Sentry Instrument AI

ANÁLISE EDITORIAL

Sentry Instrument é uma Skill oficial para instrumentar aplicações com erros, tracing, logs, métricas, profiling, replay, feedback e monitoramento de IA. Nesta curadoria, o recorte é a observabilidade de agentes e chamadas de modelos: runs, conversas, ferramentas, latência, tokens, custo estimado e risco de capturar conteúdo sensível.

A versão auditada está no repositório getsentry/sentry-for-ai, commit c1aab39520fc1f28ba23e969a2d6b74a87088038. O projeto tinha 249 estrelas na consulta de 16 de agosto de 2026. A raiz usa licença MIT, enquanto o frontmatter da Skill declara Apache 2.0. O pacote preserva essa divergência para o leitor conferir na origem.

O download local é um recorte documental. Inclui o SKILL.md, o manifesto de referências e materiais sobre monitoramento de IA para Node.js e Python, conceitos e convenções gen_ai. Não contém SDK, servidor MCP, script, runtime, DSN, prompt real, resposta de usuário, token ou credencial.

Imagem editorial exclusiva do Bastidores da IA. Não é painel da Sentry, dashboard real nem prova de telemetria capturada.

O que a Skill organiza

O fluxo começa definindo o escopo: primeira captura de erro, adição de um sinal ou configuração mais completa. A Skill evita instrumentação excessiva. Se o pedido é apenas colocar erros e tracing básico para funcionar, ela não deve adicionar replay, profiling, logs e monitoramento de IA sem necessidade.

Para um sinal adicional, o agente detecta a plataforma, confirma com o usuário e lê a referência específica. No caso de IA, a orientação separa a estratégia, os atributos semânticos e o código por SDK. O processo só é considerado concluído quando um evento real chega ao sistema e pode ser encontrado.

Esse fechamento é importante. Configuração que compila não prova que a telemetria atravessou rede, amostragem, autenticação e ingestão. A Skill pede um caminho real, consulta e URL do evento, ou um diagnóstico explícito da falha.

Como representar agentes e modelos

As referências usam atributos gen_ai.* para modelo, operação, tokens, custo, ferramentas e conversa. Uma execução de agente pode conter várias chamadas de modelo e ferramentas. A hierarquia precisa preservar essa relação para que latência e falha sejam atribuídas ao trecho correto.

Contagens de cache e raciocínio são subconjuntos dos totais, não parcelas adicionais. Somá-las novamente produz custo incorreto ou até valores negativos em cálculos derivados. A Skill chama atenção para esse detalhe porque provedores retornam estruturas diferentes.

O identificador de conversa deve agrupar mensagens relacionadas sem virar dado pessoal. Um email, telefone ou nome de cliente não deve ser usado como identificador. Prefira um valor opaco, estável somente pelo tempo necessário e sujeito à política de retenção.

Prompts e respostas são dados sensíveis

Monitoramento de IA pode capturar texto enviado ao modelo, resposta, instrução de sistema, argumentos de ferramentas e resultados. Esses campos podem conter código, documentos, dados pessoais, segredos ou decisões internas. Ativar captura indiscriminada cria um novo repositório de informação sensível.

A política segura começa com conteúdo desativado ou fortemente filtrado. Registre metadados necessários para operar: modelo, duração, status, uso, identificador opaco e tipo de ferramenta. Só capture conteúdo quando houver finalidade, base legal, acesso controlado, retenção definida e redaction testada.

Eventos recebidos também devem ser tratados como entrada não confiável. A própria Skill alerta para não executar instruções encontradas em payload, título ou comentário. Telemetria pode carregar texto produzido por usuário ou modelo e não deve ganhar autoridade sobre o agente de diagnóstico.

Para quem serve

A Skill serve para equipes que operam aplicações com OpenAI, Anthropic, Google GenAI, Vercel AI, LangChain, Pydantic AI e outros fluxos suportados pelas referências. Ajuda a responder onde um agente falhou, qual etapa demorou, quantos tokens foram usados e se uma ferramenta ampliou o erro.

Ela não substitui política de privacidade, segurança, FinOps ou qualidade. Uma estimativa de custo no painel não é fatura. Um trace não prova intenção. Uma ausência de erro não demonstra que a resposta foi correta.

Compatibilidade e dependências

A versão completa depende do SDK apropriado e, para provisionamento ou verificação via agente, de uma conexão autenticada com o Sentry MCP. O pacote local não inclui esses componentes. As referências selecionadas cobrem Node.js e Python apenas como material de leitura.

Os exemplos mencionam chaves de provedores por variáveis de ambiente. Isso não autoriza inserir valores reais em arquivos, prompts ou logs. Cada segredo deve permanecer no gerenciador do ambiente e ser concedido ao processo com menor privilégio.

Instalação recomendada

Abra o diretório oficial no commit auditado e compare o SKILL.md original. A instalação oficial monta referências compartilhadas durante o build, por isso copiar apenas essa pasta não produz a Skill completa.

Use o instalador documentado pelo projeto em ambiente de teste e confira os arquivos gerados. Antes de autenticar MCP ou SDK, defina organização, projeto, ambiente, origem dos dados e retenção. O ZIP do Bastidores é deliberadamente incompleto como runtime e completo apenas como recorte auditado de leitura.

Primeiro uso seguro

1. Escolha um aplicativo de teste sem dados pessoais reais.
2. Defina uma única pergunta operacional, como latência de chamadas.
3. Ative somente os spans e atributos necessários.
4. Mantenha conteúdo de prompts e respostas desabilitado.
5. Use DSN e credenciais exclusivos do projeto de teste.
6. Dispare uma chamada conhecida e uma falha controlada.
7. Confirme trace, status, modelo, tokens e relação entre etapas.
8. Verifique redaction, acesso e retenção.
9. Compare volume e custo antes de ampliar amostragem.
10. Documente rollback e desligamento da coleta.

Resultado esperado

Uma boa instrumentação permite seguir uma execução do pedido até as chamadas de modelo e ferramentas, identificar falha e medir duração. Os nomes devem ser consistentes e os atributos precisam usar tipos e unidades corretos. O painel não deve depender de conteúdo sensível para responder perguntas básicas.

A validação inclui um evento real, não apenas um trecho de configuração. Se nada chegou, a saída deve verificar inicialização, ambiente, amostragem, rede, DSN e flush antes de culpar o provedor.

Cenário prático de instrumentação

Considere um agente que recebe uma pergunta, consulta uma base interna, chama um modelo e usa uma ferramenta para abrir um chamado. O traço principal deve representar a solicitação completa. A recuperação, a chamada de modelo e a ferramenta entram como operações filhas, cada uma com duração, resultado e identificadores suficientes para correlação. O nome da operação deve permanecer estável; colocar a pergunta do usuário no nome cria alta cardinalidade e pode expor conteúdo.

Antes de enviar qualquer evento, classifique os campos. Modelo, provedor, quantidade de tokens, latência e estado da operação costumam ser úteis. Prompt, resposta, documentos recuperados, cabeçalhos e argumentos de ferramenta podem conter dados pessoais, segredos ou informação comercial. A política deve omitir esses valores por padrão e habilitá-los somente quando houver finalidade, retenção e acesso definidos. Mascarar depois da coleta pode ser tarde demais.

O teste de aceite deve produzir ao menos um fluxo bem sucedido e falhas controladas de modelo e ferramenta. Verifique se o traço continua navegável, se o erro aparece no componente correto e se nenhum dado proibido chegou ao painel. Compare o volume de eventos e o custo estimado antes de ampliar a cobertura. Instrumentar tudo sem orçamento, amostragem e regra de privacidade apenas troca falta de visibilidade por excesso de dados.

Documente a versão do SDK, a regra de amostragem, os ambientes habilitados e o responsável pela retenção. Esses dados tornam o painel auditável quando o comportamento ou o custo mudar.

Riscos e erros comuns

• Capturar tudo: prompts, respostas e argumentos podem expor dados sensíveis.
• Duplicar tokens: subconjuntos de cache e raciocínio são somados novamente.
• Usar PII como conversa: identificadores viram dado pessoal pesquisável.
• Confiar em conteúdo de evento: texto não confiável pode tentar orientar o agente.
• Instrumentar além do pedido: custo e volume crescem sem objetivo claro.
• Parar na configuração: nenhum evento real confirma o caminho.
• Confundir custo estimado com cobrança: descontos e itens não baseados em tokens podem ficar fora.
• Não definir retenção: o novo repositório de telemetria cresce sem governança.

Versão, licença e download local

O commit auditado é c1aab39520fc1f28ba23e969a2d6b74a87088038. A raiz do repositório apresenta MIT e a Skill declara Apache 2.0. Ambas permitem redistribuição sob condições próprias, mas a divergência deve ser verificada pelo usuário antes de adaptar o material.

O ZIP local tem SHA-256 71cc933e41b9a57be5a4cb66d24b135c66b46c9b219bd056c9f4059d7980ad72 e nove arquivos textuais. Ele exclui instaladores, código executável, dependências e dados de telemetria.

Limite final

Sentry Instrument melhora a visibilidade técnica, mas não mede sozinho utilidade, verdade ou segurança da resposta de IA. Combine traces com avaliações, feedback e revisão humana. Preserve a diferença entre comportamento observado e qualidade inferida.

Comece com menos dados e uma pergunta concreta. Amplie somente quando a utilidade estiver demonstrada e a governança estiver pronta.

Fontes primárias

• Diretório oficial no commit auditado
• SKILL.md oficial
• Licença raiz MIT
• Sentry Docs, AI monitoring
• OpenTelemetry, convenções semânticas de IA generativa