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

Comportamento de coleta e formato de dados

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

Configuração

• Configure usando as seguintes variáveis de ambiente:

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

• Para aplicações Java, também é possível configurar isso com propriedades de sistema no comando de inicialização, por 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 de dados

Neste modo, o probe não registra mensagens de entrada, mensagens de saída ou instruções do sistema. Para definições de ferramentas, apenas informações básicas são registradas 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 de dados

Neste modo, os atributos de 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.

Por padrão, ao iniciar, o agente busca um diretório de log disponível verificando os seguintes locais em ordem:

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

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

Na inicialização, o agente imprime o diretório de armazenamento de logs na saída padrão (stdout). Para simplificar o gerenciamento 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 seguintes variáveis de ambiente:

  Variável de ambiente	Valor
  OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT	True
  OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_CAPTURE_STRATEGY	event

• Para aplicações Java, também é possível adicionar propriedades de sistema ao comando de inicialização, por 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

Caso o LoongCollector já esteja instalado no seu ambiente, ignore esta etapa.

Etapa 2: Criar 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, selecione ECS. Na lista Applied Machine Group, confirme se o grupo de máquinas alvo (por exemplo, genai) foi adicionado.

3. Crie uma configuração de coleta. Em Input Configuration, substitua o File Path pelo seu diretório de log real. Para encontrar o caminho do diretório, verifique a saída padrão da sua aplicação na 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 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, por exemplo:

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

Corpos de mensagem sujeitos a truncamento