ophion/docs/Manual-Tecnico.md

Manual Técnico - OPHION

1. Visão Geral

OPHION é uma plataforma open source de observabilidade que combina métricas, logs e traces com inteligência artificial para monitoramento proativo de infraestrutura.

2. Stack Tecnológico

Camada	Tecnologia	Versão
Backend	Go	1.22+
Frontend	Next.js	14.1.0
UI Components	Radix UI	Latest
Gráficos	Recharts, Chart.js, D3	Latest
Estilização	TailwindCSS	Latest
Observabilidade	OpenTelemetry	Latest
IA	OpenAI API	GPT-4
Container	Docker Compose	Latest

3. Estrutura do Projeto

ophion/
├── cmd/                      # Entry points
│   ├── server/main.go        # API Server principal
│   └── agent/main.go         # Agente de coleta
├── internal/                 # Código interno
│   ├── ai/                   # Módulos de IA
│   │   ├── engine.go         # Motor de IA
│   │   ├── insights.go       # Geração de insights
│   │   ├── autohealing.go    # Auto-recuperação
│   │   ├── smart_alerts.go   # Alertas inteligentes
│   │   └── copilot.go        # Assistente IA
│   ├── api/                  # Handlers da API
│   │   ├── ai_handlers.go    # Endpoints de IA
│   │   └── ratelimit.go      # Rate limiting
│   ├── auth/                 # Autenticação
│   │   ├── handlers.go
│   │   └── middleware.go
│   ├── otel/                 # OpenTelemetry
│   │   └── otlp_receiver.go  # Receptor OTLP
│   └── security/             # Segurança
│       └── security.go
├── dashboard/                # Frontend Next.js
│   ├── app/                  # App Router
│   ├── components/           # Componentes React
│   └── package.json
├── deploy/                   # Configurações de deploy
│   ├── docker/
│   └── remote-agent/
├── examples/                 # Exemplos de instrumentação
│   ├── otel-nodejs/
│   └── otel-python/
├── configs/                  # Configurações
├── web/                      # Assets web
├── docker-compose.yml        # Orquestração
├── instrument.sh             # Script de instrumentação
├── install.sh                # Script de instalação
├── go.mod / go.sum           # Dependências Go
└── README.md

4. Componentes do Sistema

4.1 API Server (Go)

• Porta: 8080
• Função: Backend principal, API REST, processamento de dados
• Módulos: Auth, AI, OTLP Receiver, Rate Limiting

4.2 Dashboard (Next.js)

• Porta: 3000
• Função: Interface web, visualização de métricas, configuração
• Tecnologias: React 18, TanStack Query, Recharts, D3

4.3 OTLP Receiver

• Portas: 4317 (gRPC), 4318 (HTTP)
• Função: Recepção de traces, métricas e logs via OpenTelemetry

4.4 Agente

• Função: Coleta de dados em hosts remotos
• Deploy: Container ou binário standalone

5. Módulos de IA

5.1 AI Engine

• Motor central de processamento de IA
• Integração com OpenAI GPT-4
• Cache de respostas

5.2 Insights

• Análise automática de padrões
• Detecção de anomalias
• Sugestões de otimização

5.3 Auto-Healing

• Detecção de problemas
• Execução automática de ações corretivas
• Playbooks configuráveis

5.4 Smart Alerts

• Correlação inteligente de alertas
• Redução de ruído
• Priorização automática

5.5 Copilot

• Assistente interativo via chat
• Consultas em linguagem natural
• Geração de queries e dashboards

6. API Endpoints

6.1 Autenticação

POST /api/auth/login
POST /api/auth/logout
GET  /api/auth/me

6.2 Métricas

GET  /api/metrics
GET  /api/metrics/:name
POST /api/metrics/query

6.3 Traces

GET  /api/traces
GET  /api/traces/:traceId
POST /api/traces/search

6.4 Logs

GET  /api/logs
POST /api/logs/query

6.5 IA

POST /api/ai/insights
POST /api/ai/chat
POST /api/ai/analyze
POST /api/ai/autohealing/trigger

6.6 Alertas

GET  /api/alerts
POST /api/alerts
PUT  /api/alerts/:id
DELETE /api/alerts/:id

7. Requisitos de Sistema

7.1 Servidor

• CPU: 4 cores
• RAM: 8GB
• Disco: 100GB SSD
• SO: Linux (Ubuntu 22.04+, Debian 12+)

7.2 Dependências

• Docker 24.0+
• Docker Compose 2.0+
• Go 1.22+ (para desenvolvimento)
• Node.js 20+ (para desenvolvimento)

7.3 Rede

• Porta 3000: Dashboard
• Porta 8080: API
• Porta 4317: OTLP gRPC
• Porta 4318: OTLP HTTP

8. Instalação e Deploy

8.1 Quick Start (Docker)

git clone https://github.com/bigtux/ophion.git
cd ophion
docker compose up -d

8.2 Instalação Completa

# Download e instalação
curl -fsSL https://ophion.io/install.sh | bash

# Configuração
cp .env.example .env
vim .env

# Iniciar
docker compose up -d

8.3 Variáveis de Ambiente

# API
API_PORT=8080
API_SECRET=your-secret-key

# OpenAI
OPENAI_API_KEY=sk-xxx

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ophion

# OTLP
OTLP_GRPC_PORT=4317
OTLP_HTTP_PORT=4318

9. Instrumentação de Aplicações

9.1 Script Universal

# Auto-detecta linguagem
./instrument.sh my-container

# Linguagem específica
./instrument.sh my-container nodejs
./instrument.sh my-container python
./instrument.sh my-container java
./instrument.sh my-container dotnet

9.2 Linguagens Suportadas

• Node.js (auto-instrumentation)
• Python (auto-instrumentation)
• Java (agent)
• .NET (auto-instrumentation)
• Go (manual/SDK)

10. Segurança

10.1 Autenticação

• JWT tokens
• Session management
• Role-based access control

10.2 Comunicação

• HTTPS obrigatório em produção
• TLS para OTLP
• API rate limiting

10.3 Dados

• Encryption at rest (opcional)
• Audit logging
• Data retention policies

11. Monitoramento da Própria Plataforma

• Health checks em todos os componentes
• Self-monitoring dashboard
• Alertas de sistema

---

Documento gerado automaticamente em 2026-02-09