Conectar uma aplicação Dify ao ARMS Application Monitoring - Application Real-Time Monitoring Service: Central de Documentação do Alibaba Cloud

O Application Real-Time Monitoring Service (ARMS) permite monitorar aplicações Dify com um Python agent. Desenvolvido pela Alibaba Cloud, esse agente coleta dados de aplicações Python e oferece instrumentação automática baseada no padrão OpenTelemetry.

Etapa 1: Implantar uma aplicação Dify em um cluster de contêineres

Crie uma aplicação Dify seguindo as instruções em Criar um assistente personalizado de perguntas e respostas com IA usando o Dify.
No cluster do Container Service for Kubernetes (ACK) que hospeda sua aplicação Dify, instale o assistente de instalação de agente (ack-onepilot), conceda permissões de acesso aos recursos do ARMS e ative o Application Monitoring. Para mais informações, consulte Instalar o Python agent do ARMS em clusters ACK e ACS.

Etapa 2: Criar o item de configuração dify-bootstrap

Prepare um script de inicialização do Dify. Esse script baixa e instala o agente e, em seguida, inicia a aplicação Dify.

Obtenha o script original do dify e aplique as seguintes modificações:

Adicione os comandos de download e instalação do agente no início do script.

python3 -m ensurepip --upgrade
pip3 config set global.index-url https://mirrors.aliyun.com/pypi/simple/ && pip3 config set install.trusted-host mirrors.aliyun.com
pip3 install aliyun-bootstrap && aliyun-bootstrap -a install

Na seção de inicialização, ao final do script, adicione o comando de início aliyun-instrument.

Expandir para visualizar o script de exemplo completo

#!/bin/bash

set -e
python3 -m ensurepip --upgrade
pip3 config set global.index-url https://mirrors.aliyun.com/pypi/simple/ && pip3 config set install.trusted-host mirrors.aliyun.com
pip3 install aliyun-bootstrap && aliyun-bootstrap -a install

mkdir -p logs

if [[ "${MODE}" == "worker" ]]; then

  # Get the number of available CPU cores
  if [ "${CELERY_AUTO_SCALE,,}" = "true" ]; then
    # Set MAX_WORKERS to the number of available cores if not specified
    AVAILABLE_CORES=$(nproc)
    MAX_WORKERS=${CELERY_MAX_WORKERS:-$AVAILABLE_CORES}
    MIN_WORKERS=${CELERY_MIN_WORKERS:-1}
    CONCURRENCY_OPTION="--autoscale=${MAX_WORKERS},${MIN_WORKERS}"
  else
    CONCURRENCY_OPTION="-c ${CELERY_WORKER_AMOUNT:-1}"
  fi

  exec celery -A app.celery worker -P ${CELERY_WORKER_CLASS:-gevent} $CONCURRENCY_OPTION --loglevel ${LOG_LEVEL} \
    -Q ${CELERY_QUEUES:-dataset,generation,mail,ops_trace,app_deletion}

else
  if [[ "${DEBUG}" == "true" ]]; then
    exec flask run --host=${DIFY_BIND_ADDRESS:-0.0.0.0} --port=${DIFY_PORT:-5001} --debug
  else
    exec aliyun-instrument gunicorn \
      --bind "${DIFY_BIND_ADDRESS:-0.0.0.0}:${DIFY_PORT:-5001}" \
      --workers ${SERVER_WORKER_AMOUNT:-1} \
      --worker-class ${SERVER_WORKER_CLASS:-gevent} \
      --timeout ${GUNICORN_TIMEOUT:-200} \
      --access-logfile logs/gunicorn_access.log \
      --error-logfile logs/gunicorn_error.log \
      --access-logformat '%(h)s|%(l)s|%(u)s|%(t)s|%(r)s|%(s)s|%(b)s|%(f)s|%(a)s|DURATION:%(L)s' \
      --log-level info \
      app:app
  fi
fi

Adicione um item de configuração no console do ACK.
1. Faça login no console do Container Service for Kubernetes. Na página Clusters, clique em Create.
2. No painel de navegação à esquerda, escolha Configurations > ConfigMaps. No namespace dify-system, clique em Create.
  - ConfigMap Name: dify-bootstrap (exemplo)
  - Name: entrypoint.sh
  - Value: O script do Dify criado na etapa anterior.
3. Clique em OK para salvar o item de configuração.

Etapa 3: Editar ack-dify-api

Na página Workloads > Deployments do cluster desejado, acesse o namespace dify-system. Localize ack-dify-api e clique em Edit na coluna Actions.

Na seção Environment Variable, clique em Add e inclua as variáveis abaixo.

Type	Variable Name	Variable	Description
Custom	GEVENT_ENABLE	true	Obrigatório.
Custom	OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT	true	Coleta o conteúdo de entrada e saída. Valor padrão: true. A coleta vem ativada por padrão. Se desativada, quando um usuário envia uma consulta, o agente coleta apenas o tamanho de campos como entrada e saída para modelos, ferramentas e bases de conhecimento, mas não o conteúdo desses campos.
Custom	PROFILER_GENAI_SPLITAPP_ENABLE	false	Divide aplicações de modelos grandes. Valor padrão: false. As aplicações não são divididas por padrão. Se ativado, os dados reportados são divididos em subaplicações de Large Language Model (LLM). Cada aplicação de modelo grande, como um Workflow, Agent ou Chat App do Dify, corresponde a uma aplicação separada no ARMS.
Custom	OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT	`<integer_value>`	Limita o tamanho do conteúdo coletado. Substitua `<integer_value>` por um número inteiro que especifique o comprimento máximo de caracteres. Valor padrão: Não definido. Não há limite por padrão. Se ativado, limita o comprimento dos valores de atributo de Span reportados. Valores que excederem o tamanho especificado serão truncados.

Na seção Lifecycle, defina Start como ["/bin/bash","/app/api/docker/entrypoint.sh"].
Na seção Volume, clique em Add Local Storage.
- PV Type: Configuration Item
- Name: bootstrap
- Mount Source: dify-bootstrap
- Container Path: /app/api/docker
No canto superior direito, clique em Update para salvar a configuração.

Após instalar o agente, visualize os dados de monitoramento na página LLM Application Monitoring > Application List do console do ARMS. Para mais informações, consulte Visualizar dados de monitoramento.

Importante
Certifique-se de que a aplicação Dify esteja gerando dados.

Etapa 4: Monitorar dify-plugin-daemon

O Dify-Plugin-Daemon é o gerenciador de plugins do Dify, responsável por executar os modelos de linguagem grande (LLMs), plugins e políticas de Agent da plataforma. Use o Go Agent para monitorar o Dify-Plugin-Daemon. Para ativar o monitoramento Go, modifique o Dockerfile, recompile a imagem e configure as variáveis de ambiente. Se necessário, o Go agent para o Dify-Plugin-Daemon também pode montar um Python agent para o runtime do plugin. Para conectar o agente, execute as etapas a seguir:

Modifique o Dockerfile e recompile a imagem correspondente.

Por exemplo, aplique as seguintes alterações no arquivo local.dockerfile:

Não monitorar o plugin Python

Caso não precise monitorar o plugin Python, modifique o Dockerfile conforme abaixo:

FROM golang:1.23-alpine AS builder

ARG VERSION=unknown

# Copy the project.
COPY . /app

# Set the working directory.
WORKDIR /app

# Use goproxy if you have network issues.
# ENV GOPROXY=https://goproxy.cn,direct

# Download ARMS instgo.
RUN wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo

RUN chmod 777 instgo

# Build with instgo.
RUN ./instgo go build \
    -ldflags "\
    -X 'github.com/langgenius/dify-plugin-daemon/internal/manifest.VersionX=${VERSION}' \
    -X 'github.com/langgenius/dify-plugin-daemon/internal/manifest.BuildTimeX=$(date -u +%Y-%m-%dT%H:%M:%S%z)'" \
    -o /app/main cmd/server/main.go

# Copy entrypoint.sh.
COPY entrypoint.sh /app/entrypoint.sh
RUN chmod +x /app/entrypoint.sh

FROM ubuntu:24.04

WORKDIR /app

# Check build arguments.
ARG PLATFORM=local

# Install Python 3.12 if PLATFORM is set to local.
RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y curl python3.12 python3.12-venv python3.12-dev python3-pip ffmpeg build-essential \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* \
    && update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1;

# Preload tiktoken.
ENV TIKTOKEN_CACHE_DIR=/app/.tiktoken

# Install dify_plugin to speed up environment setup, test uv, and preload tiktoken.
RUN mv /usr/lib/python3.12/EXTERNALLY-MANAGED /usr/lib/python3.12/EXTERNALLY-MANAGED.bk \
    && python3 -m pip install uv \
    && uv pip install --system dify_plugin \
    && python3 -c "from uv._find_uv import find_uv_bin;print(find_uv_bin());" \
    && python3 -c "import tiktoken; encodings = ['o200k_base', 'cl100k_base', 'p50k_base', 'r50k_base', 'p50k_edit', 'gpt2']; [tiktoken.get_encoding(encoding).special_tokens_set for encoding in encodings]"

ENV UV_PATH=/usr/local/bin/uv
ENV PLATFORM=$PLATFORM
ENV GIN_MODE=release

COPY --from=builder /app/main /app/entrypoint.sh /app/

# Run the server. Use sh as the entrypoint to prevent the process from becoming the root process.
# Use bash to recycle resources.
CMD ["/bin/bash", "-c", "/app/entrypoint.sh"]

Monitorar o plugin Python

Para monitorar o plugin Python, modifique o Dockerfile da seguinte forma:

FROM golang:1.23-alpine AS builder

ARG VERSION=unknown

# Copy the project.
COPY . /app

# Set the working directory.
WORKDIR /app

# Use goproxy if you have network issues.
# ENV GOPROXY=https://goproxy.cn,direct

# Download ARMS instgo.
RUN wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo

RUN chmod 777 instgo

# Build with instgo.
RUN INSTGO_EXTRA_RULES="dify_python" ./instgo go build \
    -ldflags "\
    -X 'github.com/langgenius/dify-plugin-daemon/internal/manifest.VersionX=${VERSION}' \
    -X 'github.com/langgenius/dify-plugin-daemon/internal/manifest.BuildTimeX=$(date -u +%Y-%m-%dT%H:%M:%S%z)'" \
    -o /app/main cmd/server/main.go

# Copy entrypoint.sh.
COPY entrypoint.sh /app/entrypoint.sh
RUN chmod +x /app/entrypoint.sh

FROM ubuntu:24.04

WORKDIR /app

# Check build arguments.
ARG PLATFORM=local

# Install Python 3.12 if PLATFORM is set to local.
RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y curl python3.12 python3.12-venv python3.12-dev python3-pip ffmpeg build-essential \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* \
    && update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1;

# Preload tiktoken.
ENV TIKTOKEN_CACHE_DIR=/app/.tiktoken

# Install dify_plugin to speed up environment setup, test uv, and preload tiktoken.
RUN mv /usr/lib/python3.12/EXTERNALLY-MANAGED /usr/lib/python3.12/EXTERNALLY-MANAGED.bk \
    && python3 -m pip install uv \
    && uv pip install --system dify_plugin \
    && python3 -c "from uv._find_uv import find_uv_bin;print(find_uv_bin());" \
    && python3 -c "import tiktoken; encodings = ['o200k_base', 'cl100k_base', 'p50k_base', 'r50k_base', 'p50k_edit', 'gpt2']; [tiktoken.get_encoding(encoding).special_tokens_set for encoding in encodings]"

ENV UV_PATH=/usr/local/bin/uv
ENV PLATFORM=$PLATFORM
ENV GIN_MODE=release

COPY --from=builder /app/main /app/entrypoint.sh /app/

# Run the server. Use sh as the entrypoint to prevent the process from becoming the root process.
# Use bash to recycle resources.
CMD ["/bin/bash", "-c", "/app/entrypoint.sh"]

Implante a aplicação dify-plugin-daemon e reporte os dados de monitoramento.
Implantação conteinerizada

No arquivo YAML da aplicação dify-plugin-daemon, adicione os seguintes labels no caminho spec.template.metadata.
```
labels:
  aliyun.com/app-language: golang
  armsPilotAutoEnable: 'on'
  armsPilotCreateAppName: "dify-daemon-plugin"
```
Implantação não conteinerizada

Ao implantar o componente, adicione as variáveis de ambiente a seguir.
```
ARMS_LICENSE_KEY: xxx // The ARMS LicenseKey for your account
ARMS_REGION_ID: cn-heyuan // The ID of the region
ARMS_ENABLE: true
ARMS_APP_NAME: dify-plugin-daemon
```
Obtenha a LicenseKey chamando a operação da OpenAPI DescribeTraceLicenseKey.
Visualize os dados de monitoramento do dify-plugin-daemon.

Na página Application List, localize a aplicação dify-plugin-daemon. Os detalhes de monitoramento aparecem da seguinte forma:

Detalhes do trace:

(Opcional) Etapa 5: Monitorar dify-sandbox

A partir da versão 1.0.0, o Dify introduziu o dify-sandbox para gerenciar ciclos de vida de plugins e chamadas de tarefas em segundo plano. Para monitorar esse componente, siga as etapas abaixo:

Modifique o arquivo ./build/build_[amd64|arm64].sh.

Adicione o comando de download do instgo ao arquivo.

Abaixo está um exemplo de comando de download. Para comandos referentes a outras regiões e arquiteturas, consulte Baixar instgo.
```
wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo
chmod 777 instgo
```
Insira o comando instgo antes do comando go build.

Veja a seguir um exemplo do script modificado para amd64:

rm -f internal/core/runner/python/python.so
rm -f internal/core/runner/nodejs/nodejs.so
rm -f /tmp/sandbox-python/python.so
rm -f /tmp/sandbox-nodejs/nodejs.so
wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo
chmod 777 instgo
echo "Building Python lib"
CGO_ENABLED=1 GOOS=linux GOARCH=amd64 ./instgo go build -o internal/core/runner/python/python.so -buildmode=c-shared -ldflags="-s -w" cmd/lib/python/main.go &&
echo "Building Nodejs lib" &&
CGO_ENABLED=1 GOOS=linux GOARCH=amd64 ./instgo go build -o internal/core/runner/nodejs/nodejs.so -buildmode=c-shared -ldflags="-s -w" cmd/lib/nodejs/main.go &&
echo "Building main" &&
GOOS=linux GOARCH=amd64 ./instgo go build -o main -ldflags="-s -w" cmd/server/main.go
echo "Building env"
GOOS=linux GOARCH=amd64 ./instgo go build -o env -ldflags="-s -w" cmd/dependencies/init.go

Compile a imagem.

Por exemplo, para amd64:

docker build -t sandbox:0.2.9  -f docker/amd64/dockerfile .

Implante a aplicação dify-sandbox e reporte os dados de monitoramento.
Implantação conteinerizada

No arquivo YAML da aplicação dify-sandbox, adicione os seguintes labels no caminho spec.template.metadata.
```
labels:
  aliyun.com/app-language: golang
  armsPilotAutoEnable: 'on'
  armsPilotCreateAppName: "dify-sandbox"
```
Implantação não conteinerizada

Ao implantar o componente, adicione as variáveis de ambiente a seguir.
```
ARMS_LICENSE_KEY: xxx // The ARMS LicenseKey for your account
ARMS_REGION_ID: cn-heyuan // The ID of the region
ARMS_ENABLE: true
ARMS_APP_NAME: dify-sandbox
```
Obtenha a LicenseKey chamando a operação da OpenAPI DescribeTraceLicenseKey.
Visualize os dados de monitoramento do dify-sandbox.

Na página Application List, localize a aplicação dify-sandbox. Os detalhes de monitoramento aparecem da seguinte forma:

Detalhes do trace:

Referência

Para mais informações sobre como especificar uma versão do Python agent, consulte Como instalar um agente de uma versão específica em uma região específica.