Observabilidade

colibri.InitializeApp() inicializa o OpenTelemetry com dois sinais independentes:

• métricas, habilitadas por padrão e expostas em GET /metrics no formato do Prometheus, sem coletor e sem configuração;
• traces, habilitados somente quando há um coletor OTLP configurado.

Um sinal desligado recebe um provider noop: o código instrumentado continua válido e apenas não reporta nada.

Configurar os sinais

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_SERVICE_NAME=school-module

Informe a URL base, sem /v1/traces ou /v1/metrics; o SDK adiciona os caminhos dos sinais.

Variável	Padrão	Uso
OTEL_EXPORTER_OTLP_ENDPOINT	vazio	Endpoint OTLP HTTP. Habilita os traces e o exportador OTLP de métricas.
OTEL_EXPORTER_OTLP_HEADERS	vazio	Cabeçalhos chave=valor separados por vírgula.
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	endpoint principal	Endpoint alternativo apenas para métricas. Sozinho, habilita só o exportador OTLP de métricas.
OTEL_SERVICE_NAME	APP_NAME	Nome do serviço reportado no recurso OpenTelemetry.
OTEL_TRACES_ENABLED	true	Desliga os traces. Com true, os traces ainda exigem o endpoint do coletor.
OTEL_METRICS_ENABLED	true	Desliga as métricas nos dois readers, /metrics e OTLP.
OTEL_METRICS_PROMETHEUS_ENABLED	true	Expõe as métricas em /metrics pelo registry padrão do Prometheus.

Combinações

Configuração	Traces	/metrics	Métricas OTLP
Nada configurado (padrão)	desligado	ligado	desligado
OTEL_EXPORTER_OTLP_ENDPOINT configurado	ligado	ligado	ligado
Endpoint configurado e OTEL_METRICS_PROMETHEUS_ENABLED=false	ligado	desligado	ligado
Endpoint configurado e OTEL_TRACES_ENABLED=false	desligado	ligado	ligado
OTEL_METRICS_ENABLED=false e sem endpoint	desligado	desligado	desligado

Mudança de comportamento

Até a v0.2.5, sem OTEL_EXPORTER_OTLP_ENDPOINT nenhum sinal era habilitado, e /metrics servia apenas as métricas de Go e de processo do cliente Prometheus. A partir da v0.2.6, as métricas do SDK e da aplicação aparecem em /metrics por padrão. Para não expô-las, defina OTEL_METRICS_PROMETHEUS_ENABLED=false; para desligar as métricas por completo, inclusive na exportação OTLP, defina OTEL_METRICS_ENABLED=false.

Instrumentação automática

Com os traces habilitados, o SDK cria spans para:

• requisições do servidor Fiber;
• chamadas do cliente HTTP;
• operações PostgreSQL e Redis;
• produção e consumo de mensagens;
• operações de storage.

Com as métricas habilitadas, o SDK registra:

• requisições do servidor HTTP (http.server.request.duration e relacionadas) e panics recuperados;
• chamadas do cliente HTTP (http.client.request.duration), via otelhttp;
• chamadas SQL e o pool de conexões PostgreSQL (db.sql.*), via otelsql;
• o pool de conexões Redis (db.client.connections.*), via redisotel;
• mensagens publicadas, consumidas, rejeitadas, em processamento e o atraso de consumo (messaging.*);
• operações e volume transferido no storage (storage.*);
• memória, GC e goroutines do runtime Go (go.*).

A lista completa, com unidades e atributos, está no catálogo de métricas.

Criar um trace manual

import (
	"github.com/colibriproject-dev/colibri-sdk-go/pkg/base/monitoring"
	monitoringbase "github.com/colibriproject-dev/colibri-sdk-go/pkg/base/monitoring/colibri-monitoring-base"
)

transaction, traceCtx := monitoring.StartTransaction(
	ctx,
	"ProcessOrder",
	monitoringbase.SpanKindInternal,
)
defer monitoring.EndTransaction(transaction)

segment := monitoring.StartTransactionSegment(
	traceCtx,
	"LoadCustomer",
	map[string]string{"customer.type": "business"},
)
defer monitoring.EndTransactionSegment(segment)

Use o contexto retornado por StartTransaction para relacionar segmentos e operações instrumentadas.

Registrar erro

if err != nil {
	monitoring.NoticeError(transaction, err)
	return err
}

Métricas da aplicação

Contadores, histogramas e gauges da aplicação usam a mesma API das métricas do SDK:

orders := monitoring.Counter("orders.processed", "Processed orders", "{order}")
orders.AddAttrs(ctx, 1, monitoringbase.NewAttrs("channel", "web"))

Crie os instrumentos depois de colibri.InitializeApp() e reutilize os atributos. Convenções de nome, unidades, cardinalidade, gauges observáveis e testes estão em Métricas.

Funções obsoletas

monitoring.UseOTELMonitoring() está obsoleta: traces e métricas agora são independentes. Use a função que corresponde ao que o código instrumenta:

Função	Retorna true quando
monitoring.UseTracing()	os traces estão habilitados
monitoring.UseMetrics()	as métricas estão habilitadas em algum reader
monitoring.UseOTLPMetrics()	as métricas são exportadas por OTLP
monitoring.UsePrometheusMetrics()	as métricas são expostas em /metrics

Para dashboards do Grafana e regras de alerta prontas, consulte Dashboards e alertas. Para um ambiente local completo, consulte Monitoramento com Colibri e OpenTelemetry.