Documentação / Observabilidade com Grafana Externo (Ilumin)

Observabilidade com Grafana Externo (Ilumin)

Entrar

Observabilidade com Grafana Externo (Ilumin)

Este documento descreve como usar o Grafana ja existente (grafana.iaxp.cloud) com a stack de observabilidade publicada via docker-compose.observability.ilumin.yml.

Objetivo

  • Manter o Grafana centralizado e online na VPS.
  • Publicar apenas os backends de observabilidade (Alloy, Tempo, Loki, Prometheus) no Ilumin.
  • Conectar o Grafana externo aos servicos via HTTPS.

Arquitetura

  • Grafana (externo): https://grafana.iaxp.cloud
  • Alloy (coleta/roteamento OTLP): https://grafana-alloy.iaxp.cloud
  • Tempo (traces): https://grafana-tempo.iaxp.cloud
  • Loki (logs): https://grafana-loki.iaxp.cloud
  • Prometheus (metricas): https://grafana-prometheus.iaxp.cloud

Observacao: no Grafana, os datasources principais sao Tempo, Loki e Prometheus. O endpoint do Alloy e usado pelos apps instrumentados para enviar OTLP.

Compose utilizado

Arquivo: docker-compose.observability.ilumin.yml

Servicos

  • alloy (grafana/alloy:latest)
  • tempo (grafana/tempo:latest)
  • loki (grafana/loki:latest)
  • prometheus (prom/prometheus:latest)

Redes

  • traefik (external)
  • internal

Cada servico publico esta em traefik + internal, com labels Traefik e TLS (letsencrypt).

Volumes

  • tempo_data
  • loki_data
  • prometheus_data

Subindo a stack no Ilumin

  1. Use o conteudo de docker-compose.observability.ilumin.yml no app custom do Ilumin.
  2. Garanta que os DNS dos subdominios apontem para o servidor Ilumin.
  3. Aguarde provisionamento de certificado TLS.
  4. Valide os endpoints:
    • https://grafana-tempo.iaxp.cloud
    • https://grafana-loki.iaxp.cloud
    • https://grafana-prometheus.iaxp.cloud

Conectando no Grafana ja online

No Grafana (grafana.iaxp.cloud):

  1. Acesse Connections > Data sources.
  2. Adicione os datasources:
    • Prometheus: https://grafana-prometheus.iaxp.cloud
    • Loki: https://grafana-loki.iaxp.cloud
    • Tempo: https://grafana-tempo.iaxp.cloud
  3. Em cada datasource, clique em Save & test.

Ajustes recomendados no Grafana

Tempo -> Trace to logs

  • Logs datasource: Loki
  • Tags sugeridas: service.name, service.instance.id, trace_id

Tempo -> Trace to metrics

  • Metrics datasource: Prometheus
  • Tags sugeridas: service.name, service.instance.id

Loki -> Derived field para trace_id

Crie um derived field para abrir trace no Tempo.

  • Name: trace_id
  • Regex sugerida: trace[_-]?id[=:"]+([a-f0-9]{32})
  • Data source: Tempo

Configuracao das aplicacoes instrumentadas

Para enviar telemetria ao Alloy:

  • OTEL_EXPORTER_OTLP_ENDPOINT=https://grafana-alloy.iaxp.cloud
  • OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
  • OTEL_TRACES_SAMPLER=parentbased_traceidratio
  • OTEL_TRACES_SAMPLER_ARG=0.1 (ou valor desejado)
  • OTEL_LOGS_ENABLED=true (se quiser export de logs via OTLP)

Troubleshooting rapido

  • Datasource sem conexao: validar DNS, TLS e se o router Traefik do servico esta ativo.
  • Sem traces: confirmar OTEL_EXPORTER_OTLP_ENDPOINT apontando para Alloy.
  • Sem metricas: confirmar OTEL_NODE_EXPERIMENTAL_SDK_METRICS=true nos apps Node.
  • Sem logs no Loki: confirmar OTEL_LOGS_ENABLED=true e pipeline de logs no Alloy.