Application Real-Time Monitoring Service:Controlar a coleta do histórico de conversas

Comportamento de coleta e formato dos dados

Por padrão, o probe armazena mensagens de entrada, mensagens de saída, instruções do sistema e definições de ferramentas como JSON nos atributos do span.

Configuração

• Configure usando as variáveis de ambiente abaixo:

  Nome da variável de ambiente	Valor
  OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT	True
  OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_CAPTURE_STRATEGY	"span-attributes"

• Em aplicações Java, também é possível definir propriedades de sistema no comando de inicialização. Exemplo:

  -Dotel.instrumentation.genai.capture-message-content=true \
  -Dotel.instrumentation.genai.message-content.capture-strategy=span-attributes

Exemplo

[
  {
    "role": "user",
    "parts": [
      {
        "type": "text",
        "content": "Weather in Paris?"
      }
    ]
  }
]

[
  {
    "role": "assistant",
    "parts": [
      {
        "type": "tool_call",
        "id": "call_VSPygqKTWdrhaFErNvMV18Yl",
        "name": "get_weather",
        "arguments": {
          "location": "Paris"
        }
      }
    ],
    "finish_reason": "tool_call"
  }
]

[
  {
    "type": "function",
    "name": "get_weather",
    "description": "Get the current temperature for a specific location."
  }
]

[
  {
    "role": "user",
    "parts": [
      {
        "type": "text",
        "content": "Weather in Paris?"
      }
    ]
  },
  {
    "role": "assistant",
    "parts": [
      {
        "type": "tool_call",
        "id": "call_VSPygqKTWdrhaFErNvMV18Yl",
        "name": "get_weather",
        "arguments": {
          "location": "Paris"
        }
      }
    ]
  },
  {
    "role": "tool",
    "parts": [
      {
        "type": "tool_call_response",
        "id": "call_VSPygqKTWdrhaFErNvMV18Yl",
        "response": "rainy, 57°F"
      }
    ]
  }
]

[
  {
    "role": "assistant",
    "parts": [
      {
        "type": "text",
        "content": "The weather in Paris is currently rainy with a temperature of 57°F."
      }
    ],
    "finish_reason": "stop"
  }
]

Comportamento de coleta e formato dos dados

Neste modo, o probe não registra mensagens de entrada, mensagens de saída nem instruções do sistema. Para definições de ferramentas, apenas informações básicas são gravadas em formato JSON.

Configuração

• Defina esta variável de ambiente:

  Nome da variável de ambiente	Valor
  OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT	False

• Para aplicações Java, adicione a seguinte propriedade de sistema ao comando de inicialização:

  -Dotel.instrumentation.genai.capture-message-content=false

Exemplo

[
  {
    "type": "function",
    "name": "get_weather"
  }
]

Comportamento de coleta e formato dos dados

Neste modo, os atributos do span armazenam apenas informações básicas. O agente grava dados detalhados da conversa — mensagens de entrada, mensagens de saída, instruções do sistema e definições de ferramentas — em um arquivo de log local como entradas JSON de linha única.

Ao iniciar, o agente busca um diretório de log disponível verificando os seguintes locais nesta ordem:

1. Caso um diretório seja especificado pela variável de ambiente APSARA_APM_AGENT_WORKSPACE_DIR, o agente grava os logs no subdiretório .apsara-apm/{language}/logs dentro desse caminho.

2. Diretório de log do agente: /home/admin/.opt/.apsara-apm/{language}/logs

3. Diretório home: ~/.apsara-apm/{language}/{agent_version}_{agent_commit_id}/logs

Durante a inicialização, o agente imprime o diretório de armazenamento de logs na saída padrão (stdout). Para facilitar a gestão de diretórios, especifique um caminho usando a variável de ambiente APSARA_APM_AGENT_WORKSPACE_DIR.

Picked up [/Uxxxs/tools/log/.apsara-apm/python] as Agent Workspace.

O arquivo de log do histórico de conversas recebe o nome genai_messages_{ip}_{pid}.log. O tamanho máximo do arquivo é de 256 MB. Ao atingir esse limite, ocorre o rodízio de arquivos. Apenas os dois arquivos de log mais recentes são mantidos.

Configuração

• Defina as variáveis de ambiente a seguir:

  Variável de ambiente	Valor
  OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT	True
  OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_CAPTURE_STRATEGY	event

• Em aplicações Java, também é possível adicionar propriedades de sistema ao comando de inicialização. Exemplo:

  -Dotel.instrumentation.genai.capture-message-content=true \
  -Dotel.instrumentation.genai.message-content.capture-strategy=event

Exemplo

{
  "scope": {
    "name": "aliyun.instrumentation.openai",
    "version": "1.0.1"
  },
  "timeUnixNano": 1760080084146812928,
  "severity": "UNSPECIFIED",
  "attributes": {
    "event.name": "gen_ai.client.inference.operation.details",
    "gen_ai.provider.name": "openai",
    "gen_ai.operation.name": "chat",
    "gen_ai.request.model": "gpt-4",
    "gen_ai.request.max_tokens": 200,
    "gen_ai.request.top_p": 1.0,
    "gen_ai.response.id": "chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l",
    "gen_ai.response.model": "gpt-4-0613",
    "gen_ai.usage.output_tokens": 17,
    "gen_ai.usage.input_tokens": 47,
    "gen_ai.response.finish_reasons": ["tool_calls"],
    "gen_ai.input.messages": "[{\"role\":\"user\",\"parts\":[{\"type\":\"text\",\"content\":\"Weather in Paris?\"}]}]",
    "gen_ai.output.messages": "[{\"role\":\"assistant\",\"parts\":[{\"type\":\"tool_call\",\"id\":\"call_VSPygqKTWdrhaFErNvMV18Yl\",\"name\":\"get_weather\",\"arguments\":{\"location\":\"Paris\"}}],\"finish_reason\":\"tool_call\"}]",
    "gen_ai.tool.definitions": "[{\"type\":\"function\",\"name\":\"get_weather\",\"description\":\"Get the current temperature for a specific location.\"}]"
  },
  "traceId": "0b46a347592ac487ed092ebe802c6818",
  "spanId": "b3c40af8cd1a522c"
}

{
  "scope": {
    "name": "aliyun.instrumentation.openai",
    "version": "1.0.1"
  },
  "timeUnixNano": 1760080084176812928,
  "severity": "UNSPECIFIED",
  "attributes": {
    "event.name": "gen_ai.client.inference.operation.details",
    "gen_ai.provider.name": "openai",
    "gen_ai.operation.name": "chat",
    "gen_ai.request.model": "gpt-4",
    "gen_ai.request.max_tokens": 200,
    "gen_ai.request.top_p": 1.0,
    "gen_ai.response.id": "chatcmpl-VSPygqKTWdrhaFErNvMV18Yl",
    "gen_ai.response.model": "gpt-4-0613",
    "gen_ai.usage.output_tokens": 52,
    "gen_ai.usage.input_tokens": 97,
    "gen_ai.response.finish_reasons": ["stop"],
    "gen_ai.input.messages": "[{\"role\":\"user\",\"parts\":[{\"type\":\"text\",\"content\":\"Weather in Paris?\"}]},{\"role\":\"assistant\",\"parts\":[{\"type\":\"tool_call\",\"id\":\"call_VSPygqKTWdrhaFErNvMV18Yl\",\"name\":\"get_weather\",\"arguments\":{\"location\": \"Paris\"}}]},{\"role\":\"tool\",\"parts\":[{\"type\":\"tool_call_response\",\"id\":\"call_VSPygqKTWdrhaFErNvMV18Yl\",\"response\":\"rainy, 57°F\"}]}]",
    "gen_ai.output.messages": "[{\"role\":\"assistant\",\"parts\":[{\"type\":\"text\",\"content\":\"The weather in Paris is currently rainy with a temperature of 57°F.\"}],\"finish_reason\":\"stop\"}]"
  },
  "traceId": "0b46a347592ac487ed092ebe802c6818",
  "spanId": "0a706a178bd746c5"
}

Etapa 1: Instalar o LoongCollector

Se o LoongCollector já estiver instalado no seu ambiente, ignore esta etapa.

Etapa 2: Criar a configuração de coleta

1. Faça login no console do Log Service. Clique em no Project desejado, expanda o Logstore onde deseja armazenar os logs e clique em no ícone ao lado de Data Import. Na seção JSON - Text Log, clique em Connect Now.

2. Selecione um machine group existente ou crie um novo para o host onde os logs estão armazenados.

   Em Scenario, selecione Host Scenario. Em Installation Environment, escolha ECS. Na lista Applied Machine Group, confirme se o machine group alvo (por exemplo, genai) foi adicionado.

3. Crie uma configuração de coleta. Em Input Configuration, substitua o File Path pelo caminho real do seu diretório de logs. Para encontrar o caminho do diretório, verifique a saída padrão da sua aplicação durante a inicialização. Em Processing Configuration, selecione a análise JSON padrão.

   Por exemplo, defina Configuration Name como playground-test-config, selecione Text Log Collection para Input Type, use um formato de caminho de arquivo como /home/admin/logs/.apsara-apm/java/**/logs/genai_messages_*.log e defina Maximum Directory Monitoring Depth como 1.

   xxx
   Picked up /home/admin/logs/.apsara-apm/java/4.6.0_4e280e61/ as Agent Workspace.
   Unable to locate the -XX:ErrorFile parameter in the JVM options.
   If you are using Kubernetes, we recommend updating ack-onepilot to version 3.2.3 or later.
   For other environments, please consider adding the following parameters manually:
   -XX:ErrorFile=/{JavaAgentDirectory}/hs_err_pid%p.log
   -XX:OnError=/{JavaAgentDirectory}/crash_log_collector.sh
   These settings will enable automatic crash log collection to ARMS, helping us monitor
    incidents and provide timely feedback.
   Please note that this reminder does not affect the functionality of ARMS.
   If you prefer not to make these changes, feel free to disregard this message.
   Apsara Java Agent start cost: 5071 ms

4. Para habilitar a recuperação e análise de dados, configure os índices da seguinte forma: Ative Full-Text Index, mas desative Case Sensitive e Include Chinese Characters. Em Query on Specified Fields, adicione índices para os seguintes campos: attributes (tipo: json; ative Case Sensitive e Include Chinese Characters), resource (tipo: json; ative Case Sensitive e Include Chinese Characters), spanId (tipo: text; desative Case Sensitive e Include Chinese Characters) e traceId (tipo: text; desative Case Sensitive e Include Chinese Characters).

Etapa 3: Visualizar os logs coletados no SLS

Após concluir a configuração inicial, os logs aparecem no Log Service (SLS) em alguns minutos:

▼ attributes: {}
    event.name: "gen_ai.client.inference.operation.details"
    gen_ai.input.messages: "[{"role":"system","parts":[{"type":"text","content":"	
xxx
xxx
xxx
:
xxx
                              xxx"}]},{"role":"user","parts":[{"type":"text","content":"xxx"}]}]"
    gen_ai.operation.name: "invoke_agent"
    gen_ai.output.messages: "[{"role":"assistant","parts":[{"type":"text","content":"
xxx
                                    "}],"finishReason":"stop"}]"
    gen_ai.provider.name: "spring-ai"
    gen_ai.request.model: "qwen-max"
    gen_ai.request.temperature: 0.8
  ► gen_ai.response.finish_reasons: []
    gen_ai.response.id: "0d98f.xxx"
    gen_ai.tool.definitions: "[{"type":"function","name":"getBookingDetails"},{"type":"function","name":"cancelBooking"},{"type":"function","name":"changeBooking"}]"
    gen_ai.usage.input_tokens: 1300
    gen_ai.usage.output_tokens: 59
body:
▼ resource: {}
  ► attributes: {}

[
  {
    "role": "assistant",
    "parts": [
      {
        "type": "text",
        "content": "The weather in Paris...[truncated]"
      }
    ],
    "finish_reason": "stop"
  }
]

Configuração

• Configure o limite usando a seguinte variável de ambiente:

  Variável de ambiente	Valor
  OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_MAX_LENGTH	8192

• Para aplicações Java, adicione uma propriedade de sistema ao comando de inicialização. Exemplo:

  -Dotel.instrumentation.genai.message-content.max-length=8192

Corpos de mensagem sujeitos a truncamento