Dashboards e alertas

O repositório do SDK mantém, no diretório observability/, dashboards do Grafana e regras de alerta do Prometheus para as métricas emitidas pelo SDK. Eles são versionados junto com o código que emite as métricas, e o CI do SDK falha quando alguma consulta usa uma métrica que não existe no catálogo.

observability/
  dashboards/
    http.json        servidor e cliente REST
    messaging.json   produtores, consumidores e atraso de consumo
    database.json    SQL (sqlDB), Redis (cacheDB) e storage
    runtime.json     runtime Go, GC e processo
  alerts/
    rules.yaml       regras de alerta do Prometheus
    rules_test.yaml  testes das regras com promtool

Pré-requisitos

• métricas habilitadas e expostas em /metrics, o comportamento padrão — consulte Observabilidade;
• um backend compatível com Prometheus coletando /metrics, como Prometheus, Grafana Mimir, VictoriaMetrics, Amazon Managed Prometheus ou Grafana Cloud.

Os dashboards e as regras consultam os nomes expostos em /metrics, não os nomes OpenTelemetry. Um backend que recebe as métricas pelo exportador OTLP pode nomear as séries de outra forma e não é coberto.

Todos os dashboards filtram pelos labels job e instance da coleta. As listas de seleção desses labels são preenchidas a partir de target_info, que o SDK expõe em todo serviço.

Importar os dashboards

Pela interface do Grafana

1. Acesse Dashboards → New → Import e envie um dos arquivos JSON de dashboards/.
2. Salve o dashboard. Ele não fixa um datasource: usa o datasource Prometheus padrão da instância até que outro seja escolhido.

Por provisionamento

Aponte um provider de dashboards para uma cópia de dashboards/:

# /etc/grafana/provisioning/dashboards/colibri.yaml
apiVersion: 1
providers:
  - name: colibri-sdk-go
    folder: Colibri
    type: file
    options:
      path: /var/lib/grafana/dashboards/colibri

Escolher o datasource

Cada dashboard tem a lista Datasource, uma variável do tipo datasource restrita a Prometheus, e todos os painéis consultam ${datasource}:

• na interface, escolha o datasource na lista e salve o dashboard para mantê-lo como padrão;
• no provisionamento, torne o datasource correto o padrão (isDefault: true) ou altere templating.list[0].current no JSON, por exemplo "current": {"text": "Mimir", "value": "mimir-uid"}.

Carregar as regras de alerta

alerts/rules.yaml é um arquivo de regras comum do Prometheus. Adicione-o em rule_files no prometheus.yml:

rule_files:
  - /etc/prometheus/rules/rules.yaml

Com o Prometheus Operator, envolva os groups em um recurso PrometheusRule. Para Grafana Alerting ou Mimir, importe com mimirtool rules load ou cortextool rules load.

Alerta	Dispara quando	Severidade
ColibriHTTPHighErrorRate	mais de 5% das requisições respondem 5xx por 5 minutos	critical
ColibriHTTPHighLatency	o p99 da duração das requisições passa de 1 s por 10 minutos	warning
ColibriHTTPPanicRecovered	o servidor REST recuperou um panic	warning
ColibriMessagingPublishFailures	mais de 1% das publicações em um tópico falham por 5 minutos	critical
ColibriMessagingConsumerBacklog	o p99 do atraso de consumo de uma fila passa de 60 s por 10 minutos	warning
ColibriMessagingConsumerPanics	um consumer gerou panic ao processar uma mensagem	warning
ColibriSQLPoolSaturated	queries esperam por conexão com mais de 90% do pool em uso	warning
ColibriGoMemoryNearLimit	o runtime Go usa mais de 90% do GOMEMLIMIT por 10 minutos	warning
ColibriGoGCPressure	mais de 5% do tempo é gasto em pausas de GC por 10 minutos	warning

dica

Os limites são pontos de partida. Copie o arquivo e ajuste-os por serviço em vez de editá-lo no lugar, para que atualizações do SDK não sobrescrevam suas mudanças.

O alerta de backlog usa messaging.consume.lag, o tempo que a mensagem esperou no broker. A profundidade da fila é reportada pelo próprio broker — CloudWatch para SQS, Cloud Monitoring para Pub/Sub e o plugin Prometheus do RabbitMQ — e não é coberta por essas regras.

Testar localmente

O ambiente de desenvolvimento do SDK executa Prometheus e Grafana com os dashboards e as regras de observability/ montados, então alterações aparecem sem importação:

git clone https://github.com/colibriproject-dev/colibri-sdk-go.git
cd colibri-sdk-go/development-environment
make observability

make observability sobe apenas Prometheus e Grafana; make start também sobe os emuladores.

Serviço	Endereço
Grafana	http://localhost:3030, com acesso anônimo de administrador e dashboards na pasta Colibri
Prometheus	http://localhost:9091, com os alertas em Alerts

O Prometheus coleta host.docker.internal:8080 e host.docker.internal:8081, onde rodam o school-module e o finantial-module do repositório de exemplos. Para usar seu serviço, altere os targets em development-environment/prometheus/prometheus.yml e recarregue a configuração:

curl -X POST localhost:9091/-/reload