Observabilidade no RUB

A observabilidade é a capacidade de entender o estado interno de um sistema complexo apenas observando seus outputs externos. No ecossistema do RUB, isso é alcançado através de três pilares principais:Métricas,Logse**Traces **.

1. O que é Observabilidade?

Diferente do monitoramento tradicional (que foca em responder de forma binária se "o sistema está de pé?" ou "o sistema caiu?"), a observabilidade é uma propriedade profunda do sistema que foca em entender os motivos internos: "por que isso está acontecendo agora?".

Em ambientes complexos e distribuídos como o RUB, onde múltiplos plugins, conexões de banco de dados e processos em segundo plano coexistem, não basta saber que houve um erro. É necessário ter os instrumentos para dissecar a anatomia de uma falha em tempo real. A observabilidade permite que a equipe de engenharia e suporte saia de um estado reativo de " apagar incêndios" para uma postura proativa e analítica, garantindo a resiliência e a alta disponibilidade da plataforma.

Os três pilares fundamentais da observabilidade moderna, implementados nativamente no RUB, são:

-Métricas: Dados numéricos agregados ao longo do tempo (séries temporais). Elas servem para identificar tendências, padrões de uso e anomalias de performance antes que se tornem incidentes graves. Exemplos incluem uso de CPU, ocupação de memória e latência de queries. -Logs: Registros de eventos discretos, textuais e detalhados. São a "caixa preta" do sistema. No RUB, os logs são estruturados e enriquecidos com IDs de contexto, permitindo uma investigação granular sobre o comportamento de uma transação específica. -Traces (Rastreamento): O mapeamento do caminho percorrido por uma requisição através de todos os componentes do sistema. No RUB, isso é feito através do EXEC_ID, que conecta os pontos entre diferentes threads e plugins, fornecendo uma visão holística e temporal do fluxo de dados.

A união desses três pilares cria um ecossistema onde o dado flui de forma correlacionada, permitindo que o operador identifique uma anomalia em uma métrica, investigue a causa raiz nos logs e visualize o impacto total através dos traces.

2. Coleta de Métricas e Debug Humano

A coleta de dados no RUB é projetada para atender a dois perfis distintos de consumo: oanalista humano, que precisa de respostas imediatas durante uma crise ou investigação técnica, e osistema de monitoramento, que processa volumes massivos de dados para gerar alertas, dashboards de longo prazo e análises de tendência.

O RUB expõe métricas de performance e saúde do sistema de forma transparente, garantindo que o estado da aplicação nunca seja uma incógnita.

2.1 Painel de Debug (Uso por Humano)

Para visualização rápida e troubleshooting manual (debug por humano), o RUB oferece um painel interativo que consolida o estado interno da aplicação em tempo real.

-URL: /debug (ou conforme configurado no servidor de aplicação). -Principais Visões: -Gráfico de Memória: Visualização do uso de memória Heap nos últimos 120 minutos, permitindo identificar vazamentos ou picos de consumo. -Threads e Stacktraces: Lista detalhada de todas as threads ativas. Ao clicar em uma thread, é possível ver seu stacktracecompleto, fundamental para identificar deadlocks ou threads presas. -Pool de Conexões: Status de cada conexão com o banco de dados (ID, tempo de uso, última query executada). -Backpool: Monitoramento de conexões criadas fora do pool principal. -Plugins: Lista de todos os módulos carregados, suas versões e estado atual. -Garbage Collector: Estatísticas de execução do GC. -Ferramentas: Auto Refresh (atualização automática) e botão para download do HTML para análise offline (Snapshot).

2.2 Coleta Automática (Prometheus)

-**URL Base**: `/debug/metrics/any` (Consolida todas as métricas abaixo)

-Endpoints Específicos: - /debug/metrics/infra: Saúde da JVM e hardware. - /debug/metrics/log: Saúde do sistema de escrita de logs. - /debug/metrics/connections: Saúde do acesso ao banco de dados (Pool e Backpool). - /debug/metrics/contexts: Quantidade e tipos de contextos ativos. - /debug/metrics/version: Versão do Core e dos Plugins.

3. Configuração do Prometheus

Para configurar a coleta automática, adicione o RUB como um job no arquivo prometheus.yml.

3.1 Autenticação

O endpoint /debug exigeBasic Authentication(exceto para requisições originadas em localhost). Utilize as credenciais de um usuário que possua a permissão**"Visualizar Métricas de Debug"**(ROLE_GET_DEBUG).

3.2 Exemplo de prometheus.yml

scrape_configs:
  - job_name: 'rub-app'
    metrics_path: '/debug/metrics/any'
    static_configs:
      - targets: [ '192.168.1.10:80' ]
    basic_auth:
      username: 'seu_usuario'
      password: 'seu_token_ou_senha'

3.3 Coleta de Métricas de Infraestrutura (CPU, Memória, Disco)

As métricas de infraestrutura são extraídas diretamente dos MXBeans da JVM e do Sistema Operacional pelo RUB, eliminando a necessidade de instaladores externos (como Node Exporter) para métricas básicas.

-CPU: Coletada via OperatingSystemMXBean, fornece o uso tanto do processo Java quanto do sistema global. -Memória: Fornece detalhes de Heap e Non-Heap (Metaspace, Code Cache). -Disco: Monitora o espaço total e livre nos diretórios cruciais: raiz (.), logs (log/) e armazenamento ( storage/).

4. Catálogo de Métricas

Abaixo estão listadas as principais métricas expostas pelo RUB via DebugServlet.

4.1 Infraestrutura e JVM (/metrics/infra)

4.2 Logs (/metrics/log)

Monitora se há gargalos na gravação de logs em disco.

4.3 Banco de Dados (/metrics/connections)

4.4 Contextos e Plugins (/metrics/contexts e /metrics/version)

5. Logs e Rastreamento (Traces)

5.1 Uso do Trace no RUB (EXEC_ID)

O RUB utiliza o conceito deDistributed Tracingde forma nativa através doEXEC_ID. Conforme detalhado na Documentação de Logs, cada operação recebe um UUID único.

-Propagação: O EXEC_ID é propagado por todas as camadas do sistema durante uma mesma execução (MDC - Mapped Diagnostic Context). -Correlação: Ao encontrar um erro em qualquer categoria de log (_main.log, _data.log, etc), o desenvolvedor pode usar o UUID para reconstruir o fluxo completo da requisição. -Loki + Trace: Quando os logs são enviados aoGrafana Loki, o EXEC_ID torna-se a chave de busca para correlacionar logs de diferentes threads que trabalharam na mesma tarefa.

5.2 Integração com Grafana Tempo

Para uma visão de traces distribuídos (OpenTelemetry), o RUB pode exportar spans para oGrafana Tempo. Isso permite visualizar graficamente o tempo gasto em cada plugin ou chamada de banco de dados, correlacionando o ID do trace com os logs do Loki de forma automática.

6. Stack de Observabilidade Recomendada

Para um ambiente de produção resiliente, a stack recomendada é aLGTM(Loki, Grafana, Tempo, Prometheus).

graph TD
    subgraph "Aplicação RUB"
        R[RUB Instance]
        D[DebugServlet /metrics]
        L[LogWriter /stdout]
    end

    subgraph "Coleta e Armazenamento"
        PROM[Prometheus]
        LOKI[Grafana Loki]
        TEMPO[Grafana Tempo]
    end

    subgraph "Visualização"
        GF[Grafana Dashboards]
    end

    %% Fluxo de Métricas
    D -- "Scrape (Métricas)" --> PROM
    
    %% Fluxo de Logs
    L -- "Promtail / Fluent-bit (Logs)" --> LOKI
    
    %% Fluxo de Traces
    R -- "OTLP (Traces)" --> TEMPO

    %% Correlação no Grafana
    GF -.-> PROM
    GF -.-> LOKI
    GF -.-> TEMPO
    
    LOKI -- "Correlation (EXEC_ID)" --> TEMPO
    PROM -- "Exemplars" --> TEMPO

    style GF fill:#f96,stroke:#333,stroke-width:4px
    style PROM fill:#e67e22,stroke:#333,stroke-width:2px
    style LOKI fill:#27ae60,stroke:#333,stroke-width:2px
    style TEMPO fill:#8e44ad,stroke:#333,stroke-width:2px

Destaques da Stack:

-Prometheus: Armazena as séries temporais das métricas listadas no Catálogo. -Loki: Indexa os logs estruturados do RUB, permitindo buscas rápidas pelo EXEC_ID ou CONTEXT_ID. -Tempo: Armazena os traces detalhados para análise de latência. -Grafana: Atua como a "Single Source of Truth", onde o operador correlaciona métricas de CPU com picos de logs de erro e rastreia o culpado via Trace.

7. Instalação da Stack de Infraestrutura

A instalação da stack de observabilidade deve seguir os padrões de governança e infraestrutura detalhados no Guia de Deploy. Abaixo, fornecemos um exemplo de referência utilizando Docker Compose para subir uma stack básica de métricas.

7.1 Exemplo: Docker Compose (Prometheus + Grafana)

Este exemplo configura o Prometheus para coletar métricas do RUB e o Grafana para visualização.

version: '3.8'

services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"
    restart: always

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    restart: always

Certifique-se de que o arquivo prometheus.yml (conforme detalhado na seção3.2 Exemplo de prometheus.yml) esteja configurado corretamente para apontar para a instância do RUB.