fix: add agent key auth for ingest endpoints
This commit is contained in:
415
docs/INSTRUMENTACAO.md
Normal file
415
docs/INSTRUMENTACAO.md
Normal file
@@ -0,0 +1,415 @@
|
||||
# 🐍 Ophion - Guia de Instrumentação OpenTelemetry
|
||||
|
||||
Este guia explica como adicionar auto-instrumentação OpenTelemetry a qualquer container Docker, enviando traces, métricas e logs para o Ophion.
|
||||
|
||||
## 📋 Índice
|
||||
|
||||
- [Arquitetura](#arquitetura)
|
||||
- [Setup Rápido](#setup-rápido)
|
||||
- [Variáveis de Ambiente](#variáveis-de-ambiente)
|
||||
- [Instrumentação por Linguagem](#instrumentação-por-linguagem)
|
||||
- [Node.js](#nodejs)
|
||||
- [Python](#python)
|
||||
- [Java](#java)
|
||||
- [Go](#go)
|
||||
- [.NET](#net)
|
||||
- [Instrumentação de Containers Existentes](#instrumentação-de-containers-existentes)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Arquitetura
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ Your App 1 │ │ Your App 2 │ │ Your App N │
|
||||
│ (Node.js/Python/│ │ (Java/Go/.NET) │ │ (Any language) │
|
||||
│ etc.) │ │ │ │ │
|
||||
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
|
||||
│ │ │
|
||||
│ OTLP (gRPC/HTTP) │ │
|
||||
│ │ │
|
||||
└───────────────────────┼───────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────┐
|
||||
│ OpenTelemetry │
|
||||
│ Collector │
|
||||
│ (otel-collector) │
|
||||
│ :4317 (gRPC) │
|
||||
│ :4318 (HTTP) │
|
||||
└────────────┬────────────┘
|
||||
│
|
||||
┌────────────▼────────────┐
|
||||
│ Ophion Server │
|
||||
│ (server:8080) │
|
||||
│ │
|
||||
│ Traces │ Metrics │ │
|
||||
│ Logs │ Alerts │
|
||||
└─────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Setup Rápido
|
||||
|
||||
### 1. Inicie o Ophion com o Collector
|
||||
|
||||
```bash
|
||||
cd ~/projetos_jarvis/ophion
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
O `otel-collector` estará disponível em:
|
||||
- **gRPC:** `otel-collector:4317`
|
||||
- **HTTP:** `otel-collector:4318`
|
||||
|
||||
### 2. Configure seu container
|
||||
|
||||
Adicione estas variáveis de ambiente ao seu serviço:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- OTEL_SERVICE_NAME=meu-servico
|
||||
- OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
|
||||
- OTEL_TRACES_EXPORTER=otlp
|
||||
- OTEL_METRICS_EXPORTER=otlp
|
||||
- OTEL_LOGS_EXPORTER=otlp
|
||||
```
|
||||
|
||||
### 3. Conecte à rede do Ophion
|
||||
|
||||
```yaml
|
||||
networks:
|
||||
- ophion
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Variáveis de Ambiente
|
||||
|
||||
### Essenciais
|
||||
|
||||
| Variável | Descrição | Exemplo |
|
||||
|----------|-----------|---------|
|
||||
| `OTEL_SERVICE_NAME` | Nome do seu serviço | `api-gateway` |
|
||||
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint do collector | `http://otel-collector:4318` |
|
||||
| `OTEL_TRACES_EXPORTER` | Exporter de traces | `otlp` |
|
||||
|
||||
### Opcionais (Recomendadas)
|
||||
|
||||
| Variável | Descrição | Default |
|
||||
|----------|-----------|---------|
|
||||
| `OTEL_SERVICE_VERSION` | Versão do serviço | - |
|
||||
| `OTEL_EXPORTER_OTLP_PROTOCOL` | Protocolo OTLP | `http/protobuf` |
|
||||
| `OTEL_METRICS_EXPORTER` | Exporter de métricas | `none` |
|
||||
| `OTEL_LOGS_EXPORTER` | Exporter de logs | `none` |
|
||||
| `OTEL_RESOURCE_ATTRIBUTES` | Atributos extras | `env=prod` |
|
||||
| `OTEL_TRACES_SAMPLER` | Tipo de sampler | `parentbased_always_on` |
|
||||
| `OTEL_TRACES_SAMPLER_ARG` | Argumento do sampler | `1.0` |
|
||||
| `OTEL_PROPAGATORS` | Formatos de propagação | `tracecontext,baggage` |
|
||||
|
||||
### Exemplo Completo
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
# Identificação
|
||||
- OTEL_SERVICE_NAME=meu-servico
|
||||
- OTEL_SERVICE_VERSION=1.2.3
|
||||
|
||||
# Endpoint
|
||||
- OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
|
||||
- OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
|
||||
|
||||
# Exporters
|
||||
- OTEL_TRACES_EXPORTER=otlp
|
||||
- OTEL_METRICS_EXPORTER=otlp
|
||||
- OTEL_LOGS_EXPORTER=otlp
|
||||
|
||||
# Recursos
|
||||
- OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production,team=backend
|
||||
|
||||
# Sampling (100% em dev, ajuste em prod)
|
||||
- OTEL_TRACES_SAMPLER=parentbased_traceidratio
|
||||
- OTEL_TRACES_SAMPLER_ARG=1.0
|
||||
|
||||
# Propagação (trace context para outros serviços)
|
||||
- OTEL_PROPAGATORS=tracecontext,baggage,b3multi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Instrumentação por Linguagem
|
||||
|
||||
### Node.js
|
||||
|
||||
**Auto-instrumentação sem alterar código:**
|
||||
|
||||
1. Instale os pacotes:
|
||||
```bash
|
||||
npm install @opentelemetry/auto-instrumentations-node @opentelemetry/api
|
||||
```
|
||||
|
||||
2. Configure no docker-compose.yml:
|
||||
```yaml
|
||||
environment:
|
||||
- OTEL_SERVICE_NAME=minha-api-node
|
||||
- OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
|
||||
- OTEL_TRACES_EXPORTER=otlp
|
||||
- NODE_OPTIONS=--require @opentelemetry/auto-instrumentations-node/register
|
||||
```
|
||||
|
||||
**Instrumentações automáticas incluídas:**
|
||||
- HTTP/Express/Fastify
|
||||
- MongoDB/PostgreSQL/MySQL
|
||||
- Redis/Memcached
|
||||
- gRPC
|
||||
- AWS SDK
|
||||
|
||||
### Python
|
||||
|
||||
**Auto-instrumentação sem alterar código:**
|
||||
|
||||
1. Instale os pacotes:
|
||||
```bash
|
||||
pip install opentelemetry-distro opentelemetry-exporter-otlp
|
||||
opentelemetry-bootstrap -a install
|
||||
```
|
||||
|
||||
2. Execute com o wrapper:
|
||||
```dockerfile
|
||||
CMD ["opentelemetry-instrument", "python", "app.py"]
|
||||
```
|
||||
|
||||
3. Configure no docker-compose.yml:
|
||||
```yaml
|
||||
environment:
|
||||
- OTEL_SERVICE_NAME=minha-api-python
|
||||
- OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
|
||||
- OTEL_TRACES_EXPORTER=otlp
|
||||
- OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
|
||||
```
|
||||
|
||||
**Instrumentações automáticas incluídas:**
|
||||
- Flask/Django/FastAPI
|
||||
- Requests/HTTPX/aiohttp
|
||||
- SQLAlchemy/psycopg2
|
||||
- Redis/Celery
|
||||
- boto3/botocore
|
||||
|
||||
### Java
|
||||
|
||||
**Auto-instrumentação via Java Agent:**
|
||||
|
||||
1. Baixe o agent no Dockerfile:
|
||||
```dockerfile
|
||||
RUN wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar \
|
||||
-O /opt/opentelemetry-javaagent.jar
|
||||
```
|
||||
|
||||
2. Configure no docker-compose.yml:
|
||||
```yaml
|
||||
environment:
|
||||
- OTEL_SERVICE_NAME=minha-api-java
|
||||
- OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
|
||||
- OTEL_TRACES_EXPORTER=otlp
|
||||
- JAVA_TOOL_OPTIONS=-javaagent:/opt/opentelemetry-javaagent.jar
|
||||
```
|
||||
|
||||
**Instrumentações automáticas incluídas:**
|
||||
- Spring Boot/Spring MVC
|
||||
- JAX-RS/Jersey
|
||||
- Hibernate/JPA
|
||||
- JDBC (PostgreSQL, MySQL, etc.)
|
||||
- Kafka/RabbitMQ
|
||||
- gRPC
|
||||
|
||||
### Go
|
||||
|
||||
Go requer instrumentação explícita no código, mas é simples:
|
||||
|
||||
```go
|
||||
import (
|
||||
"go.opentelemetry.io/otel"
|
||||
"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
|
||||
"go.opentelemetry.io/otel/sdk/trace"
|
||||
)
|
||||
|
||||
func initTracer() (*trace.TracerProvider, error) {
|
||||
exporter, err := otlptracehttp.New(context.Background())
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
tp := trace.NewTracerProvider(
|
||||
trace.WithBatcher(exporter),
|
||||
trace.WithResource(resource.NewWithAttributes(
|
||||
semconv.SchemaURL,
|
||||
semconv.ServiceName(os.Getenv("OTEL_SERVICE_NAME")),
|
||||
)),
|
||||
)
|
||||
|
||||
otel.SetTracerProvider(tp)
|
||||
return tp, nil
|
||||
}
|
||||
```
|
||||
|
||||
### .NET
|
||||
|
||||
**Auto-instrumentação via .NET OpenTelemetry:**
|
||||
|
||||
1. Adicione os pacotes:
|
||||
```bash
|
||||
dotnet add package OpenTelemetry.Extensions.Hosting
|
||||
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
|
||||
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
|
||||
```
|
||||
|
||||
2. Configure no Program.cs:
|
||||
```csharp
|
||||
builder.Services.AddOpenTelemetry()
|
||||
.WithTracing(tracing => tracing
|
||||
.AddAspNetCoreInstrumentation()
|
||||
.AddHttpClientInstrumentation()
|
||||
.AddOtlpExporter());
|
||||
```
|
||||
|
||||
3. Configure no docker-compose.yml:
|
||||
```yaml
|
||||
environment:
|
||||
- OTEL_SERVICE_NAME=minha-api-dotnet
|
||||
- OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Instrumentação de Containers Existentes
|
||||
|
||||
### Método 1: Modificar docker-compose.yml
|
||||
|
||||
Adicione ao seu serviço existente:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
meu-servico-existente:
|
||||
# ... configuração existente ...
|
||||
environment:
|
||||
# Adicione estas linhas:
|
||||
- OTEL_SERVICE_NAME=meu-servico
|
||||
- OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
|
||||
- OTEL_TRACES_EXPORTER=otlp
|
||||
# Para Node.js:
|
||||
- NODE_OPTIONS=--require @opentelemetry/auto-instrumentations-node/register
|
||||
# Para Java:
|
||||
# - JAVA_TOOL_OPTIONS=-javaagent:/opt/opentelemetry-javaagent.jar
|
||||
networks:
|
||||
- ophion
|
||||
|
||||
networks:
|
||||
ophion:
|
||||
external: true
|
||||
```
|
||||
|
||||
### Método 2: Docker Compose Override
|
||||
|
||||
Crie um arquivo `docker-compose.otel.yml`:
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
meu-servico:
|
||||
environment:
|
||||
- OTEL_SERVICE_NAME=meu-servico
|
||||
- OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
|
||||
- OTEL_TRACES_EXPORTER=otlp
|
||||
networks:
|
||||
- ophion
|
||||
|
||||
networks:
|
||||
ophion:
|
||||
external: true
|
||||
```
|
||||
|
||||
Execute com:
|
||||
```bash
|
||||
docker-compose -f docker-compose.yml -f docker-compose.otel.yml up -d
|
||||
```
|
||||
|
||||
### Método 3: Sidecar Pattern
|
||||
|
||||
Para aplicações que não suportam modificação:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
meu-servico:
|
||||
# Aplicação original sem modificação
|
||||
|
||||
otel-proxy:
|
||||
image: otel/opentelemetry-collector-contrib:latest
|
||||
command: ["--config=/etc/otel-config.yaml"]
|
||||
volumes:
|
||||
- ./otel-proxy-config.yaml:/etc/otel-config.yaml
|
||||
depends_on:
|
||||
- meu-servico
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Troubleshooting
|
||||
|
||||
### Traces não aparecem no Ophion
|
||||
|
||||
1. **Verifique conectividade:**
|
||||
```bash
|
||||
docker exec -it seu-container wget -q -O- http://otel-collector:13133/health
|
||||
```
|
||||
|
||||
2. **Verifique logs do collector:**
|
||||
```bash
|
||||
docker logs ophion-otel-collector
|
||||
```
|
||||
|
||||
3. **Verifique se as env vars estão corretas:**
|
||||
```bash
|
||||
docker exec -it seu-container env | grep OTEL
|
||||
```
|
||||
|
||||
### Erros de conexão
|
||||
|
||||
- Certifique-se que o container está na rede `ophion`
|
||||
- Use `otel-collector` (nome do serviço) e não `localhost`
|
||||
- Porta 4318 para HTTP, 4317 para gRPC
|
||||
|
||||
### Muitos traces (custo alto)
|
||||
|
||||
Ajuste o sampling:
|
||||
```yaml
|
||||
environment:
|
||||
- OTEL_TRACES_SAMPLER=parentbased_traceidratio
|
||||
- OTEL_TRACES_SAMPLER_ARG=0.1 # 10% dos traces
|
||||
```
|
||||
|
||||
### Traces incompletos
|
||||
|
||||
Verifique propagação entre serviços:
|
||||
```yaml
|
||||
environment:
|
||||
- OTEL_PROPAGATORS=tracecontext,baggage,b3multi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Exemplos
|
||||
|
||||
Veja os exemplos completos em:
|
||||
- `examples/docker/nodejs-instrumented/` - Node.js
|
||||
- `examples/docker/python-instrumented/` - Python
|
||||
- `examples/docker/java-instrumented/` - Java
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Suporte
|
||||
|
||||
- **Documentação OpenTelemetry:** https://opentelemetry.io/docs/
|
||||
- **Ophion Issues:** Abra uma issue no repositório
|
||||
- **Collector Debug:** Use `debug` exporter para troubleshooting
|
||||
Reference in New Issue
Block a user