docs: add complete OPHION manual with logo
This commit is contained in:
5
.env
Normal file
5
.env
Normal file
@@ -0,0 +1,5 @@
|
|||||||
|
# OPHION Local Development
|
||||||
|
AGENT_KEY=ophion-secret-agent-key-2024
|
||||||
|
JWT_SECRET=ophion-jwt-secret-change-in-production
|
||||||
|
ADMIN_PASSWORD=ophion123
|
||||||
|
TZ=America/Sao_Paulo
|
||||||
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