Telemetria

ADK-Rust oferece observabilidade de nível de produção através da crate adk-telemetry, que integra log estruturado e rastreamento distribuído usando o ecossistema tracing e OpenTelemetry.

Visão Geral

O sistema de telemetria permite:

• Log Estruturado: Logs ricos e consultáveis com informações contextuais
• Rastreamento Distribuído: Rastreie requisições através de hierarquias de Agent e limites de serviço
• Integração OpenTelemetry: Exporte traces para backends de observabilidade (Jaeger, Datadog, Honeycomb, etc.)
• Propagação Automática de Contexto: IDs de Session, usuário e invocação fluem por todas as operações
• Spans Pré-configurados: Funções auxiliares para operações ADK comuns

Início Rápido

Log Básico no Console

Para desenvolvimento e implantações simples, inicialize o log do console:

use adk_telemetry::init_telemetry;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Inicializa a telemetria com o nome do seu serviço
    init_telemetry("my-agent-service")?;
    
    // Seu código de Agent aqui
    
    Ok(())
}

Isso configura o log estruturado para stdout com padrões razoáveis.

Exportação OpenTelemetry

Para implantações em produção com rastreamento distribuído:

use adk_telemetry::init_with_otlp;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Inicializa com o exportador OTLP
    init_with_otlp("my-agent-service", "http://localhost:4317")?;
    
    // Seu código de Agent aqui
    
    // Descarrega os traces antes de sair
    adk_telemetry::shutdown_telemetry();
    Ok(())
}

Isso exporta traces e métricas para um endpoint de coletor OpenTelemetry.

Níveis de Log

Controle a verbosidade do log usando a variável de ambiente RUST_LOG:

Configurando Níveis de Log

# Define o nível de log global
export RUST_LOG=info

# Define níveis de log por módulo
export RUST_LOG=adk_agent=debug,adk_model=info

# Combina níveis globais e específicos de módulo
export RUST_LOG=warn,adk_agent=debug

O sistema de telemetria usa o nível info por padrão se RUST_LOG não for definido.

Macros de Log

Use as macros tracing padrão para log:

use adk_telemetry::{trace, debug, info, warn, error};

// Log informativo
info!("Agent iniciado com sucesso");

// Log estruturado com campos
info!(
    agent.name = "my_agent",
    session.id = "sess-123",
    "Processando requisição de usuário"
);

// Log de depuração
debug!(user_input = ?input, "Entrada recebida");

// Log de aviso e erro
warn!("Limite de taxa se aproximando");
error!(error = ?err, "Falha ao chamar o model");

Campos Estruturados

Adicione campos contextuais às mensagens de log para melhor filtragem e análise:

use adk_telemetry::info;

info!(
    agent.name = "customer_support",
    user.id = "user-456",
    session.id = "sess-789",
    invocation.id = "inv-abc",
    "Execução do Agent iniciada"
);

Esses campos se tornam consultáveis no seu backend de observabilidade.

Instrumentação

Instrumentação Automática

Use o atributo #[instrument] para criar spans automaticamente para funções:

use adk_telemetry::{instrument, info};

#[instrument]
async fn process_request(user_id: &str, message: &str) {
    info!("Processing request");
    // Function logic here
}

// Cria um span chamado "process_request" com user_id e message como campos

Pular Parâmetros Sensíveis

Exclua dados sensíveis dos rastreamentos:

use adk_telemetry::instrument;

#[instrument(skip(api_key))]
async fn call_external_api(api_key: &str, query: &str) {
    // api_key não aparecerá nos rastreamentos
}

Nomes de Span Personalizados

use adk_telemetry::instrument;

#[instrument(name = "external_api_call")]
async fn fetch_data(url: &str) {
    // O Span será nomeado "external_api_call" em vez de "fetch_data"
}

Spans Pré-configurados

ADK-Telemetry oferece funções auxiliares para operações comuns:

Span de Execução de Agente

use adk_telemetry::agent_run_span;

let span = agent_run_span("my_agent", "inv-123");
let _enter = span.enter();

// Código de execução do Agente aqui
// Todos os logs dentro deste escopo herdam o contexto do span

Span de Chamada de Modelo

use adk_telemetry::model_call_span;

let span = model_call_span("gemini-2.0-flash");
let _enter = span.enter();

// Chamada de API do Modelo aqui

Span de Execução de Tool

use adk_telemetry::tool_execute_span;

let span = tool_execute_span("weather_tool");
let _enter = span.enter();

// Código de execução da Tool aqui

Span de Callback

use adk_telemetry::callback_span;

let span = callback_span("before_model");
let _enter = span.enter();

// Lógica de callback aqui

Adicionando Atributos de Contexto

Adicione contexto de usuário e sessão ao span atual:

use adk_telemetry::add_context_attributes;

add_context_attributes("user-456", "sess-789");

Criação Manual de Span

Para instrumentação personalizada, crie spans manualmente:

use adk_telemetry::{info, Span};

let span = tracing::info_span!(
    "custom_operation",
    operation.type = "data_processing",
    operation.id = "op-123"
);

let _enter = span.enter();
info!("Performing custom operation");
// Código da operação aqui

Atributos de Span

Adicione atributos dinamicamente:

use adk_telemetry::Span;

let span = Span::current();
span.record("result.count", 42);
span.record("result.status", "success");

Configuração do OpenTelemetry

Endpoint OTLP

O exportador OTLP envia rastreamentos para um endpoint de coletor:

use adk_telemetry::init_with_otlp;

// Jaeger Local (porta OTLP padrão)
init_with_otlp("my-service", "http://localhost:4317")?;

// Endpoint de provedor de nuvem
init_with_otlp("my-service", "https://otlp.example.com:4317")?;

Executando um Coletor Local

Para desenvolvimento, execute o Jaeger com suporte OTLP:

docker run -d --name jaeger \
  -p 4317:4317 \
  -p 16686:16686 \
  jaegertracing/all-in-one:latest

# Visualize rastreamentos em http://localhost:16686

Visualização de Rastreamentos

Uma vez configurado, os rastreamentos aparecem no seu backend de observabilidade mostrando:

• Hierarquia de execução do Agente
• Latências de chamadas de Modelo
• Tempo de execução de Tool
• Propagação de erros
• Fluxo de contexto (ID do usuário, ID da sessão, etc.)

Integração com ADK

Os componentes do adk-rust emitem telemetria automaticamente quando o sistema de telemetria é inicializado:

use adk_rust::prelude::*;
use adk_telemetry::init_telemetry;
use std::sync::Arc;

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    // Initialize telemetry first
    init_telemetry("my-agent-app")?;
    
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = Arc::new(GeminiModel::new(&api_key, "gemini-2.5-flash")?);
    
    let agent = LlmAgentBuilder::new("support_agent")
        .model(model)
        .instruction("You are a helpful support agent.")
        .build()?;
    
    // Use Launcher for simple execution
    Launcher::new(Arc::new(agent)).run().await?;
    
    Ok(())
}

As operações de Agent, Model e Tool emitirão automaticamente logs e traces estruturados.

Telemetria Personalizada em Tools

Adicione telemetria a Tools personalizadas:

use adk_rust::prelude::*;
use adk_telemetry::{info, instrument, tool_execute_span};
use serde_json::{json, Value};

#[instrument(skip(ctx))]
async fn weather_tool_impl(
    ctx: Arc<dyn ToolContext>,
    args: Value,
) -> Result<Value> {
    let span = tool_execute_span("weather_tool");
    let _enter = span.enter();
    
    let location = args["location"].as_str().unwrap_or("unknown");
    info!(location = location, "Fetching weather data");
    
    // Tool logic here
    let result = json!({
        "temperature": 72,
        "condition": "sunny"
    });
    
    info!(location = location, "Weather data retrieved");
    Ok(result)
}

let weather_tool = FunctionTool::new(
    "get_weather",
    "Get current weather for a location",
    json!({
        "type": "object",
        "properties": {
            "location": {"type": "string"}
        },
        "required": ["location"]
    }),
    weather_tool_impl,
);

Telemetria Personalizada em Callbacks

Adicione observabilidade a Callbacks:

use adk_rust::prelude::*;
use adk_telemetry::{info, callback_span};
use std::sync::Arc;

let agent = LlmAgentBuilder::new("observed_agent")
    .model(model)
    .before_callback(Box::new(|ctx| {
        Box::pin(async move {
            let span = callback_span("before_agent");
            let _enter = span.enter();
            
            info!(
                agent.name = ctx.agent_name(),
                user.id = ctx.user_id(),
                session.id = ctx.session_id(),
                "Agent execution starting"
            );
            
            Ok(None)
        })
    }))
    .after_callback(Box::new(|ctx| {
        Box::pin(async move {
            let span = callback_span("after_agent");
            let _enter = span.enter();
            
            info!(
                agent.name = ctx.agent_name(),
                "Agent execution completed"
            );
            
            Ok(None)
        })
    }))
    .build()?;

Considerações de Desempenho

Amostragem

Para sistemas de alta vazão, considere a amostragem de traces:

// Nota: A configuração de amostragem depende da sua configuração OpenTelemetry
// Configure a amostragem no seu coletor OTLP ou backend

Spans Assíncronos

Sempre use #[instrument] em funções async para garantir o contexto de span adequado:

use adk_telemetry::instrument;

// ✅ Correto - contexto de span preservado em pontos de await
#[instrument]
async fn async_operation() {
    tokio::time::sleep(Duration::from_secs(1)).await;
}

// ❌ Incorreto - span manual pode perder o contexto
async fn manual_span_operation() {
    let span = tracing::info_span!("operation");
    let _enter = span.enter();
    tokio::time::sleep(Duration::from_secs(1)).await;
    // O contexto pode ser perdido após o await
}

Nível de Log em Produção

Use o nível info ou warn em produção para reduzir o overhead:

export RUST_LOG=warn,my_app=info

Solução de Problemas

Nenhum Log Aparecendo

1. Verifique se a variável de ambiente RUST_LOG está definida
2. Garanta que init_telemetry() seja chamado antes de qualquer log
3. Verifique se a telemetria é inicializada apenas uma vez (usa Once internamente)

Traces Não Exportados

1. Verifique se o endpoint OTLP está acessível
2. Verifique se o collector está em execução e aceitando conexões
3. Chame shutdown_telemetry() antes da saída da aplicação para descarregar os spans pendentes
4. Verifique problemas de rede/firewall

Contexto Ausente nos Spans

1. Use #[instrument] em funções async
2. Garanta que os spans sejam inseridos com let _enter = span.enter()
3. Mantenha o guarda _enter no escopo pela duração da operação

Melhores Práticas

1. Inicialize Cedo: Chame init_telemetry() no início de main()
2. Use Campos Estruturados: Adicione contexto com pares chave-valor, não interpolação de string
3. Instrumente Funções Async: Sempre use #[instrument] em funções async
4. Descarregue na Saída: Chame shutdown_telemetry() antes do encerramento da aplicação
5. Níveis de Log Apropriados: Use info para eventos importantes, debug para detalhes
6. Evite Dados Sensíveis: Pule parâmetros sensíveis com #[instrument(skip(...))]
7. Nomenclatura Consistente: Use nomes de campo consistentes (ex: user.id, session.id)

Relacionado

• Callbacks - Adicione telemetria a callbacks
• Tools - Instrumente ferramentas personalizadas
• Deployment - Configuração de telemetria em produção

---

Anterior: ← Events | Próximo: Launcher →