PostHog LLM Analytics: rastros sem expor conversas

ANÁLISE EDITORIAL

Uma chamada de modelo pode funcionar e ainda esconder problemas que só aparecem em produção: custo inesperado, latência crescente, erro intermitente, contexto excessivo ou uma resposta impossível de relacionar ao restante da conversa. PostHog LLM Analytics Setup orienta um agente a instrumentar essas chamadas e transformá-las em eventos, gerações e rastros analisáveis.

A Skill vem do repositório oficial PostHog/skills. A curadoria do Bastidores da IA fixou o commit 870cdf070c94f2bf39d8b2a9d4916cfd44779cce, no qual o SKILL.md declara a versão 1.9.4. Em 28 de agosto de 2026, a API pública do GitHub registrava 60 estrelas, o repositório não estava arquivado e declarava licença MIT. A exceção ao piso de 1.000 estrelas foi aceita porque o mantenedor é o fornecedor oficial, há atividade recente, documentação, versão e licença verificáveis. Isso comprova origem, não popularidade.

Ilustração editorial exclusiva: a capa representa fluxos abstratos de entrada, resposta e métricas atravessando uma lente analítica. Não é captura de tela, dashboard real, logotipo da PostHog, telemetria coletada nem prova de aplicação instrumentada.

O que esta Skill faz de verdade

A instrução começa pela pilha que já existe. Em vez de adicionar suporte para todos os provedores, ela manda escolher somente o provedor ou framework usado pela aplicação e carregar a referência correspondente. A pasta auditada contém orientações para OpenAI, Azure OpenAI, Anthropic, Google, Cohere, Mistral, Perplexity, DeepSeek, Groq, Together AI, Fireworks AI, xAI, Cerebras, Hugging Face, Ollama, OpenRouter e várias bibliotecas de agentes.

O fluxo recomendado adiciona o SDK ou wrapper da PostHog ao redor da chamada existente. Segundo a documentação oficial de LLM Analytics, as chamadas continuam indo diretamente ao provedor, enquanto o wrapper extrai propriedades e envia eventos à PostHog. Uma geração pode registrar modelo, provedor, entrada, saída, tokens, latência e custo. Gerações e spans relacionados podem compartilhar um identificador de trace, formando a linha do tempo de uma interação.

Essa observabilidade não avalia automaticamente se uma resposta é verdadeira, segura ou útil. Ela oferece evidência operacional para investigar uma chamada e comparar comportamentos. Qualidade, revisão de conteúdo, consentimento e decisão de produto continuam fora da telemetria.

Para quem serve

A Skill é útil para desenvolvedores e equipes de produto que já operam uma função com LLM e precisam responder perguntas concretas. Qual modelo está mais lento? Uma mudança de prompt aumentou tokens? Um erro aparece só em determinado provedor? Quais chamadas pertencem à mesma conversa? O custo estimado acompanha o volume esperado?

Ela também ajuda SREs e responsáveis por FinOps a separar geração, trace, sessão e custo. A referência Traces define trace como agrupamento de gerações e spans, enquanto sessão é um agrupamento opcional de vários traces. Essa diferença evita usar um identificador de conversa como se fosse a unidade de uma única execução.

Não é a melhor escolha para uma aplicação sem política de telemetria, sem base legal para tratar dados pessoais ou sem responsável por retenção e acesso. Também não substitui logs de infraestrutura, avaliação de qualidade, testes de carga ou monitoramento do provedor. Se a equipe só precisa medir quantidade de chamadas, uma captura mínima e agregada pode ser mais adequada que armazenar conteúdo completo.

Compatibilidade e pré-requisitos

O runtime canônico é uma aplicação que use um SDK ou uma integração compatível. As referências auditadas cobrem Python e Node.js com maior frequência, além de wrappers para frameworks como LangChain, LlamaIndex, CrewAI, AutoGen, DSPy, LangGraph, Pydantic AI, Vercel AI SDK, LiteLLM, Semantic Kernel e OpenAI Agents SDK. A compatibilidade real depende das versões instaladas e deve ser confirmada na referência escolhida.

Antes de editar código, identifique linguagem, gerenciador de dependências, provedor, método síncrono ou assíncrono, streaming, ambiente de execução e onde a aplicação encerra o cliente. O SKILL.md lembra que processos curtos precisam fazer flush ou shutdown para não perder eventos. Isso é comportamento de entrega assíncrona, não garantia de que todo evento chegará.

Você também precisa de um projeto PostHog autorizado, token do projeto, host correspondente à região e credencial do provedor de modelo. Nenhuma dessas credenciais faz parte do download local. Guarde segredos em variáveis de ambiente ou no cofre já adotado pelo projeto. Nunca copie token real para prompt, exemplo, commit, captura ou relatório.

Instalação recomendada

A rota oficial do repositório documenta instalação por marketplace do Claude Code e cópia manual de uma pasta de Skill. O README do commit auditado deve prevalecer sobre comandos lembrados de outra versão. Em clientes compatíveis com Agent Skills, copie a pasta completa llm-analytics-setup para o escopo de projeto aceito pelo host e preserve SKILL.md junto com references.

O ZIP do Bastidores é documental. Ele contém 40 arquivos textuais: SKILL.md, 37 referências Markdown, LICENSE e ORIGEM.md. Não inclui plugin, SDK, CLI, scripts, binários, dependências, chaves, tokens, credenciais ou dados de telemetria. Para uso funcional, instale dependências somente depois de revisar a referência do provedor e o diff proposto para a aplicação.

Faça a primeira instalação em branch separada e ambiente descartável. Não misture instrumentação com uma migração de SDK, refatoração da regra de negócio ou troca de provedor. Mudanças mínimas facilitam comparar comportamento antes e depois e tornam o rollback compreensível.

Configuração antes do primeiro uso

Defina primeiro um contrato de dados. Liste cada propriedade que poderá sair da aplicação, finalidade, responsável, retenção, região, acesso e condição de descarte. As referências mostram que uma geração pode conter a entrada e a saída completas. Isso significa que prompts, mensagens de sistema, respostas, resultados de ferramentas e trechos recuperados podem carregar dados pessoais, segredos comerciais ou conteúdo confidencial.

O SKILL.md proíbe PII em propriedades de eventos e sugere propriedades de pessoa para identificação. Essa orientação técnica não é autorização jurídica nem política suficiente. Dados pessoais continuam pessoais quando armazenados em outro campo. A configuração conservadora é começar sem conteúdo, sem identificador direto e com dados sintéticos, registrando apenas modelo, status, latência, contagem de tokens e um trace aleatório. Depois, amplie somente o que tiver finalidade e aprovação claras.

Revise o modo de privacidade descrito nas referências do provedor. Confirme no SDK instalado quais campos ele remove, quais permanecem e como streaming, ferramentas e exceções são tratados. Não suponha que um nome como privacy_mode elimine todos os dados sensíveis. Faça uma captura controlada e leia o evento resultante antes de habilitar produção.

Primeiro uso seguro

Escolha uma chamada de teste simples, sem dados de cliente e sem ferramenta externa. Use um usuário sintético, um trace novo e um prompt banal. Instrumente somente esse caminho. Execute uma vez e confira quatro lugares: resposta do provedor, evento recebido, trace montado e logs locais de erro.

Compare o evento com o contrato aprovado. O modelo e o provedor correspondem à chamada? A latência usa a unidade esperada? Tokens de entrada e saída vieram do SDK ou de estimativa? O conteúdo foi omitido quando deveria? O identificador não revela e-mail, nome, telefone, IP ou código interno? Se qualquer campo exceder o contrato, desligue a captura e corrija antes de repetir.

Depois teste uma falha deliberada e segura, como uma chave falsa em ambiente isolado ou um timeout controlado. O objetivo é verificar como exceções são registradas sem ativar coleta ampla. O SKILL.md recomenda autocaptura de exceções no cliente Python, mas essa opção pode incluir contexto que a organização não deseja transmitir. Valide o payload real e não habilite por hábito.

Resultado esperado

O resultado mínimo é um trace reproduzível que agrupe chamadas relacionadas e permita ver modelo, provedor, duração, tokens, estado de erro e custo calculado ou informado. A página oficial sobre generations descreve a unidade de uma chamada; a documentação de spans cobre operações internas relacionadas.

Registre junto ao teste o commit da aplicação, versões dos SDKs, ambiente, política de conteúdo e exemplos sintéticos usados. Um dashboard sem essas referências pode mostrar tendência, mas não explica por que os números mudaram. Preserve também uma forma de desativar a instrumentação e uma consulta que comprove ausência de eventos quando o recurso estiver desligado.

Custos exigem interpretação. A referência Calculating LLM costs informa que a PostHog combina provedor, modelo e tokens com dados de preço, incluindo componentes de cache, requisição e busca quando aplicáveis. Preço pode mudar e contratos privados podem divergir. Use o valor como estimativa operacional até reconciliar com a fatura do provedor.

Permissões e riscos

A Skill é textual, mas sua execução pode alterar dependências, imports, inicialização de clientes, variáveis de ambiente e encerramento do processo. Também cria um novo fluxo de dados para um serviço externo. Trate instalação e transmissão como decisões separadas: revisar código não autoriza enviar conteúdo de produção.

Os riscos principais são exposição de prompts e respostas, identificação excessiva, retenção indefinida, acesso amplo ao painel, aumento de custo por volume de eventos, latência adicional no encerramento e perda silenciosa de eventos se o cliente não fizer flush. Trace IDs e session IDs também podem virar identificadores indiretos se forem derivados de dados de negócio.

Restrinja tokens ao projeto correto, separe ambientes, aplique menor privilégio, mantenha host e região explícitos e evite eventos de desenvolvimento no projeto de produção. Revise consentimento, base legal, contrato, retenção e direitos do titular com os responsáveis internos. Esta página não oferece aconselhamento jurídico.

Erros comuns

O trace não aparece. Confira host, token do projeto, rede, fila assíncrona e chamada de shutdown. Processos curtos podem terminar antes do envio.

Há gerações, mas não um trace único. Verifique se as chamadas relacionadas recebem o mesmo $ai_trace_id. Não gere um ID diferente a cada etapa se a intenção é mostrar uma interação completa.

O custo parece incorreto. Confirme provedor, nome exato do modelo, tokens de cache e preço personalizado. Não confronte uma estimativa com a fatura sem alinhar período, moeda, desconto e componentes cobrados.

Conteúdo sensível apareceu no evento. Desligue a captura, aplique o procedimento de incidente e retenção da organização, remova o campo na origem e repita somente com dados sintéticos. Mascarar no dashboard não desfaz a transmissão anterior.

Streaming ou ferramenta não é registrado. Verifique se o wrapper suporta o método usado pela versão instalada. Uma integração que cobre create pode não cobrir outro método de streaming. Leia o código e a documentação atuais antes de adaptar.

Versão auditada e download local

A curadoria auditou a versão 1.9.4 no commit 870cdf070c94f2bf39d8b2a9d4916cfd44779cce, com licença MIT. O repositório oficial tinha 60 estrelas na consulta de 28 de agosto de 2026. O pacote local tem 93.655 bytes e SHA-256 91909375a9d3b5d9ed8c81d8b794dcc1e6d47c564603b631a9a81ba1ee3d3e7a.

Baixar o pacote documental auditado. Confira o hash depois do download. Para instalar ou atualizar a Skill funcional, use o diretório oficial fixado no commit e revise todas as referências aplicáveis ao seu provedor.

Resultado esperado e limite final

PostHog LLM Analytics Setup deve produzir instrumentação pequena, rastreável e reversível. O primeiro sucesso não é um painel cheio. É um único evento sintético cujo conteúdo, custo, latência e identificação correspondem ao contrato aprovado.

A Skill não prova qualidade do modelo, não garante cálculo perfeito, não substitui consentimento e não decide quais dados a organização pode armazenar. Traces ajudam a investigar comportamento. A decisão de enviar, reter, correlacionar e interpretar cada campo continua humana.

Fontes primárias

• Repositório oficial PostHog Skills
• Pasta da Skill no commit auditado
• SKILL.md versão 1.9.4
• Licença MIT
• Documentação oficial de LLM Analytics
• Instalação oficial
• Captura manual oficial
• Traces e agrupamento de chamadas
• Cálculo de custos
• Especificação Agent Skills