Coletar e inspecionar rastreamentos no Microsoft Foundry Toolkit

Use Microsoft Foundry Toolkit para Visual Studio Code para coletar rastreamentos locais ou exibir telemetria para agentes implantados no Microsoft Foundry. Um rastreamento agrupa operações registradas para uma solicitação. Cada operação é um span com tempo, status e quaisquer atributos ou eventos fornecidos pela instrumentação.

Este artigo aborda primeiro a coleta local e, em seguida, o rastreamento na nuvem para agentes implantados. Escolha a fonte de dados que corresponde à sua investigação:

Um agente hospedado executa seu código personalizado no Foundry Agent Service. A Foundry gerencia a hospedagem, mas você permanece responsável pelo código e pelas dependências. O rastreamento não substitui a criação e a implantação do agente.

Prerequisites

• Visual Studio Code com a extensão pública atual do Foundry Toolkit. Consulte Install Foundry Toolkit.
• Um aplicativo que você pode executar localmente, com seu modelo e conexões de ferramenta configuradas.
• Para o primeiro exemplo, um aplicativo do Python Microsoft Agent Framework e seu ambiente de Python selecionado. Para outros SDKs, use a configuração em Python ou em JavaScript e TypeScript.
• Para rastreamento na nuvem, é necessário ter um agente implantado e um recurso do Application Insights conectado ao projeto do Foundry, ou permissão para conectar ou criar um.
• Para consultas na nuvem, a função Leitor do Log Analytics é necessária no recurso do Application Insights conectado. Para tabelas protegidas, atribua também a função Leitor de Dados de Monitoramento Privilegiado. Consulte os pré-requisitos de rastreamento do Foundry.

A coleção local não requer permissões do Application Insights ou de telemetria de nuvem. Chamadas de modelo e execução de ferramentas ainda podem usar serviços remotos e incorrer em encargos.

Coletar rastros locais

O coletor local recebe telemetria pelo Protocolo OpenTelemetry (OTLP). Ele não instrumenta um aplicativo automaticamente. Seu framework ou uma biblioteca de instrumentação deve criar spans e exportá-los para o coletor.

SDK e configuração de idioma

Os SDKs com instrumentação interna ainda precisam de um exportador. Outros SDKs usam um pacote de instrumentação separado.

"Nenhuma orientação de instalação dedicada do Kit de Ferramentas" significa que não há nenhum caminho de instalação específico do SDK aqui para esse idioma, não que o coletor rejeite sua telemetria. O coletor aceita dados OTLP. O instrumentor determina quais operações e detalhes da mensagem são capturados.

Esses exemplos usam opções de instrumentação selecionadas, não uma lista completa de bibliotecas compatíveis. A instrumentação OpenLLMetry e Traceloop é uma biblioteca que não é da Microsoft.

Configurar instrumentação

Use este procedimento com um aplicativo existente do Python Agent Framework. Mantenha o agente e o coletor no mesmo ambiente local para este passo a passo.

1. Selecione Foundry Toolkit na Barra de Atividades e, em seguida, Ferramentas de Desenvolvedor>>.

2. Selecione Iniciar Coletor antes de executar seu aplicativo.

3. No ambiente de Python do aplicativo, instale o exportador gRPC se ele ainda não estiver declarado em suas dependências:

   python -m pip install opentelemetry-exporter-otlp-proto-grpc
   

   Referência: exportadores OTLP do OpenTelemetry Python.

4. Configure o OpenTelemetry uma vez na inicialização do aplicativo, antes de construir ou executar o agente:

   import os
   
   os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "http://localhost:4317"
   os.environ["OTEL_EXPORTER_OTLP_PROTOCOL"] = "grpc"
   
   from agent_framework.observability import configure_otel_providers
   
   configure_otel_providers(enable_sensitive_data=False)
   

   Referência: observabilidade do Agent Framework.

   Se seu aplicativo ou biblioteca de hospedagem já configurar provedores OpenTelemetry, configure seus exportadores existentes em vez de adicionar outra configuração de provedor. As variáveis específicas OTEL_EXPORTER_OTLP_*_ENDPOINT do sinal podem substituir o endpoint base. Verifique se há configurações de rastreamento, log ou métrica existentes que apontam para outro lugar.

5. Execute o aplicativo com seu ponto de entrada normal e envie uma solicitação que acione o agente. Permita que a solicitação seja concluída e dê ao exportador tempo para enviar telemetria antes de interromper o processo.

6. No Rastreamento, selecione Atualizar e selecione o novo rastreamento para inspecionar seus spans.

O Agent Framework oferece instrumentação para clientes de modelo, agentes e operações de fluxo de trabalho. Outros frameworks podem exigir uma biblioteca de instrumentação. A compatibilidade do OTLP permite que o coletor receba dados, enquanto atributos emitidos e convenções semânticas de IA gerativas determinam o que o visualizador exibe.

Para outro SDK ou idioma, use a configuração abaixo em vez da configuração do Agent Framework. Inicie o coletor primeiro, configure a instrumentação antes de criar clientes, execute seu aplicativo e atualize a lista de rastreamento.

endpoints do coletor

Associe o protocolo do exportador ao ponto de extremidade do coletor. O Toolkit escuta no localhost com estes padrões:

Alguns exportadores HTTP aceitam http://localhost:4318 e acrescentam o caminho do sinal em si. Siga a configuração do exportador em vez de acrescentar o caminho duas vezes. Algumas bibliotecas de instrumentação enviam o conteúdo das mensagens como registros de log, portanto exportar apenas spans pode não fornecer detalhes de entrada e de saída.

Essas portas estão relacionadas ao servidor HTTP do agente e às portas do depurador. Em um contêiner ou ambiente de desenvolvimento remoto, localhost refere-se a esse ambiente. Estabeleça a conexão apropriada com o coletor em vez de supor que ele se refira à sua área de trabalho.

configuração do SDK do Python

Os exemplos a seguir pressupõem que seu aplicativo já tenha o SDK do modelo, as credenciais e a configuração do modelo. Instale as dependências compartilhadas e o pacote adicional para o seu SDK da tabela a seguir:

python -m pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

Referência: OpenTelemetry Python SDK, exportadores OTLP.

Adicione essa configuração compartilhada uma vez na inicialização do aplicativo, seguida pela instrumentação de uma das linhas da tabela. Não o combine com a configuração do provedor de outra biblioteca.

import os

os.environ["TRACELOOP_TRACE_CONTENT"] = "false"
os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "false"
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "false"

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
    OTLPSpanExporter,
)

provider = TracerProvider(
    resource=Resource.create({"service.name": "my-agent"})
)
provider.add_span_processor(BatchSpanProcessor(
    OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
))
trace.set_tracer_provider(provider)

Referência: TracerProvider e processadores de span, OTLPSpanExporter.

Instale o pacote na linha selecionada usando python -m pip install <package>. Os exemplos da OpenAI, da Anthropic, da LangChain e os exemplos separados do OpenAI Agents usam instrumentação OpenLLMetry que não é da Microsoft. As versões do SDK e as APIs de modelo podem produzir detalhes diferentes.

Para projetos Foundry, siga as diretrizes de rastreamento do lado do cliente e crie seu cliente OpenAI após a instrumentação. Essa orientação difere do SDK de Agentes clássico. Não instrumente as mesmas chamadas OpenAI com ambos AIProjectInstrumentor e um instrumentor OpenAI separado.

Para o SDK do OpenAI Agents, instale opentelemetry-instrumentation-openai-agents e adicione este código após a configuração compartilhada:

from agents import set_trace_processors
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor

set_trace_processors([])
OpenAIAgentsInstrumentor().instrument()

Referência: instrumentação de Agentes OpenAI, rastreamento de Agentes OpenAI.

Este exemplo substitui os processadores de rastreamento existentes antes de adicionar o processador OpenTelemetry. Sem essa substituição, o SDK também pode exportar rastreamentos para seu back-end padrão. Se você precisar usar os processadores existentes, examine os destinos de rastreamento antes de alterá-los. Mantenha o rastreamento do SDK habilitado para que o processador OpenTelemetry receba eventos.

Depois que um aplicativo de curta duração concluir suas solicitações, chame provider.force_flush() antes de sair para enviar spans em buffer. Para obter ajuda para adaptar esses snippets, use a ferramenta Tracing Code Gen do Kit de Ferramentas.

Exportar registros de log de mensagens

Alguns instrumentors emitem conteúdo da mensagem como registros de log OpenTelemetry em vez de atributos de span. Se você optar por registrar esse conteúdo em um teste de desenvolvimento controlado, adicione essa configuração uma vez ao lado do provedor de rastreamento Python anterior:

from opentelemetry import _logs
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

logger_provider = LoggerProvider(resource=provider.resource)
logger_provider.add_log_record_processor(BatchLogRecordProcessor(
    OTLPLogExporter(endpoint="http://localhost:4318/v1/logs")
))
_logs.set_logger_provider(logger_provider)

Referência: OpenTelemetry Python SDK de log, OTLPLogExporter.

Chame logger_provider.force_flush() antes de sair de um aplicativo de curta duração. Um exportador de logs não ativa a captura de conteúdo por si só. Siga as configurações de conteúdo do instrumentador e as diretrizes de manipulação de dados.

Configuração do SDK do JavaScript e typeScript

Para aplicativos Node.js, compartilhe o mesmo provedor de rastreamento e registre a instrumentação para seu SDK. Este exemplo usa CommonJS e a configuração do provedor OpenTelemetry JavaScript 2.x. Os aplicativos TypeScript compilados para CommonJS podem usar a mesma ordem de inicialização.

Seu aplicativo já deve ter seu SDK do modelo, credenciais e configuração do modelo. Instale as dependências compartilhadas e o instrumentor OpenAI:

npm install @opentelemetry/api @opentelemetry/sdk-trace-node \
  @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/instrumentation @traceloop/instrumentation-openai

Referência: exportadores JavaScript OpenTelemetry, instrumentação OpenAI.

Criar tracing.cjs:

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const {
  OTLPTraceExporter
} = require('@opentelemetry/exporter-trace-otlp-proto');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { OpenAIInstrumentation } = require('@traceloop/instrumentation-openai');

const provider = new NodeTracerProvider({
  spanProcessors: [
    new BatchSpanProcessor(new OTLPTraceExporter({
      url: 'http://localhost:4318/v1/traces'
    }))
  ]
});
provider.register();

registerInstrumentations({
  instrumentations: [new OpenAIInstrumentation({ traceContent: false })]
});

module.exports = provider;

Referência: NodeTracerProvider, instrumentação OpenAI.

Carregue esse arquivo antes de importar ou requerer o SDK do modelo. Por exemplo, execute node --require ./tracing.cjs app.cjs para um aplicativo CommonJS. Para outro SDK, substitua o pacote OpenAI, a importação e a entrada de registro pela linha correspondente:

Os pacotes Traceloop são instrumentação não Microsoft. Para um aplicativo Foundry Projects, instrumente o cliente que faz a solicitação ao modelo. A instrumentação do SDK do Azure não substitui a instrumentação OpenAI para chamadas feitas por meio de um cliente OpenAI.

Para módulos ECMAScript nativos, siga a configuração de ESM do OpenTelemetry. O carregamento da instrumentação após o SDK de destino pode deixar as chamadas não instrumentadas. No desligamento, aguarde provider.shutdown() após a conclusão das solicitações para exportar spans em buffer.

Inspecionar e gerenciar rastros locais

Use a árvore de spans para seguir a solicitação da orquestração do agente para operações de modelo e ferramenta.

1. Selecione um span lento ou com falha.
2. Verifique sua duração e estado.
3. Abra Entrada + Saída para mensagens gravadas, quando fornecidas pela instrumentação, ou Metadados para atributos de span.

Os exemplos mantêm a captura de conteúdo confidencial desativada. Dados de tempo sem mensagens podem ser o resultado esperado.

Para um teste controlado de desenvolvimento do Agent Framework, defina enable_sensitive_data=True em sua configuração existente para registrar conteúdo de prompt, resposta e ferramenta compatível. Restaure-o para False quando o teste for concluído. Outros instrumentadores têm suas próprias configurações de conteúdo.

Os rastreamentos coletados persistem em um banco de dados SQLite local chamado traces.db, no subdiretório tracing de .aitk na pasta pessoal do usuário. Fechar o visualizador não os exclui.

Selecione Parar Coletor para interromper a coleção local. Seu agente e suas chamadas de modelo continuam em execução. Para remover registros locais, selecione os rastreamentos na lista e selecione Excluir.

O armazenamento local é separado do Application Insights. Excluir rastreamentos locais não remove a telemetria de nuvem e limpar uma conversa no Inspetor não exclui nenhum dos repositórios.

Exibir rastreamentos de agente hospedado

Após a implantação, use rastreamentos de nuvem para investigar o agente em execução no Foundry em vez do processo local. O Kit de Ferramentas consulta o recurso do Application Insights conectado do projeto. Ele não carrega seu banco de dados de rastreamento local.

Confirme os pré-requisitos de nuvem antes de começar. O acesso ao agente sozinho não concede permissão para consultar a telemetria.

Conectar o Application Insights e inspecionar uma solicitação

Use a aba Rastreamentos do agente para conectar o Application Insights e encontrar uma solicitação de um agente implantado.

1. Na barra lateral do Foundry Toolkit, abra Meus Agentes de Recursos>. Selecione a guia Agente Hospedado e selecione o nome do agente.

2. Selecione Rastreios. Se o projeto não tiver nenhum recurso conectado, selecione Habilitar o App Insights.

3. Nas Configurações do App Insights, selecione um Nome de Recurso do Application Insights existente. Como alternativa, escolha criar um recurso e conclua os campos de recurso e workspace necessários. Selecione Enviar e aguarde a confirmação.

   Isso altera a conexão compartilhada do Application Insights do projeto, não uma preferência de workspace local. A criação de recursos e a coleta de telemetria podem gerar cobranças do Azure. Confirme o projeto e o recurso desejados antes de enviar.

4. Retorne ao Playground e envie uma solicitação de teste para o agente implantado.

5. Dê tempo para ingestão e, em seguida, abra Traces novamente. Use os filtros de intervalo de tempo, pesquisar por ID de conversa, status ou duração para localizar a solicitação.

   

6. Selecione um trace e, em seguida, um span, para examinar Metadados e Entrada + Saída, quando o conteúdo estiver disponível.

Para inspecionar as operações associadas a uma conversa, selecione sua ID de Conversa na lista de rastreamento. O modo de exibição de conversa mostra uma árvore de operações e metadados.

Conectar o Application Insights habilita o rastreamento do lado do servidor do Foundry. A visibilidade de suas chamadas de modelo, chamadas de ferramenta e código personalizado também depende da biblioteca de hospedagem e da instrumentação do framework. Consulte Configurar o rastreamento na Foundry para coleção do lado do serviço e instrumentação de cliente adicional.

A consulta de detalhes de rastreamento do Toolkit atualmente abrange os últimos sete dias. Esta é uma janela de consulta, não uma configuração de retenção. Para dados mais antigos, use o portal do Foundry ou Azure Monitor, sujeito à configuração de retenção do workspace conectado.

Dados, acesso, retenção e custo

Decida para onde a telemetria deve ir antes de habilitar a captura de conteúdo ou conectar um recurso de nuvem. A mesma solicitação pode gerar spans locais, telemetria na nuvem e dados enviados para provedores de modelos ou de ferramentas.

Use as orientações de rastreamento do Foundry para segurança e privacidade e retenção de dados e custos. Para identidade de produção, isolamento de rede e acesso downstream, siga a segurança do agente hospedado e o tratamento de dados. Não trate as credenciais locais como permissões do agente implantado.

Troubleshooting

Conteúdo relacionado

• Depurar agentes com o Agent Inspector.
• Conceitos de rastreamento de agente.
• Configure o rastreamento do lado do cliente.