# 🐍 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