bigtux/ophion

Fork 0

Files

bigtux a1ca397c43 docs: add complete OPHION manual with logo

2026-02-06 22:27:27 -03:00

9.8 KiB

Raw Blame History

🐍 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

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

docker --version
docker compose version

3. Instalação

3.1 Clone o repositório

git clone https://github.com/bigtux/ophion.git
cd ophion

3.2 Inicie a stack

docker compose up -d --build

3.3 Verifique os containers

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

curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@suaempresa.com",
    "password": "SenhaForte123!"
  }'

Resposta:

{
  "message": "User registered successfully",
  "token": "eyJhbG...",
  "user": {
    "email": "admin@suaempresa.com",
    "role": "admin"
  }
}

4.2 Acessar o Dashboard

Abra http://seu-servidor:3000/login
Digite o email e senha cadastrados
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

# 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

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)

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

./instrument.sh <container> <linguagem> <ophion_server>

Linguagens suportadas: dotnet, nodejs, python, java, go, php

6.2 Exemplos por Linguagem

.NET

./instrument.sh minha-api-dotnet dotnet http://10.0.0.5:8080

Ou manualmente no docker-compose:

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

./instrument.sh minha-api-node nodejs http://10.0.0.5:8080

Ou no código:

// Adicione no início do app (antes de tudo)
require('@opentelemetry/auto-instrumentations-node/register');

npm install @opentelemetry/auto-instrumentations-node

OTEL_SERVICE_NAME=minha-api \
OTEL_EXPORTER_OTLP_ENDPOINT=http://ophion:8080 \
node app.js

Python

./instrument.sh minha-api-python python http://10.0.0.5:8080

Ou manualmente:

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

./instrument.sh minha-api-java java http://10.0.0.5:8080

Ou no docker-compose:

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:

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "admin@empresa.com",
  "password": "senha123"
}

Resposta:

{
  "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

Altere todas as senhas padrão
Use HTTPS (coloque atrás de Nginx/Traefik)
Restrinja acesso por firewall
Faça backup do PostgreSQL

10. Troubleshooting

Agent dá erro 401

# 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

Verifique se a app está instrumentada
Faça uma requisição para a app
Aguarde ~30 segundos
Verifique os logs do container

docker logs ophion 2>&1 | grep -i trace

Dashboard não abre

# 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

# Verifique se PostgreSQL está rodando
docker compose ps postgres

# Verifique a DATABASE_URL
docker exec ophion env | grep DATABASE

📞 Suporte

Website: ophion.com.br
Email: suporte@ophion.com.br
Documentação: docs.ophion.com.br

9.8 KiB Raw Blame History