flysloughofdespond447/claude-code-opentelemetry-setup

O que claude-code-opentelemetry-setup faz?

🚀 Monitore o uso do Claude Code com OpenTelemetry, Prometheus, Loki e Grafana para obter insights em tempo real sobre custos, uso de tokens e métricas de desempenho.

Visão Geral

Esta skill configura a telemetria do Claude Code usando o ecossistema OpenTelemetry, integrando-se ao Prometheus para coleta de métricas, Loki para agregação de logs e Grafana para dashboards visuais.

Funcionalidades

• Monitoramento de Custos: Acompanhe o custo de cada requisição ao Claude Code em tempo real.
• Uso de Tokens: Visualize o consumo de tokens (entrada e saída) por sessão ou por comando.
• Métricas de Desempenho: Latência, taxa de requisições, erros e mais.
• Dashboards Personalizados: Grafana com dashboards pré-configurados para análise imediata.
• Exportação de Dados: Dados exportados para Prometheus e Loki para consultas e alertas.

Pré-requisitos

• Docker e Docker Compose instalados.
• Claude Code CLI configurado e funcional.
• Acesso a um terminal com permissões de administrador (para instalação de pacotes, se necessário).

Instalação

1. Clone este repositório:

git clone https://github.com/flysloughofdespond447/claude-code-opentelemetry-setup.git
cd claude-code-opentelemetry-setup

2. Inicie o stack de monitoramento:

docker-compose up -d

3. Configure o Claude Code para usar o OpenTelemetry Collector. Isso geralmente é feito definindo as variáveis de ambiente:

export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
export OTEL_SERVICE_NAME="claude-code"

4. (Opcional) Importe o dashboard do Grafana para visualização imediata:

   • Acesse http://localhost:3000 (usuário: admin, senha: admin).
   • Vá em "Configuration" → "Data Sources" e adicione Prometheus (http://prometheus:9090) e Loki (http://loki:3100).
   • Importe o arquivo dashboard.json da pasta grafana/.

Como Usar

Após a configuração, qualquer requisição feita via Claude Code será automaticamente rastreada. Para verificar:

claude "explique este projeto"

As métricas aparecerão no Grafana em tempo real.

Estrutura do Projeto

.
├── docker-compose.yml
├── otel-collector-config.yaml
├── prometheus/
│   └── prometheus.yml
├── loki/
│   └── loki-config.yaml
├── grafana/
│   ├── dashboards/
│   │   └── claude-code-monitoring.json
│   └── datasources/
│       └── datasources.yaml
└── README.md

Solução de Problemas

• Portas já em uso: Altere as portas no docker-compose.yml.
• Métricas não aparecendo: Verifique se as variáveis de ambiente OTEL_EXPORTER_OTLP_ENDPOINT e OTEL_SERVICE_NAME estão configuradas corretamente.
• Grafana não carrega: Verifique os logs com docker-compose logs grafana.

Contribuição

Sinta-se à vontade para abrir issues ou enviar pull requests. Toda contribuição é bem-vinda!

Licença

MIT