AgentLoop:Instrumentar uma aplicação Dify

Visualizar dados de monitoramento do workflow

A página de detalhes da aplicação contém as seguintes abas: Overview, Performance Analysis, Token Analysis, LLM Operations, Provided Services, Dependent Services, Trace Analysis, Exception Analysis e Session Analysis. A aba Overview exibe os seguintes dados:

• Cartões de métricas principais: Model Calls, Token Usage (com comparação diária), Traces, Spans, Sessions e Users

• Gráfico de pizza com a distribuição de tipos de operação (TASK, TOOL, CHAIN, LLM, RETRIEVER)

• Gráficos de linhas para média de chamadas LLM por requisição, tendência de contagem de requisições e tendência de contagem de sessões

• Gráfico de barras Model Call Ranking (Top 5) e tabela Request Count User Ranking (Top 5)

Exemplo de detalhes do trace: os detalhes incluem informações de nós, como chamadas LLM, recuperação de dados e invocação de ferramentas.

A página de detalhes do trace exibe um gráfico cascata à esquerda, mostrando nós de etapas (tipos incluem CHAIN, TOOL, TASK, LLM e RETRIEVER), cada um com uma barra de tempo no gráfico de Gantt. O painel à direita apresenta informações detalhadas sobre o nó selecionado, incluindo nome da aplicação, endpoint, hostname, spanId, parentSpanId e código de status. A seção Additional Information, na parte inferior, permite visualizar o conteúdo das mensagens de entrada e saída do nó, como entrada JSON para análise de alertas e resultados de análise de causa raiz.

1. Modifique o Dockerfile e recrie a imagem correspondente. O código abaixo mostra um exemplo de local.dockerfile modificado:

   FROM golang:1.23-alpine AS builder
   
   ARG VERSION=unknown
   
   # copy project
   COPY . /app
   
   # set working directory
   WORKDIR /app
   
   # using 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
   
   # instgo build
   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 args
   ARG PLATFORM=local
   
   # Install python3.12 if PLATFORM is 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 speedup the 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, using sh as the entrypoint to avoid process being the root process
   # and using bash to recycle resources
   CMD ["/bin/bash", "-c", "/app/entrypoint.sh"]

   Nota

   A opção INSTGO_EXTRA_RULES ativa o monitoramento automático do runtime do plugin. Para impedir que o agent do plugin seja iniciado junto com o plugin-daemon, remova INSTGO_EXTRA_RULES="dify_python" do arquivo de build.

2. Configure as variáveis de ambiente:

   • Para ambientes ECS:

     Parâmetro	Valor	Descrição
     ARMS_LICENSE_KEY	xxx@xxx	Sua License Key.
     ARMS_REGION_ID	cn-heyuan	ID da sua região.
     ARMS_ENABLE	true	Ativa ou desativa o agent.
     ARMS_APP_NAME	dify-plugin-daemon	Nome da aplicação.

   • Para ambientes containerizados com ack-onepilot: na configuração YAML da aplicação dify-plugin-daemon, adicione os seguintes rótulos em spec.template.metadata.

     labels:
       aliyun.com/app-language: golang
       armsPilotAutoEnable: 'on'
       armsPilotCreateAppName: "dify-daemon-plugin"

3. Implante e visualize os dados de monitoramento do dify-plugin-daemon. Na página de lista de aplicações, acesse a aplicação dify-plugin-daemon. A página de visão geral da aplicação exibe as seguintes informações:

   • Cartões de métricas: Requests, Errors, Average Latency e Instances, com variações diárias e semanais

   • Gráficos de tendência: gráfico de barras Requests/1m, gráfico de linhas Errors/1m, gráfico de linhas Latency/1m (com percentis P99, P90 e P75) e gráfico de anel Peak CPU Utilization

   • Painéis de ranking Top 5: Request Count, Error Count, Average Latency e Peak CPU Utilization by Instance

   O gráfico cascata do trace mostra os detalhes da cadeia de chamadas do insight-agent-plugin-daemon. Os principais spans incluem:

   • GET (python/redis, 1,95 ms)

   • connect (python/sqlalchemy)

   • SELECT dify (sqlalchemy, 34,95 ms)

   • Chamadas em múltiplas camadas de /v1/sandbox/run (POST httpx → SERVER go net_http_server → INTERNAL, aproximadamente 28–30 ms)

   • UPDATE dify (sqlalchemy, 2,38 ms)

   O painel de detalhes à direita exibe hostname, hora de início, hora de término, spanId, parentSpanId, código de status e uma lista de Attributes (como net.protocol.name, component.name e endpoint) para o span selecionado.

4. Visualize os dados de monitoramento dos plugins. Após instale o agent, o plugin-daemon inicia automaticamente o agent para o runtime do plugin. Cada runtime de plugin corresponde a uma aplicação observável separada, nomeada no formato {plugin_daemon_name}_plugin_{plugin_name}_{plugin_version}. Por exemplo, se sua aplicação plugin-daemon se chama local-dify-plugin-daemon e você instalou a versão 0.0.53 do plugin tongyi, uma aplicação chamada local-dify-plugin-daemon_plugin_tongyi_0.0.53 será criada automaticamente. A página de visão geral do monitoramento de plugins exibe as seguintes informações:

   • Abas superiores: Application Overview, Application Topology, Provided Services, Dependent Services, Trace Analysis, Instance Monitoring, Scenario Analysis e Application Configuration

   • Cartões de métricas principais: requisições, erros, latência média e instâncias (com variações diárias e semanais)

   • Gráficos de séries temporais: tendências para contagem de requisições, contagem de erros, latência e pico de utilização de CPU

   • Rankings Top 5: contagem de requisições, contagem de erros e latência média, exibindo chamadas no nível de endpoint do plugin (como invoke_llm, get_ai_model_schemas e invoke_rerank)

1. Modifique o arquivo build/build_[amd64|arm64].sh e recrie a imagem correspondente.

   1. Adicione o comando para baixe o instgo. O código abaixo mostra um exemplo. Para comandos de download de outras regiões e arquiteturas, consulte Download instgo.

      wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo
      chmod 777 instgo

   2. Insira o comando instgo antes de go build. O código abaixo mostra um exemplo para a arquitetura 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
      

2. Configure as variáveis de ambiente.

   • Para implantações em containers K8s: na configuração YAML da aplicação dify-plugin-daemon, adicione os seguintes rótulos em spec.template.metadata.

     labels:
       aliyun.com/app-language: golang
       armsPilotAutoEnable: 'on'
       armsPilotCreateAppName: "dify-daemon-plugin"
     

   • Para integração manual:

     Parâmetro	Valor	Descrição
     ARMS_LICENSE_KEY	xxx	Sua License Key.
     ARMS_REGION_ID	cn-heyuan	ID da sua região.
     ARMS_ENABLE	true	Ativa ou desativa o agent.
     ARMS_APP_NAME	dify-plugin-daemon	Nome da aplicação.

3. Implante e visualize os dados de monitoramento do sandbox. Na página de lista de aplicações, acesse a aplicação dify-sandbox. A aba Application Overview exibe as seguintes métricas resumidas:

   • Requests: 3.051,00 (1,60% em relação ao dia anterior)

   • Errors: 0,00 (0% em relação ao dia anterior)

   • Average Latency: 47,7 ms (1,36% em relação ao dia anterior)

   • Instances: 9 (0% em relação à semana anterior)

   Os gráficos de séries temporais mostram Requests/1m, Errors/1m, Latency/1m (com curvas P99, P90 e P75) e utilização de CPU. O ranking Top 5 Provided Services indica o caminho principal de requisições como /v1/sandbox/run, com 3.051 requisições, 0 erros e latência média de 47,7 ms.

   A página de detalhes de trace do ARMS mostra um trace com duração total de 8,7 segundos, abrangendo 5 aplicações e 1.039 endpoints, com anomalias detectadas. As tags de componentes incluem redis (575), sqlalchemy (337), net_http_server (16) e httpx (14). O gráfico cascata de spans ilustra a cadeia de chamadas em múltiplas camadas, desde SELECT dify até /v1/sandbox/run POST 200, demonstrando o caminho completo da chamada do Dify ao sandbox. O painel de detalhes do span exibe o nome da aplicação insight-agent-sandbox, endpoint /v1/sandbox/run, hostname sandbox-7489d68cd5-xcqv8, com código de status normal. A seção Attributes apresenta campos como net.protocol.name, component.name e outras informações detalhadas.