09-04-02 — Tracing GA: spans, filtering, inspeção end-to-end

O que é um trace de agente

Cada execução de um agente (um Run) gera um trace hierárquico:

"""
Run: customer-support-agent / thread_abc123 / run_xyz789
├── Span: agent.run (total: 4.2s, tokens: 1847)
│   ├── Span: model.invoke (1.8s) — GPT-4o chamado com histórico
│   ├── Span: tool.file_search (0.9s) — buscou "prazo contrato"
│   │   ├── embedding_call (0.2s) — embed query
│   │   └── vector_search (0.7s) — buscou nos chunks
│   └── Span: model.invoke (1.3s) — GPT-4o gerou resposta final
│       ├── input_tokens: 1200
│       └── output_tokens: 647
"""

Habilitando tracing no seu app

Se usar o AI Foundry SDK, tracing automático está habilitado com uma linha:

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
import os

client = AIProjectClient.from_connection_string(
    os.environ["AZURE_AI_FOUNDRY_CONNECTION_STRING"],
    DefaultAzureCredential()
)

# Habilita tracing automático — envia para Application Insights
client.telemetry.enable(destination=client.telemetry.get_connection_string())

// C# - habilitar tracing
using Azure.AI.Projects;
using Azure.Identity;

var client = new AIProjectClient(
    new Uri(Environment.GetEnvironmentVariable("AZURE_AI_FOUNDRY_ENDPOINT")),
    new DefaultAzureCredential()
);

// Habilita tracing via OpenTelemetry para Application Insights
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureAIProjectsInstrumentation()
    .AddAzureMonitorTraceExporter(options => {
        options.ConnectionString = 
            Environment.GetEnvironmentVariable("APPLICATIONINSIGHTS_CONNECTION_STRING");
    })
    .Build();

Visualizando traces no portal Foundry

No portal ai.azure.com:

1. Selecione seu Projeto
2. Menu lateral → Tracing
3. Lista de todos os runs com: data, duração, tokens, status
4. Clique em qualquer run → visualização em árvore de spans
5. Filter por: data, duração (outliers de latência), status (failed), tokens (custo alto)

Filtering avançado

Para debugging específico, filtre por:

• Latência > Xms: identifique runs lentos — tool calls problemáticas?
• Tokens > N: identifique conversas que estão consumindo muito — histórico muito longo?
• Status = failed: debugging de erros de runtime
• Tool = file_search: ver apenas runs que usaram RAG
• User/Session ID: rastrear comportamento de usuário específico

Custom spans no seu código

Para adicionar contexto de negócio ao trace:

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

def processar_solicitacao(pedido_id: str, pergunta: str):
    with tracer.start_as_current_span("processar_solicitacao") as span:
        span.set_attribute("pedido_id", pedido_id)
        span.set_attribute("canal", "whatsapp")
        span.set_attribute("cliente_segmento", "enterprise")
        
        # Chamar o agente — spans filho automáticos do Foundry SDK
        response = run_agent(pergunta)
        
        span.set_attribute("resposta_tokens", response.usage.total_tokens)
        return response

Alertas baseados em traces

No Azure Monitor, crie alertas baseados nos dados de tracing:

• P95 latência > 10s → alerta para equipe de infra
• Taxa de erro (failed runs) > 5% → alerta crítico
• Uso de tokens/hora > threshold → alerta de custo