OpenTelemetry

An OpenTelemetry collector receives telemetry from many systems and forwards it to the monitoring backend in use. Where Prometheus pulls metrics from the server, OpenTelemetry works the other way round: Stalwart pushes its metrics to an OpenTelemetry collector at a fixed interval. This suits deployments that already route their telemetry through a collector.

The metrics are sent as OTLP data with cumulative temporality. Each export therefore contains the totals of each counter and histogram since the process started, not the change since the last export, and these totals reset when the server restarts.

Configuration

The exporter is configured in the openTelemetry field of the Metrics object (found in the WebUI under Settings › Telemetry › Metrics › General, Settings › Telemetry › Metrics › OpenTelemetry, Settings › Telemetry › Metrics › Prometheus). Its @type selects the transport: Disabled, Http or Grpc. Until Http or Grpc is chosen, no metrics are pushed.

Both transports have the following fields:

• url is the address of the collector. With Http, it is required and used as given, so it typically ends in /v1/metrics. With Grpc, it has no path, such as http://otel.example.com:4317. When it is empty, the standard OTEL_EXPORTER_OTLP_ENDPOINT environment variables apply, and http://localhost:4317 if none is set.
• interval is the time between two exports, 1 minute by default.
• timeout limits each export.

The transports differ in authentication. The Http variant also has httpAuth (Unauthenticated, Basic or Bearer), httpHeaders and allowInvalidCerts. The Grpc variant sends no authentication, so the collector must accept unauthenticated connections.

Cluster and failures

Metrics are pushed only by nodes whose cluster role includes the metricsPush task, or by every node when no roles are configured. Each node sends its own metrics. Export failures are reported as telemetry.otel-metrics-exporter-error events.

Examples

The following value pushes metrics every 30 seconds to a collector over HTTP, with a bearer token:

{
  "openTelemetry": {
    "@type": "Http",
    "url": "https://otel.example.com:4318/v1/metrics",
    "interval": 30000,
    "httpAuth": {
      "@type": "Bearer",
      "bearerToken": {"@type": "EnvironmentVariable", "variableName": "OTEL_TOKEN"}
    }
  }
}

The following value pushes metrics to a collector on the same host over gRPC:

{
  "openTelemetry": {
    "@type": "Grpc",
    "url": "http://127.0.0.1:4317"
  }
}