Observability
A missão é investigar uma execução com timeout de ferramenta e fallback. Você criará uma árvore de spans e logs correlacionados, depois adicionará uma segunda execução com falha de autorização. O relatório deve identificar etapa, causa observável, impacto no usuário e dados ausentes, sem depender de uma reprodução da conversa.
Use Node e arquivos locais spans.json e logs.json. O exemplo dispensa qualquer backend ou credencial. A integração opcional com um coletor OpenTelemetry ou uma plataforma de tracing exige instalação, endpoint e autorização próprios; não descreva as fixtures como traces enviados a um serviço. Antes de habilitar conteúdo completo de prompts, defina quais campos podem ser capturados.
JavaScriptIA & MLAvaliaçãoAo terminar esta aula
- Observe caminhos executados, versões e resultados.
- Mensure ponta a ponta e por tentativa.
- Telemetria deve ser útil sem capturar segredos desnecessários.
Antes de continuar: Leitura: Observability
Definir uma árvore que preserve causalidade
FundamentosDesenhe request como raiz e retrieval, model, tool e response como filhos. Para retries, crie spans separados com attempt e uma referência à operação lógica. Para worker assíncrono, preserve o contexto na mensagem e registre queueWaitMs. Acrescente promptVersion, policyVersion e tenantId opaco, sem nome ou documento pessoal. Crie duas requisições com IDs diferentes e confirme que nenhum filho aparece associado à raiz errada. Um teste estrutural deve rejeitar span órfão quando a captura pretende ser completa, ou sinalizá-lo como captura parcial quando houver amostragem deliberada.
Inspecionar o timeout com um teste determinístico
AvaliaçãoExecute o código e confirme que lookup é a etapa em erro, que existe log ligado ao seu span e que o fallback encerra a requisição. Remova o spanId do log: a reconstrução perde a associação precisa, e seu teste deve detectar isso. Depois marque a raiz como error e explique a mudança de semântica: o fallback deixou de concluir a tarefa. A duração de 180 é uma fixture, não latência observada de um provedor. Substitua os tempos por medições monotônicas somente quando executar operações reais.
const assert = require('node:assert/strict');
const spans = [
{traceId:'t1',id:'root',parent:null,name:'request',start:0,end:180,status:'ok'},
{traceId:'t1',id:'s1',parent:'root',name:'retrieve',start:0,end:30,status:'ok'},
{traceId:'t1',id:'s2',parent:'root',name:'lookup',start:30,end:130,status:'error',errorType:'timeout'},
{traceId:'t1',id:'s3',parent:'root',name:'fallback',start:130,end:180,status:'ok',inputTokens:40,outputTokens:10}
];
const logs=[{traceId:'t1',spanId:'s2',eventName:'tool.timeout'}];
const failed=spans.find(s=>s.status==='error');
assert.equal(failed.name,'lookup');
assert.ok(logs.some(l=>l.spanId===failed.id));
assert.equal(spans[0].end-spans[0].start,180);
console.log({failed,finalStatus:spans[0].status,
tokens:spans.reduce((n,s)=>n+(s.inputTokens||0)+(s.outputTokens||0),0)});Medir uso e interpretar tentativas
FundamentosAdicione uma chamada de modelo anterior ao timeout com inputTokens 60 e outputTokens 20, preservando a chamada do fallback. A soma deve subir para 130 unidades reportadas nas fixtures. Acrescente campos usageKind e tariffVersion quando houver cálculo de custo, sem preencher preços inventados. Gere uma tabela por requisição contendo tentativas, uso, duração e conclusão. Para um serviço real, confira se o SDK reporta categorias específicas, como tokens de cache. O total deve refletir todas as chamadas registradas e apontar explicitamente eventos sem informação de uso.
Testar a política de captura e a falha do coletor
FundamentosInsira deliberadamente apiKey e um cabeçalho Authorization em um objeto de evento local, depois execute a sanitização e confirme que esses valores não aparecem no arquivo exportado. Teste também um segredo dentro de uma mensagem de erro para perceber a limitação da filtragem por nome de campo. Não envie esses valores a um backend. Simule exportador indisponível e limite o buffer a dez eventos; registre quantos foram descartados. A perda controlada precisa ser visível para evitar interpretar silêncio do painel como ausência de falhas.
Produzir uma análise que outro operador possa seguir
FundamentosEntregue um relatório com traceId, versão do agente, árvore resumida, etapa de falha, decisão de fallback e resultado funcional. Inclua uma linha do tempo e explique lacunas de captura. Compare brevemente OpenTelemetry com uma das opções LangSmith, Phoenix ou MLflow, usando a mesma necessidade concreta: correlacionar ferramenta, custo e avaliação. Se você testar uma integração, anexe versão, configuração sem segredo e prova de recebimento. Se permanecer local, declare o alcance: o exercício verifica formato e interpretação, não operação de uma plataforma externa.
↗ LangSmith Observability↗ Setup Tracing↗ MLflow Tracing for LLM and Agent Observability
Exercício aplicado
O dashboard mostra status ok na requisição, mas um usuário relata que a compra não foi consultada. Use o trace para distinguir sucesso de transporte, fallback e conclusão funcional.
- Localize a raiz e os filhos pelo traceId.
- Identifique erro de lookup e log correlacionado.
- Verifique qual decisão de fallback foi registrada.
- Compare a resposta final com o contrato da tarefa.
Abrir resolução comentada
O span raiz pode estar ok quando a aplicação entregou uma resposta válida por fallback. O trace prova que a consulta falhou e que outro caminho foi executado; não prova que o objetivo original foi concluído. A classificação funcional depende da política de encaminhamento.
Para investigar sem reproduzir, preserve os IDs, versões e categorias de erro. Não é necessário armazenar credenciais ou raciocínio privado. Se o conteúdo necessário não foi capturado, a análise deve assumir evidência insuficiente em vez de inventar a causa.
const assert = require('node:assert/strict');
const spans = [
{traceId:'t1',id:'root',parent:null,name:'request',start:0,end:180,status:'ok'},
{traceId:'t1',id:'s1',parent:'root',name:'retrieve',start:0,end:30,status:'ok'},
{traceId:'t1',id:'s2',parent:'root',name:'lookup',start:30,end:130,status:'error',errorType:'timeout'},
{traceId:'t1',id:'s3',parent:'root',name:'fallback',start:130,end:180,status:'ok',inputTokens:40,outputTokens:10}
];
const logs=[{traceId:'t1',spanId:'s2',eventName:'tool.timeout'}];
const failed=spans.find(s=>s.status==='error');
assert.equal(failed.name,'lookup');
assert.ok(logs.some(l=>l.spanId===failed.id));
assert.equal(spans[0].end-spans[0].start,180);
console.log({failed,finalStatus:spans[0].status,
tokens:spans.reduce((n,s)=>n+(s.inputTokens||0)+(s.outputTokens||0),0)});Como conferir seu resultado
- Logs e spans preservam traceId e vínculo correto.
- Timeout e fallback aparecem como etapas diferentes.
- Uso inclui todas as tentativas capturadas.
- Nenhum segredo de teste permanece no export local.
Aplique em um problema novo
Primeiro resolva sem consultar a resposta. Explique suas decisões e guarde a evidência. A conclusão de leitura é independente desta autoavaliação.
Confira seus pré-requisitos
- Ler árvore parent/spanId e tempos.
- Correlacionar logs sem dados desnecessários.
Trace tem duas tentativas com 30+10 tokens cada e fallback 20+5. Calcule consumo e desenhe relatório do timeout.
Conferir raciocínio e critérios de domínio
Total 105 tokens:40+40+25, não apenas 25 da saída aceita.
Relatório mostra caminho/tentativas e lookup desconhecido, distinguindo transporte/função.
Uso é fixture; custo financeiro exige preço/modelo/data e minimização dos dados.
Evidências para autoavaliação ou revisão por pares
- Consumo de todas as tentativas: Total 105 tokens:40+40+25, não apenas 25 da saída aceita.
- Estado funcional: Relatório mostra caminho/tentativas e lookup desconhecido, distinguindo transporte/função.
- Preço e privacidade: Uso é fixture; custo financeiro exige preço/modelo/data e minimização dos dados.
Um erro frequente
Só resposta final gera custo.
Todas as tentativas reportadas participam do ledger de consumo.
Teste sua compreensão
Responda com suas palavras antes de abrir o comentário. Saber explicar uma decisão é parte do domínio.
1. O trace revela o raciocínio privado do modelo?
2. Por que a soma de spans paralelos pode exceder a duração total?
Porque os intervalos podem se sobrepor.
A latência ponta a ponta depende do caminho crítico.
3. Um backend sem eventos prova ausência de falhas?
Não.
Amostragem, perda e exportação indisponível podem gerar lacunas.
Seu progresso fica salvo neste navegador. Concluir a leitura não substitui demonstrar o domínio nos exercícios.
Referências e aprofundamento
Documentação oficial e trabalhos originais. As referências registram o escopo e as limitações para você conferir o que sustentam.
- Traces
OpenTelemetry • consulta: 2026-10-06
FundamentosTrace, span, contexto, relações pai-filho, eventos e status de execução.
Limites: Instrumentação mostra operações registradas; não revela raciocínio privado do modelo.
- Logs
OpenTelemetry • consulta: 2026-10-06
FundamentosLogs estruturados e correlação com contexto de traces.
Limites: Coleta e retenção dependem da implementação; evitar registrar segredos e conteúdo sensível desnecessário.
- MLflow Tracing for LLM and Agent Observability
MLflow • consulta: 2026-10-06
AgentesIA & MLAvaliaçãoEntradas, saídas, metadados, latência e uso de tokens por etapa; integração OpenTelemetry.
Limites: Custo financeiro exige cálculo adicional com tarifas vigentes; traces só cobrem etapas instrumentadas.
- Spend Tracking
LiteLLM • consulta: 2026-10-06
FundamentosRegistro de uso e gasto, atribuição a chaves/usuários e consulta de custos.
Limites: Estimativa de custo depende das tarifas e dos metadados de uso; reconciliar com faturamento do provedor.
- OpenTelemetry GenAI Semantic Conventions
OpenTelemetry • consulta: 2026-10-06
FundamentosRepositório oficial atual de convenções para spans, métricas e eventos GenAI, MCP e provedores.
Limites: A documentação anterior no site informa migração para este repositório; verificar versão e suporte da instrumentação.
- LangSmith Observability
LangChain • consulta: 2026-10-06
AvaliaçãoTracing de aplicações LLM e agentes, depuração e observação de etapas.
Limites: Opção de implementação, não obrigação curricular; configuração e acesso aos dados requerem atenção.
- Setup Tracing
Arize Phoenix • consulta: 2026-10-06
FundamentosSetup de tracing e instrumentação de aplicações LLM.
Limites: Escolher uma ferramenta para o laboratório; a página não prova equivalência funcional entre produtos.