bigtux/ophion
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
3be72d9c7f17eb485eb72a5dfdf067132b8f039e
ophion/docs/manual_tecnico.html
bigtux 3be72d9c7f Sync to Gitea
2026-02-11 11:59:03 -03:00

565 lines
15 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>OPHION - Manual Técnico</title>
<style>
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
color: #2D3142;
background: white;
line-height: 1.6;
padding: 40px 60px;
max-width: 900px;
margin: 0 auto;
}
h1 {
color: #1A7A4C;
font-size: 28px;
margin-bottom: 20px;
padding-bottom: 10px;
border-bottom: 3px solid #1A7A4C;
}
h2 {
color: #1A7A4C;
font-size: 22px;
margin-top: 30px;
margin-bottom: 15px;
}
h3 {
color: #1A7A4C;
font-size: 18px;
margin-top: 20px;
margin-bottom: 10px;
}
p {
margin-bottom: 12px;
}
table {
width: 100%;
border-collapse: collapse;
margin: 20px 0;
}
th, td {
border: 1px solid #E2E4E8;
padding: 12px;
text-align: left;
}
th {
background: #1A7A4C;
color: white;
font-weight: 600;
}
tr:nth-child(even) {
background: #f9f9f9;
}
code {
background: #f4f4f4;
padding: 2px 6px;
border-radius: 4px;
font-family: 'Courier New', monospace;
font-size: 14px;
}
pre {
background: #1e1e1e;
color: #d4d4d4;
padding: 20px;
border-radius: 8px;
overflow-x: auto;
margin: 20px 0;
}
pre code {
background: none;
padding: 0;
color: inherit;
}
ul, ol {
margin: 15px 0;
padding-left: 30px;
}
li {
margin-bottom: 8px;
}
blockquote {
border-left: 4px solid #1A7A4C;
padding-left: 20px;
margin: 20px 0;
font-style: italic;
color: #555;
}
hr {
border: none;
border-top: 2px solid #E2E4E8;
margin: 30px 0;
}
strong {
color: #1A7A4C;
}
.page-break {
page-break-after: always;
}
</style>
</head>
<body>
<h1>OPHION - Manual Técnico</h1>
<h2>Plataforma de Observabilidade com IA</h2>
<hr />
<h2>1. Visão Geral</h2>
<p><strong>OPHION</strong> é uma plataforma de observabilidade open source que combina <strong>métricas, logs e traces</strong> em uma única solução, potencializada por <strong>inteligência artificial</strong> para monitoramento proativo e auto-healing.</p>
<hr />
<h2>2. Stack Tecnológico</h2>
<table>
<thead>
<tr>
<th>Camada</th>
<th>Tecnologia</th>
<th>Função</th>
</tr>
</thead>
<tbody>
<tr>
<td>API Server</td>
<td>Go 1.22</td>
<td>Backend principal</td>
</tr>
<tr>
<td>Dashboard</td>
<td>Next.js + TypeScript</td>
<td>Interface web</td>
</tr>
<tr>
<td>Collector</td>
<td>OpenTelemetry Collector</td>
<td>Ingestão de telemetria</td>
</tr>
<tr>
<td>Database</td>
<td>PostgreSQL</td>
<td>Dados estruturados</td>
</tr>
<tr>
<td>Time Series</td>
<td>ClickHouse</td>
<td>Métricas de alta performance</td>
</tr>
<tr>
<td>Cache</td>
<td>Redis</td>
<td>Cache e filas</td>
</tr>
<tr>
<td>Container</td>
<td>Docker Compose</td>
<td>Orquestração</td>
</tr>
</tbody>
</table>
<hr />
<h2>3. Arquitetura do Sistema</h2>
<pre><code>┌─────────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
</code></pre>
<hr />
<h2>4. Estrutura de Diretórios</h2>
<pre><code>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
</code></pre>
<hr />
<h2>5. Componentes Principais</h2>
<h3>5.1 OpenTelemetry Collector</h3>
<p><strong>Portas:</strong>
- <code>4317</code> - OTLP gRPC
- <code>4318</code> - OTLP HTTP</p>
<p><strong>Pipeline:</strong></p>
<pre><code class="language-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
</code></pre>
<h3>5.2 Server (Go API)</h3>
<p><strong>Endpoints principais:</strong></p>
<table>
<thead>
<tr>
<th>Endpoint</th>
<th>Método</th>
<th>Descrição</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>/api/v1/traces</code></td>
<td>POST</td>
<td>Ingestão de traces</td>
</tr>
<tr>
<td><code>/api/v1/metrics</code></td>
<td>POST</td>
<td>Ingestão de métricas</td>
</tr>
<tr>
<td><code>/api/v1/logs</code></td>
<td>POST</td>
<td>Ingestão de logs</td>
</tr>
<tr>
<td><code>/api/v1/services</code></td>
<td>GET</td>
<td>Lista serviços</td>
</tr>
<tr>
<td><code>/api/v1/alerts</code></td>
<td>GET/POST</td>
<td>Gerenciamento de alertas</td>
</tr>
<tr>
<td><code>/api/v1/ai/analyze</code></td>
<td>POST</td>
<td>Análise por IA</td>
</tr>
</tbody>
</table>
<h3>5.3 Dashboard (Next.js)</h3>
<p><strong>Recursos:</strong>
- Service Map visual
- Trace waterfall
- Métricas em tempo real
- Logs agregados
- Alertas e notificações
- AI Copilot chat</p>
<hr />
<h2>6. Auto-Instrumentação</h2>
<h3>6.1 Script Universal</h3>
<pre><code class="language-bash"># Auto-detecta linguagem
./instrument.sh &lt;container-name&gt;
# Especifica linguagem
./instrument.sh my-app nodejs
./instrument.sh my-app python
./instrument.sh my-app java
./instrument.sh my-app dotnet
</code></pre>
<h3>6.2 Suporte por Linguagem</h3>
<table>
<thead>
<tr>
<th>Linguagem</th>
<th>Método</th>
<th>Complexidade</th>
</tr>
</thead>
<tbody>
<tr>
<td>.NET</td>
<td>Auto-instrumentation</td>
<td>Zero code</td>
</tr>
<tr>
<td>Node.js</td>
<td>Auto-instrumentation</td>
<td>Zero code</td>
</tr>
<tr>
<td>Python</td>
<td>Auto-instrumentation</td>
<td>Zero code</td>
</tr>
<tr>
<td>Java</td>
<td>Java Agent</td>
<td>Zero code</td>
</tr>
<tr>
<td>Go</td>
<td>SDK (compile-time)</td>
<td>Pequenas mudanças</td>
</tr>
<tr>
<td>PHP</td>
<td>SDK</td>
<td>Pequenas mudanças</td>
</tr>
</tbody>
</table>
<h3>6.3 Variáveis de Ambiente</h3>
<pre><code class="language-env">OTEL_EXPORTER_OTLP_ENDPOINT=http://ophion:4318
OTEL_SERVICE_NAME=my-service
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production
</code></pre>
<hr />
<h2>7. AI Engine</h2>
<h3>7.1 Funcionalidades</h3>
<ul>
<li><strong>Correlação de Alertas</strong>: Agrupa alertas relacionados</li>
<li><strong>Root Cause Analysis</strong>: Identifica causa raiz</li>
<li><strong>Previsão de Capacidade</strong>: Prevê saturação de recursos</li>
<li><strong>Auto-Healing</strong>: Executa ações corretivas automáticas</li>
<li><strong>Copilot</strong>: Chat para consultas em linguagem natural</li>
</ul>
<h3>7.2 Integração OpenAI</h3>
<pre><code class="language-env">OPENAI_API_KEY=sk-...
AI_MODEL=gpt-4
</code></pre>
<hr />
<h2>8. Deploy</h2>
<h3>8.1 Quick Start (Docker)</h3>
<pre><code class="language-bash">git clone https://github.com/bigtux/ophion.git
cd ophion
docker compose up -d
</code></pre>
<h3>8.2 Acessos</h3>
<table>
<thead>
<tr>
<th>Serviço</th>
<th>URL</th>
<th>Porta</th>
</tr>
</thead>
<tbody>
<tr>
<td>Dashboard</td>
<td>http://localhost:3000</td>
<td>3000</td>
</tr>
<tr>
<td>API</td>
<td>http://localhost:8080</td>
<td>8080</td>
</tr>
<tr>
<td>OTLP gRPC</td>
<td>localhost:4317</td>
<td>4317</td>
</tr>
<tr>
<td>OTLP HTTP</td>
<td>localhost:4318</td>
<td>4318</td>
</tr>
</tbody>
</table>
<h3>8.3 Produção</h3>
<pre><code class="language-bash"># Com install.sh
./install.sh --production
# Ou manualmente
docker compose -f docker-compose.prod.yml up -d
</code></pre>
<hr />
<h2>9. Requisitos do Sistema</h2>
<table>
<thead>
<tr>
<th>Recurso</th>
<th>Mínimo</th>
<th>Recomendado</th>
</tr>
</thead>
<tbody>
<tr>
<td>CPU</td>
<td>2 cores</td>
<td>4+ cores</td>
</tr>
<tr>
<td>RAM</td>
<td>4 GB</td>
<td>8+ GB</td>
</tr>
<tr>
<td>Disco</td>
<td>20 GB SSD</td>
<td>100+ GB SSD</td>
</tr>
<tr>
<td>Docker</td>
<td>20.10+</td>
<td>Latest</td>
</tr>
<tr>
<td>Docker Compose</td>
<td>v2+</td>
<td>Latest</td>
</tr>
</tbody>
</table>
<hr />
<h2>10. Configuração</h2>
<h3>10.1 Variáveis de Ambiente</h3>
<pre><code class="language-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=...
</code></pre>
<h3>10.2 Configuração do Collector</h3>
<pre><code class="language-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]
</code></pre>
<hr />
<h2>11. Segurança</h2>
<ul>
<li>Autenticação JWT para dashboard</li>
<li>API Key para agents (<code>AGENT_KEY</code>)</li>
<li>TLS opcional para OTLP</li>
<li>Isolamento de rede via Docker</li>
<li>Logs de auditoria</li>
</ul>
<hr />
<h2>12. Desenvolvimento</h2>
<pre><code class="language-bash"># Backend (Go)
go run ./cmd/server
# Frontend (Next.js)
cd dashboard
npm install
npm run dev
# Testes
go test ./...
</code></pre>
<hr />
<h2>13. Troubleshooting</h2>
<table>
<thead>
<tr>
<th>Problema</th>
<th>Solução</th>
</tr>
</thead>
<tbody>
<tr>
<td>Traces não aparecem</td>
<td>Verificar OTEL_EXPORTER_OTLP_ENDPOINT</td>
</tr>
<tr>
<td>Dashboard lento</td>
<td>Aumentar RAM do ClickHouse</td>
</tr>
<tr>
<td>Collector crash</td>
<td>Verificar memory_limiter no config</td>
</tr>
<tr>
<td>Auth falhando</td>
<td>Verificar JWT_SECRET</td>
</tr>
</tbody>
</table>
<hr />
<h2>14. Licença</h2>
<p>AGPL-3.0 (Community Edition)</p>
<hr />
<p><em>Documento gerado automaticamente - OPHION</em></p>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink