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