docs: add complete OPHION manual with logo
This commit is contained in:
479
docs/MANUAL_OPHION.md
Normal file
479
docs/MANUAL_OPHION.md
Normal file
@@ -0,0 +1,479 @@
|
||||
<p align="center">
|
||||
<img src="../docs/ophion_snake_logo.png" alt="OPHION Logo" width="120"/>
|
||||
</p>
|
||||
|
||||
<h1 align="center">🐍 OPHION</h1>
|
||||
<h3 align="center">Open Source Observability Platform — AI-Powered</h3>
|
||||
|
||||
<p align="center">
|
||||
<strong>Métricas • Traces • Logs • Alertas</strong><br>
|
||||
<em>Monitoramento completo para suas aplicações</em>
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
# 📖 Manual de Instalação e Uso
|
||||
|
||||
**Versão:** 1.0
|
||||
**Data:** Fevereiro 2026
|
||||
**Website:** [ophion.com.br](https://ophion.com.br)
|
||||
|
||||
---
|
||||
|
||||
## 📋 Índice
|
||||
|
||||
1. [Visão Geral](#1-visão-geral)
|
||||
2. [Requisitos](#2-requisitos)
|
||||
3. [Instalação](#3-instalação)
|
||||
4. [Primeiro Acesso](#4-primeiro-acesso)
|
||||
5. [Instalando o Agent](#5-instalando-o-agent)
|
||||
6. [Instrumentação de Aplicações](#6-instrumentação-de-aplicações)
|
||||
7. [Dashboard](#7-dashboard)
|
||||
8. [API Reference](#8-api-reference)
|
||||
9. [Segurança](#9-segurança)
|
||||
10. [Troubleshooting](#10-troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## 1. Visão Geral
|
||||
|
||||
O **OPHION** é uma plataforma de observabilidade open source que unifica:
|
||||
|
||||
| Funcionalidade | Descrição |
|
||||
|----------------|-----------|
|
||||
| **Métricas** | CPU, RAM, disco, rede, containers |
|
||||
| **Traces** | Rastreamento distribuído de requests |
|
||||
| **Logs** | Coleta e busca centralizada |
|
||||
| **Alertas** | Notificações configuráveis |
|
||||
|
||||
### Diferenciais
|
||||
|
||||
- ✅ **Open Source** — Sem custos de licença
|
||||
- ✅ **Auto-instrumentação** — Suporte a todas linguagens
|
||||
- ✅ **OpenTelemetry** — Padrão de mercado
|
||||
- ✅ **Fácil instalação** — Um comando para subir
|
||||
- ✅ **Segurança** — JWT + API Keys
|
||||
|
||||
---
|
||||
|
||||
## 2. Requisitos
|
||||
|
||||
### Hardware Mínimo
|
||||
|
||||
| Recurso | Mínimo | Recomendado |
|
||||
|---------|--------|-------------|
|
||||
| CPU | 2 cores | 4+ cores |
|
||||
| RAM | 4 GB | 8+ GB |
|
||||
| Disco | 20 GB SSD | 100+ GB SSD |
|
||||
|
||||
### Software
|
||||
|
||||
- **Sistema Operacional:** Linux (Ubuntu 20.04+, Debian, CentOS)
|
||||
- **Docker:** 20.10+
|
||||
- **Docker Compose:** v2.0+
|
||||
|
||||
### Verificar instalação do Docker
|
||||
|
||||
```bash
|
||||
docker --version
|
||||
docker compose version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Instalação
|
||||
|
||||
### 3.1 Clone o repositório
|
||||
|
||||
```bash
|
||||
git clone https://github.com/bigtux/ophion.git
|
||||
cd ophion
|
||||
```
|
||||
|
||||
### 3.2 Inicie a stack
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
### 3.3 Verifique os containers
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
Saída esperada:
|
||||
```
|
||||
NAME STATUS PORTS
|
||||
ophion Up (healthy) 0.0.0.0:3000->3000, 0.0.0.0:8080->8080
|
||||
postgres Up 5432
|
||||
redis Up 6379
|
||||
```
|
||||
|
||||
### 3.4 Acesse
|
||||
|
||||
| Serviço | URL |
|
||||
|---------|-----|
|
||||
| Dashboard | http://seu-servidor:3000 |
|
||||
| API | http://seu-servidor:8080 |
|
||||
| Health Check | http://seu-servidor:8080/health |
|
||||
|
||||
---
|
||||
|
||||
## 4. Primeiro Acesso
|
||||
|
||||
### 4.1 Criar usuário administrador
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/auth/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"email": "admin@suaempresa.com",
|
||||
"password": "SenhaForte123!"
|
||||
}'
|
||||
```
|
||||
|
||||
Resposta:
|
||||
```json
|
||||
{
|
||||
"message": "User registered successfully",
|
||||
"token": "eyJhbG...",
|
||||
"user": {
|
||||
"email": "admin@suaempresa.com",
|
||||
"role": "admin"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 Acessar o Dashboard
|
||||
|
||||
1. Abra http://seu-servidor:3000/login
|
||||
2. Digite o email e senha cadastrados
|
||||
3. Clique em **Login**
|
||||
|
||||
---
|
||||
|
||||
## 5. Instalando o Agent
|
||||
|
||||
O Agent coleta métricas do servidor (CPU, RAM, disco, rede, containers).
|
||||
|
||||
### 5.1 No servidor a ser monitorado
|
||||
|
||||
```bash
|
||||
# Clone o repositório
|
||||
git clone https://github.com/bigtux/ophion.git
|
||||
cd ophion
|
||||
|
||||
# Instale Go (se necessário)
|
||||
apt update && apt install -y golang-go
|
||||
|
||||
# Compile o agent
|
||||
go mod tidy
|
||||
go build -o ophion-agent ./cmd/agent
|
||||
|
||||
# Execute
|
||||
export OPHION_SERVER=http://IP_DO_SERVIDOR_OPHION:8080
|
||||
export AGENT_KEY=ophion-secret-agent-key-2024
|
||||
nohup ./ophion-agent > /var/log/ophion-agent.log 2>&1 &
|
||||
```
|
||||
|
||||
### 5.2 Verificar funcionamento
|
||||
|
||||
```bash
|
||||
cat /var/log/ophion-agent.log
|
||||
```
|
||||
|
||||
Saída esperada:
|
||||
```
|
||||
🐍 OPHION Agent starting
|
||||
Server: http://10.0.0.5:8080
|
||||
Host: meu-servidor
|
||||
Interval: 30s
|
||||
Docker: true
|
||||
📤 Sent 12 metrics
|
||||
```
|
||||
|
||||
### 5.3 Configuração como serviço (systemd)
|
||||
|
||||
```bash
|
||||
cat > /etc/systemd/system/ophion-agent.service << EOF
|
||||
[Unit]
|
||||
Description=OPHION Agent
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
Environment="OPHION_SERVER=http://IP_OPHION:8080"
|
||||
Environment="AGENT_KEY=ophion-secret-agent-key-2024"
|
||||
ExecStart=/opt/ophion/ophion-agent
|
||||
Restart=always
|
||||
RestartSec=10
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
systemctl daemon-reload
|
||||
systemctl enable ophion-agent
|
||||
systemctl start ophion-agent
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Instrumentação de Aplicações
|
||||
|
||||
Para ver **traces** das aplicações, é necessário instrumentá-las.
|
||||
|
||||
### 6.1 Script Universal
|
||||
|
||||
```bash
|
||||
./instrument.sh <container> <linguagem> <ophion_server>
|
||||
```
|
||||
|
||||
**Linguagens suportadas:** `dotnet`, `nodejs`, `python`, `java`, `go`, `php`
|
||||
|
||||
### 6.2 Exemplos por Linguagem
|
||||
|
||||
#### .NET
|
||||
|
||||
```bash
|
||||
./instrument.sh minha-api-dotnet dotnet http://10.0.0.5:8080
|
||||
```
|
||||
|
||||
Ou manualmente no docker-compose:
|
||||
```yaml
|
||||
services:
|
||||
minha-api:
|
||||
image: minha-api:latest
|
||||
environment:
|
||||
- OTEL_SERVICE_NAME=minha-api
|
||||
- OTEL_EXPORTER_OTLP_ENDPOINT=http://ophion:8080
|
||||
- CORECLR_ENABLE_PROFILING=1
|
||||
- CORECLR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658571}
|
||||
- CORECLR_PROFILER_PATH=/otel/dotnet/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so
|
||||
- DOTNET_ADDITIONAL_DEPS=/otel/dotnet/AdditionalDeps
|
||||
- DOTNET_SHARED_STORE=/otel/dotnet/store
|
||||
- DOTNET_STARTUP_HOOKS=/otel/dotnet/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll
|
||||
volumes:
|
||||
- ophion-otel-agents:/otel:ro
|
||||
```
|
||||
|
||||
#### Node.js
|
||||
|
||||
```bash
|
||||
./instrument.sh minha-api-node nodejs http://10.0.0.5:8080
|
||||
```
|
||||
|
||||
Ou no código:
|
||||
```javascript
|
||||
// Adicione no início do app (antes de tudo)
|
||||
require('@opentelemetry/auto-instrumentations-node/register');
|
||||
```
|
||||
|
||||
```bash
|
||||
npm install @opentelemetry/auto-instrumentations-node
|
||||
|
||||
OTEL_SERVICE_NAME=minha-api \
|
||||
OTEL_EXPORTER_OTLP_ENDPOINT=http://ophion:8080 \
|
||||
node app.js
|
||||
```
|
||||
|
||||
#### Python
|
||||
|
||||
```bash
|
||||
./instrument.sh minha-api-python python http://10.0.0.5:8080
|
||||
```
|
||||
|
||||
Ou manualmente:
|
||||
```bash
|
||||
pip install opentelemetry-distro opentelemetry-exporter-otlp
|
||||
opentelemetry-bootstrap -a install
|
||||
|
||||
OTEL_SERVICE_NAME=minha-api \
|
||||
OTEL_EXPORTER_OTLP_ENDPOINT=http://ophion:8080 \
|
||||
opentelemetry-instrument python app.py
|
||||
```
|
||||
|
||||
#### Java
|
||||
|
||||
```bash
|
||||
./instrument.sh minha-api-java java http://10.0.0.5:8080
|
||||
```
|
||||
|
||||
Ou no docker-compose:
|
||||
```yaml
|
||||
services:
|
||||
minha-api:
|
||||
image: minha-api:latest
|
||||
environment:
|
||||
- OTEL_SERVICE_NAME=minha-api
|
||||
- OTEL_EXPORTER_OTLP_ENDPOINT=http://ophion:8080
|
||||
- JAVA_TOOL_OPTIONS=-javaagent:/otel/java/opentelemetry-javaagent.jar
|
||||
volumes:
|
||||
- ophion-otel-agents:/otel:ro
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Dashboard
|
||||
|
||||
### 7.1 Páginas Disponíveis
|
||||
|
||||
| Página | Descrição |
|
||||
|--------|-----------|
|
||||
| **Dashboard** | Visão geral: agents, serviços, alertas |
|
||||
| **Traces** | Lista de traces com filtros |
|
||||
| **Logs** | Busca e visualização de logs |
|
||||
| **Metrics** | Gráficos de métricas |
|
||||
| **Services** | Mapa de dependências |
|
||||
| **Alerts** | Gerenciamento de alertas |
|
||||
| **Agents** | Lista de agents conectados |
|
||||
|
||||
### 7.2 Filtros de Traces
|
||||
|
||||
- **Service:** Filtrar por serviço
|
||||
- **Operation:** Filtrar por operação
|
||||
- **Duration:** Traces lentos (> X ms)
|
||||
- **Status:** OK ou Error
|
||||
|
||||
### 7.3 Visualização de Trace
|
||||
|
||||
Ao clicar em um trace, você vê:
|
||||
- Timeline com todos os spans
|
||||
- Duração de cada operação
|
||||
- Serviço responsável
|
||||
- Atributos e erros
|
||||
|
||||
---
|
||||
|
||||
## 8. API Reference
|
||||
|
||||
### Autenticação
|
||||
|
||||
**Login:**
|
||||
```bash
|
||||
POST /api/v1/auth/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"email": "admin@empresa.com",
|
||||
"password": "senha123"
|
||||
}
|
||||
```
|
||||
|
||||
**Resposta:**
|
||||
```json
|
||||
{
|
||||
"token": "eyJhbG...",
|
||||
"user": { "email": "...", "role": "admin" }
|
||||
}
|
||||
```
|
||||
|
||||
### Endpoints Principais
|
||||
|
||||
| Método | Endpoint | Descrição |
|
||||
|--------|----------|-----------|
|
||||
| GET | /health | Status do servidor |
|
||||
| POST | /api/v1/auth/login | Login |
|
||||
| POST | /api/v1/auth/register | Registro |
|
||||
| GET | /api/v1/metrics | Consultar métricas |
|
||||
| GET | /api/v1/traces | Listar traces |
|
||||
| GET | /api/v1/traces/:id | Detalhes do trace |
|
||||
| GET | /api/v1/logs | Buscar logs |
|
||||
| GET | /api/v1/agents | Listar agents |
|
||||
| GET | /api/v1/alerts | Listar alertas |
|
||||
|
||||
### Headers
|
||||
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Segurança
|
||||
|
||||
### 9.1 Autenticação
|
||||
|
||||
- **JWT Token** — Expira em 24 horas
|
||||
- **API Keys** — Para integrações
|
||||
- **AGENT_KEY** — Para agents
|
||||
|
||||
### 9.2 Variáveis de Ambiente
|
||||
|
||||
| Variável | Descrição | Padrão |
|
||||
|----------|-----------|--------|
|
||||
| JWT_SECRET | Segredo para JWT | ophion-jwt-secret... |
|
||||
| AGENT_KEY | Chave dos agents | ophion-secret-agent... |
|
||||
| ADMIN_PASSWORD | Senha inicial admin | ophion123 |
|
||||
|
||||
### 9.3 Recomendações para Produção
|
||||
|
||||
1. **Altere todas as senhas padrão**
|
||||
2. **Use HTTPS** (coloque atrás de Nginx/Traefik)
|
||||
3. **Restrinja acesso por firewall**
|
||||
4. **Faça backup do PostgreSQL**
|
||||
|
||||
---
|
||||
|
||||
## 10. Troubleshooting
|
||||
|
||||
### Agent dá erro 401
|
||||
|
||||
```bash
|
||||
# Verifique se a AGENT_KEY está correta
|
||||
echo $AGENT_KEY
|
||||
|
||||
# Deve ser igual à configurada no servidor
|
||||
docker exec ophion env | grep AGENT_KEY
|
||||
```
|
||||
|
||||
### Traces não aparecem
|
||||
|
||||
1. Verifique se a app está instrumentada
|
||||
2. Faça uma requisição para a app
|
||||
3. Aguarde ~30 segundos
|
||||
4. Verifique os logs do container
|
||||
|
||||
```bash
|
||||
docker logs ophion 2>&1 | grep -i trace
|
||||
```
|
||||
|
||||
### Dashboard não abre
|
||||
|
||||
```bash
|
||||
# Verifique se os containers estão rodando
|
||||
docker compose ps
|
||||
|
||||
# Verifique os logs
|
||||
docker compose logs ophion
|
||||
|
||||
# Reinicie
|
||||
docker compose restart ophion
|
||||
```
|
||||
|
||||
### Erro de conexão com banco
|
||||
|
||||
```bash
|
||||
# Verifique se PostgreSQL está rodando
|
||||
docker compose ps postgres
|
||||
|
||||
# Verifique a DATABASE_URL
|
||||
docker exec ophion env | grep DATABASE
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📞 Suporte
|
||||
|
||||
- **Website:** [ophion.com.br](https://ophion.com.br)
|
||||
- **Email:** suporte@ophion.com.br
|
||||
- **Documentação:** [docs.ophion.com.br](https://docs.ophion.com.br)
|
||||
|
||||
---
|
||||
|
||||
<p align="center">
|
||||
<strong>Made with 🖤 in Brazil</strong><br>
|
||||
<em>OPHION © 2026 - Open Source Observability Platform</em>
|
||||
</p>
|
||||
Reference in New Issue
Block a user