Observability

colibri.InitializeApp() initializes OpenTelemetry with two independent signals:

• metrics, enabled by default and exposed on GET /metrics in the Prometheus format, with no collector and no configuration;
• traces, enabled only when an OTLP collector is configured.

A disabled signal gets a noop provider: instrumented code stays valid and simply reports nothing.

Configure the signals

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

Provide the base URL without /v1/traces or /v1/metrics; the SDK appends the signal paths.

Variable	Default	Usage
OTEL_EXPORTER_OTLP_ENDPOINT	empty	OTLP HTTP endpoint. Enables traces and the OTLP metric exporter.
OTEL_EXPORTER_OTLP_HEADERS	empty	Comma-separated key=value headers.
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	main endpoint	Alternative endpoint for metrics only. On its own, it enables only the OTLP metric exporter.
OTEL_SERVICE_NAME	APP_NAME	Service name reported in the OpenTelemetry resource.
OTEL_TRACES_ENABLED	true	Turns traces off. When true, traces still require the collector endpoint.
OTEL_METRICS_ENABLED	true	Turns metrics off in both readers, /metrics and OTLP.
OTEL_METRICS_PROMETHEUS_ENABLED	true	Exposes metrics on /metrics through the Prometheus default registry.

Combinations

Configuration	Traces	/metrics	OTLP metrics
Nothing configured (default)	off	on	off
OTEL_EXPORTER_OTLP_ENDPOINT set	on	on	on
Endpoint set and OTEL_METRICS_PROMETHEUS_ENABLED=false	on	off	on
Endpoint set and OTEL_TRACES_ENABLED=false	off	on	on
OTEL_METRICS_ENABLED=false and no endpoint	off	off	off

Behavior change

Up to v0.2.5, no signal was enabled without OTEL_EXPORTER_OTLP_ENDPOINT, and /metrics served only the Go and process metrics of the Prometheus client. From v0.2.6, SDK and application metrics appear on /metrics by default. To stop exposing them, set OTEL_METRICS_PROMETHEUS_ENABLED=false; to turn metrics off entirely, including the OTLP export, set OTEL_METRICS_ENABLED=false.

Automatic instrumentation

With traces enabled, the SDK creates spans for Fiber server requests, HTTP client calls, PostgreSQL and Redis operations, message production and consumption, and storage operations.

With metrics enabled, the SDK records:

• HTTP server requests (http.server.request.duration and related) and recovered panics;
• HTTP client calls (http.client.request.duration), through otelhttp;
• SQL calls and the PostgreSQL connection pool (db.sql.*), through otelsql;
• the Redis connection pool (db.client.connections.*), through redisotel;
• published, consumed, rejected, and in-flight messages, and the consume lag (messaging.*);
• storage operations and transferred bytes (storage.*);
• Go runtime memory, GC, and goroutines (go.*).

The full list, with units and attributes, is in the metric catalog.

Create a manual trace

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 the context returned by StartTransaction for segments and instrumented operations.

Record errors

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

Application metrics

Application counters, histograms, and gauges use the same API as the SDK metrics:

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

Create instruments after colibri.InitializeApp() and reuse attribute sets. Naming, units, cardinality, observable gauges, and testing are covered in Metrics.

Deprecated functions

monitoring.UseOTELMonitoring() is deprecated: traces and metrics are now independent. Use the function matching what the code instruments:

Function	Returns true when
monitoring.UseTracing()	traces are enabled
monitoring.UseMetrics()	metrics are enabled in any reader
monitoring.UseOTLPMetrics()	metrics are exported over OTLP
monitoring.UsePrometheusMetrics()	metrics are exposed on /metrics

For ready-made Grafana dashboards and alert rules, see Dashboards and alerts.