416 lines
11 KiB
Markdown
416 lines
11 KiB
Markdown
# 🐍 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
|