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:

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

# Auto-detecta linguagem
./instrument.sh <container-name>

# 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

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

OPENAI_API_KEY=sk-...
AI_MODEL=gpt-4

8. Deploy

8.1 Quick Start (Docker)

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

# 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

# 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

# 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

# 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