🐍 OPHION
Open Source Observability Platform — AI-Powered
Métricas • Traces • Logs • Alertas
Monitoramento completo para suas aplicações
---
# 📖 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
```
**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
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)
---
Made with 🖤 in Brazil
OPHION © 2026 - Open Source Observability Platform