Recolha e inspecione rastreios no Microsoft Foundry Toolkit

Use Microsoft Foundry Toolkit para Visual Studio Code para recolher traços locais ou visualizar telemetria para agentes implementados em Microsoft Foundry. Um trace agrupa operações registadas 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 recolha local e depois o rastreio na cloud para agentes implantados. Escolha a fonte de dados que corresponda à sua investigação:

Um agente alojado executa o seu código personalizado no Foundry Agent Service. A Foundry gere o alojamento, mas tu continuas responsável pelo código e pelas dependências. O rastreamento não substitui a criação e implementação de agentes.

Prerequisites

• Visual Studio Code com a atual extensão pública Foundry Toolkit. Consulte Instalar o Foundry Toolkit.
• Uma aplicação que pode correr localmente, com as ligações ao modelo e à ferramenta configuradas.
• Para o primeiro exemplo, uma aplicação Python Microsoft Agent Framework e o seu ambiente Python selecionado. Para outros SDKs, use a configuração em Python ou JavaScript e TypeScript.
• Para cloud tracing, é necessário um agente implementado e um recurso Application Insights ligados ao seu projeto Foundry, ou permissão para ligar ou criar um.
• Para consultas na cloud, é necessária a função Log Analytics Reader no recurso do Application Insights ligado. Para tabelas protegidas, atribua também o papel de Leitor de Dados de Monitorização Privilegiada. Veja os pré-requisitos para traçar da Foundry.

A recolha local não requer permissões do Application Insights ou da telemetria na cloud. As chamadas de modelo e a execução de ferramentas ainda podem usar serviços remotos e incorrer em encargos.

Recolher rastreios locais

O coletor local recebe telemetria através do OpenTelemetry Protocol (OTLP). Isto não instrumenta automaticamente uma aplicação. A sua framework ou biblioteca de instrumentação deve criar spans e exportá-los para o collector.

SDK e configuração do idioma

SDKs com instrumentação incorporada ainda precisam de um exportador. Outros SDKs utilizam um pacote de instrumentação separado.

"Sem orientação dedicada de configuração do Toolkit" significa que não existe um caminho de configuração específico para SDK para essa linguagem, não que o coletor rejeite a sua telemetria. O coletor aceita dados OTLP. O instrumentor determina quais as operações e detalhes da mensagem que são capturados.

Estes exemplos utilizam opções selecionadas de instrumentação, não uma lista exaustiva de bibliotecas compatíveis. OpenLLMetry e instrumentação Traceloop são bibliotecas não Microsoft.

Configurar instrumentação

Use este procedimento com uma aplicação existente do Python Agent Framework. Mantenha o agente e o coletor no mesmo ambiente local para este guia passo a passo.

1. Selecione Foundry Toolkit na barra de atividade, depois Ferramentas de Programador>Monitor>Rastreio.

2. Selecione Start Collector antes de executar a sua aplicação.

3. No ambiente Python da aplicação, instale o exportador gRPC se ainda não estiver declarado nas suas dependências:

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

   Referência: exportadores OTLP OpenTelemetry para Python.

4. Configure o OpenTelemetry uma vez no arranque da aplicação, 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 a sua aplicação ou biblioteca de hosting já configura providers do OpenTelemetry, configure os exportadores existentes em vez de adicionar outra configuração de provider. Variáveis específicas OTEL_EXPORTER_OTLP_*_ENDPOINT do sinal podem sobrepor o endpoint base. Verifique as definições existentes de rastreamento, registo ou métrica que apontem para outro lado.

5. Executa a aplicação com o seu ponto de entrada normal e envia um pedido que exercite o agente. Deixe a solicitação terminar e dê tempo ao exportador para enviar a telemetria antes de parar o processo.

6. Em Rastreio, selecione Atualizar e depois selecione o novo traço para inspecionar os seus spans.

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

Para outro SDK ou linguagem, use a configuração abaixo em vez da configuração do Agent Framework. Inicie primeiro o coletor, configure a instrumentação antes de criar clientes, depois execute a sua aplicação e atualize a lista de traços.

Pontos de extremidade dos coletores

Associe o protocolo exportador ao endpoint do coletor. O Toolkit ouve no localhost com estes valores predefinidos:

Alguns exportadores HTTP aceitam http://localhost:4318 e adicionam o caminho do sinal eles próprios. Siga a configuração do seu exportador em vez de adicionar o caminho duas vezes. Algumas bibliotecas de instrumentação enviam conteúdo de mensagens como registos de log, pelo que exportar apenas spans pode não fornecer detalhes de entrada e saída.

Estas portas não estão relacionadas nem com o servidor HTTP do agente nem com as portas do depurador. Num ambiente de contentores ou desenvolvimento remoto, localhost refere-se a esse ambiente. Estabeleça a ligação apropriada ao coletor em vez de assumir que se refere à sua área de trabalho.

Configuração do SDK em Python

Os exemplos seguintes pressupõem que a sua aplicação já tem o SDK do modelo, credenciais e configuração do modelo. Instale as dependências partilhadas e o pacote adicional para o seu SDK a partir da tabela seguinte:

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

Referência: OpenTelemetry Python SDK, exportadores OTLP.

Adicione esta configuração partilhada uma vez no arranque da aplicação, seguida pela instrumentação de uma das linhas da tabela. Não o combines com a configuração do provider 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 fila escolhida com python -m pip install <package>. Os exemplos de OpenAI, Anthropic, LangChain e agentes OpenAI separados utilizam instrumentação não Microsoft OpenLLMetry. Versões do SDK e APIs de modelos podem produzir detalhes diferentes.

Para Projetos Foundry, siga as orientações de rastreamento do lado do cliente e crie o seu cliente OpenAI após a instrumentação. Esta orientação difere do clássico Agents SDK. Não instrumente as mesmas chamadas OpenAI com ambos AIProjectInstrumentor e um instrumentador OpenAI separado.

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

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

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

Referência: instrumentação dos Agentes OpenAI, tracing dos Agentes OpenAI.

Este exemplo substitui processadores de traço existentes antes de adicionar o processador OpenTelemetry. Sem essa substituição, o SDK também pode exportar rastreios para o seu backend predefinido. Se tiveres processadores existentes, revê os destinos de rastreio antes de os alterar. Mantenha o rastreamento do SDK ativado para que o processador OpenTelemetry receba eventos.

Depois de uma aplicação de curta duração terminar os seus pedidos, chame provider.force_flush() antes de sair para enviar os spans em buffer. Para ajuda na adaptação destes excertos, utilize a ferramenta Tracing Code Gen do Toolkit.

Exportar registos do registo de mensagens

Alguns instrumentadores emitem conteúdo de mensagens como registos de log do OpenTelemetry em vez de atributos span. Se optar por gravar esse conteúdo num teste de desenvolvimento controlado, adicione esta configuração uma vez ao lado do fornecedor 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 logging SDK, OTLPLogExporter.

Ligue logger_provider.force_flush() antes de encerrar uma aplicação de curta duração. Um exportador de log não ativa a captura de conteúdo sozinho. Siga as definições de conteúdo do seu instrumentor e as orientações sobre o tratamento de dados.

Configuração do SDK de JavaScript e TypeScript

Para aplicações Node.js, partilhe um fornecedor de rastreamento e registe a instrumentação para o seu SDK. Este exemplo utiliza CommonJS e a configuração do provider OpenTelemetry JavaScript 2.x. As aplicações TypeScript compiladas para CommonJS podem usar a mesma ordem de inicialização.

A sua aplicação já deve ter o SDK do modelo, credenciais e configuração do modelo. Instale as dependências partilhadas e o instrumentador 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 do 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.

Carrega este ficheiro antes de importar ou de requerer o SDK do teu modelo. Por exemplo, execute node --require ./tracing.cjs app.cjs para uma aplicação CommonJS. Para outro SDK, substitua o pacote OpenAI, a importação e a entrada de registo pela linha correspondente:

Os pacotes Traceloop são instrumentação que não é da Microsoft. Para uma aplicação do Foundry Projects, instrumente o cliente que faz o pedido ao modelo. A instrumentação do SDK do Azure não substitui a instrumentação OpenAI para chamadas feitas através de um cliente OpenAI.

Para módulos ECMAScript nativos, siga a configuração ESM da OpenTelemetry. Carregar instrumentação após o SDK alvo pode deixar chamadas sem instrumentação. No encerramento, aguarde provider.shutdown() após a conclusão das requisições para exportar os spans em buffer.

Inspecionar e gerir os registos de rastreio locais

Use a span tree para seguir a solicitação da orquestração do agente para as operações de modelo e ferramenta.

1. Selecione um span lento ou com falha.
2. Verifique a duração e o estado.
3. Abrir 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údos sensíveis desativada. Dados de temporização sem mensagens podem ser o resultado esperado.

Para um teste controlado de desenvolvimento do Agent Framework, defina enable_sensitive_data=True na configuração existente para registar o conteúdo suportado de pedidos, respostas e ferramentas. Restaure-o para False quando o teste estiver concluído. Outros instrumentadores têm as suas próprias definições de conteúdo.

Os vestígios recolhidos são armazenados numa base de dados SQLite local chamada traces.db, no subdiretório tracing de .aitk sob a pasta inicial do utilizador. Fechar o visualizador não os apaga.

Selecione Stop Collector para parar a recolha local. O seu agente e as suas chamadas de modelo continuam em execução. Para remover registos locais, selecione os rastreios na lista e selecione Eliminar.

O armazenamento local é separado do Application Insights. Eliminar rastreios locais não remove a telemetria na cloud, e limpar uma conversa no Inspector não apaga nenhum dos dois armazenamentos.

Ver registos de rastreio do agente alojado

Após a implementação, use rastreios na cloud para investigar o agente a correr no Foundry em vez do processo local. O Toolkit consulta o recurso Application Insights ligado ao projeto. Não envia a tua base de dados local de rastreios.

Confirme os pré-requisitos da nuvem antes de começar. O acesso ao agente por si só não concede permissão para consultar telemetria.

Ligue-se ao Application Insights e inspecione um pedido HTTP

Utilize o separador Traces do agente para ligar o Application Insights e encontrar um pedido do agente implementado.

1. Na barra lateral do Foundry Toolkit, abra Os Meus Recursos>Agentes. Selecione o separador Agente Hospedado e depois selecione o nome do agente.

2. Selecione Traces. Se o projeto não tiver um recurso ligado, selecione Enable App Insights.

3. Nas Definições do App Insights, selecione um Nome de Recurso do Application Insights existente. Em alternativa, escolha criar um recurso e completar os campos do recurso e do espaço de trabalho necessários. Selecione Enviar e aguarde por confirmação.

   Isto altera a ligação partilhada ao Application Insights do projeto, não uma preferência de espaço de trabalho local. A criação de recursos e a recolha de telemetria podem implicar custos do Azure. Confirme que o projeto e o recurso são os pretendidos antes de submeter.

4. Volte ao Playground e envie um pedido de teste ao agente implementado.

5. Deixe tempo para a ingestão e depois abra o Traces novamente. Utilize o intervalo de tempo, Pesquisa por ID de conversa, Estado ou Duração para localizar o pedido.

   

6. Selecione um rastreio, depois um span, para rever Metadados e Entrada + Saída, quando o conteúdo estiver disponível.

Para inspecionar operações associadas a uma conversa, selecione o seu ID de Conversa na lista de traços. A vista de conversa mostra uma árvore de operações e metadados.

Ligar o Application Insights permite o rastreamento do lado do servidor da Foundry. A visibilidade sobre as chamadas de modelo, chamadas de ferramentas e código personalizado também depende da biblioteca de alojamento e da instrumentação do framework. Veja Configurar traçado no Foundry para recolha do lado do serviço e instrumentação adicional do cliente.

A consulta de trace-detail do Toolkit cobre atualmente os últimos sete dias. Esta é uma janela de consulta, não uma definição de retenção. Para dados mais antigos, utilize o portal Foundry ou o Azure Monitor, em função da configuração de retenção do espaço de trabalho ligado.

Dados, acesso, retenção e custo

Decida para onde deve ir a telemetria antes de ativar a captura de conteúdo ou ligar um recurso na cloud. O mesmo pedido pode gerar spans locais, telemetria na nuvem e dados enviados a fornecedores de modelos ou ferramentas.

Utilize as orientações de rastreio da Foundry para segurança e privacidade e retenção e custo de dados. Para identidade de produção, isolamento de rede e acesso a jusante, siga segurança e tratamento de dados de agentes alojados. Não trate as credenciais locais como permissões do agente implementado.

Troubleshooting

Conteúdo relacionado

• Depurar agentes com o Agent Inspector.
• Conceitos de rastreio do Agent.
• Configurar o rastreamento do lado do cliente.