# OPHION - Manual Técnico ## Plataforma de Observabilidade com IA --- ## 1. Visão Geral **OPHION** é uma plataforma de observabilidade open source que combina **métricas, logs e traces** em uma única solução, potencializada por **inteligência artificial** para monitoramento proativo e auto-healing. --- ## 2. Stack Tecnológico | Camada | Tecnologia | Função | |--------|------------|--------| | API Server | Go 1.22 | Backend principal | | Dashboard | Next.js + TypeScript | Interface web | | Collector | OpenTelemetry Collector | Ingestão de telemetria | | Database | PostgreSQL | Dados estruturados | | Time Series | ClickHouse | Métricas de alta performance | | Cache | Redis | Cache e filas | | Container | Docker Compose | Orquestração | --- ## 3. Arquitetura do Sistema ``` ┌─────────────────────────────────────────────────────────────────┐ │ APLICAÇÕES INSTRUMENTADAS │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Node.js │ │ Python │ │ Java │ │ .NET │ │ Go │ │ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │ └───────────┴───────────┼───────────┴───────────┘ │ │ │ OTLP (4317/4318) │ └───────────────────────────────┼─────────────────────────────────┘ │ ┌───────────────────────────────┼─────────────────────────────────┐ │ OPHION STACK ▼ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ OpenTelemetry Collector │ │ │ │ (receivers → processors → exporters) │ │ │ └─────────────────────────┬───────────────────────┘ │ │ │ │ │ ┌────────────────┐ ▼ ┌────────────────┐ │ │ │ Dashboard │◄───► Server ◄──►│ PostgreSQL │ │ │ │ (Next.js) │ (Go API) │ ClickHouse │ │ │ │ :3000 │ :8080 │ Redis │ │ │ └────────────────┘ └────────────────┘ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ AI Engine (Copilot) │ │ │ │ - Correlação de alertas │ │ │ │ - Previsão de capacidade │ │ │ │ - Auto-healing │ │ │ └────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 4. Estrutura de Diretórios ``` ophion/ ├── cmd/ │ ├── server/ # API Server (Go) │ └── agent/ # Agent de coleta ├── internal/ # Código interno Go │ ├── api/ # Handlers HTTP │ ├── db/ # Repositórios │ ├── ai/ # Engine de IA │ └── telemetry/ # Processamento OTLP ├── dashboard/ # Frontend Next.js │ ├── src/ │ │ ├── app/ # App Router │ │ ├── components/ # UI Components │ │ └── lib/ # Utilitários │ └── package.json ├── deploy/ │ ├── docker/ # Docker configs │ │ └── otel-collector-config.yaml │ ├── remote-agent/ # Agent remoto │ └── instrumentation/ # Scripts de instrumentação ├── examples/ # Exemplos por linguagem │ ├── otel-nodejs/ │ ├── otel-python/ │ └── docker/ ├── configs/ # Configurações ├── docs/ # Documentação ├── instrument.sh # Script de auto-instrumentação ├── install.sh # Instalador ├── docker-compose.yml ├── go.mod / go.sum └── server # Binário compilado ``` --- ## 5. Componentes Principais ### 5.1 OpenTelemetry Collector **Portas:** - `4317` - OTLP gRPC - `4318` - OTLP HTTP **Pipeline:** ```yaml receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: batch: timeout: 1s memory_limiter: limit_mib: 512 exporters: ophion: endpoint: http://server:8080 ``` ### 5.2 Server (Go API) **Endpoints principais:** | Endpoint | Método | Descrição | |----------|--------|-----------| | `/api/v1/traces` | POST | Ingestão de traces | | `/api/v1/metrics` | POST | Ingestão de métricas | | `/api/v1/logs` | POST | Ingestão de logs | | `/api/v1/services` | GET | Lista serviços | | `/api/v1/alerts` | GET/POST | Gerenciamento de alertas | | `/api/v1/ai/analyze` | POST | Análise por IA | ### 5.3 Dashboard (Next.js) **Recursos:** - Service Map visual - Trace waterfall - Métricas em tempo real - Logs agregados - Alertas e notificações - AI Copilot chat --- ## 6. Auto-Instrumentação ### 6.1 Script Universal ```bash # Auto-detecta linguagem ./instrument.sh # Especifica linguagem ./instrument.sh my-app nodejs ./instrument.sh my-app python ./instrument.sh my-app java ./instrument.sh my-app dotnet ``` ### 6.2 Suporte por Linguagem | Linguagem | Método | Complexidade | |-----------|--------|--------------| | .NET | Auto-instrumentation | Zero code | | Node.js | Auto-instrumentation | Zero code | | Python | Auto-instrumentation | Zero code | | Java | Java Agent | Zero code | | Go | SDK (compile-time) | Pequenas mudanças | | PHP | SDK | Pequenas mudanças | ### 6.3 Variáveis de Ambiente ```env OTEL_EXPORTER_OTLP_ENDPOINT=http://ophion:4318 OTEL_SERVICE_NAME=my-service OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production ``` --- ## 7. AI Engine ### 7.1 Funcionalidades - **Correlação de Alertas**: Agrupa alertas relacionados - **Root Cause Analysis**: Identifica causa raiz - **Previsão de Capacidade**: Prevê saturação de recursos - **Auto-Healing**: Executa ações corretivas automáticas - **Copilot**: Chat para consultas em linguagem natural ### 7.2 Integração OpenAI ```env OPENAI_API_KEY=sk-... AI_MODEL=gpt-4 ``` --- ## 8. Deploy ### 8.1 Quick Start (Docker) ```bash git clone https://github.com/bigtux/ophion.git cd ophion docker compose up -d ``` ### 8.2 Acessos | Serviço | URL | Porta | |---------|-----|-------| | Dashboard | http://localhost:3000 | 3000 | | API | http://localhost:8080 | 8080 | | OTLP gRPC | localhost:4317 | 4317 | | OTLP HTTP | localhost:4318 | 4318 | ### 8.3 Produção ```bash # Com install.sh ./install.sh --production # Ou manualmente docker compose -f docker-compose.prod.yml up -d ``` --- ## 9. Requisitos do Sistema | Recurso | Mínimo | Recomendado | |---------|--------|-------------| | CPU | 2 cores | 4+ cores | | RAM | 4 GB | 8+ GB | | Disco | 20 GB SSD | 100+ GB SSD | | Docker | 20.10+ | Latest | | Docker Compose | v2+ | Latest | --- ## 10. Configuração ### 10.1 Variáveis de Ambiente ```env # Server PORT=8080 DATABASE_URL=postgres://user:pass@localhost:5432/ophion REDIS_URL=redis://localhost:6379 CLICKHOUSE_URL=clickhouse://localhost:9000 # Auth JWT_SECRET=your-secret AGENT_KEY=agent-secret-key # AI OPENAI_API_KEY=sk-... AI_ENABLED=true # Notifications TELEGRAM_BOT_TOKEN=... TELEGRAM_CHAT_ID=... ``` ### 10.2 Configuração do Collector ```yaml # otel-collector-config.yaml receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: batch: timeout: 1s send_batch_size: 1024 exporters: otlphttp: endpoint: http://server:8080/api/v1 service: pipelines: traces: receivers: [otlp] processors: [batch] exporters: [otlphttp] ``` --- ## 11. Segurança - Autenticação JWT para dashboard - API Key para agents (`AGENT_KEY`) - TLS opcional para OTLP - Isolamento de rede via Docker - Logs de auditoria --- ## 12. Desenvolvimento ```bash # Backend (Go) go run ./cmd/server # Frontend (Next.js) cd dashboard npm install npm run dev # Testes go test ./... ``` --- ## 13. Troubleshooting | Problema | Solução | |----------|---------| | Traces não aparecem | Verificar OTEL_EXPORTER_OTLP_ENDPOINT | | Dashboard lento | Aumentar RAM do ClickHouse | | Collector crash | Verificar memory_limiter no config | | Auth falhando | Verificar JWT_SECRET | --- ## 14. Licença AGPL-3.0 (Community Edition) --- *Documento gerado automaticamente - OPHION*