Configure telemetry¶

Expose Stegflow's metrics to a Prometheus scraper, and push traces, metrics or logs to an OpenTelemetry collector.

Stegflow always collects its metrics and serves them on /metrics, but that endpoint is closed until you open it. Exporting over OTLP is opt-in, per signal.

Prerequisites¶

A running Stegflow instance.
A Prometheus server, an OTLP collector, or both.
A way to set environment variables on the container (see Configuration).

Steps¶

1. Open the metrics endpoint¶

With the defaults, /metrics answers 401 with a WWW-Authenticate: Bearer header. Grant access with a token, or by source network.

Bearer tokenAllowed networks

STEGFLOW_Metrics__BearerToken=<A_LONG_RANDOM_TOKEN>

The scraper sends it as Authorization: Bearer <token>. The comparison is constant-time.

prometheus.yml

scrape_configs:
  - job_name: stegflow
    authorization:
      credentials: <A_LONG_RANDOM_TOKEN>
    static_configs:
      - targets: ["stegflow:8080"]

STEGFLOW_Metrics__AllowedNetworks__0=10.0.0.0/8

Requests coming from those networks scrape without a token. Add more with __1, __2, and so on.

prometheus.yml

scrape_configs:
  - job_name: stegflow
    static_configs:
      - targets: ["stegflow:8080"]

The endpoint exposes the engine's own meters and the authorization decision cache meters.

AllowAnonymous drops every check

STEGFLOW_Metrics__AllowAnonymous=true serves /metrics with no token and no source check. Use it only on a network you already isolate, since the metrics reveal tenant and execution activity.

2. Export traces to a collector¶

Tracing has no pull equivalent, so it is captured only when you opt in. Set the collector endpoint and switch traces on:

STEGFLOW_OpenTelemetry__OTLP__Endpoint=http://collector:4317
STEGFLOW_OpenTelemetry__OTLP__Traces=true

You then get spans for incoming and outgoing HTTP, Entity Framework Core queries, and the engine's own operations.

3. Add metrics and logs, if you want them¶

The same endpoint serves the other two signals, each with its own switch:

STEGFLOW_OpenTelemetry__OTLP__Metrics=true
STEGFLOW_OpenTelemetry__OTLP__Logs=true

Pushing metrics over OTLP does not replace /metrics; both stay available.

Two settings help when the collector is not a plain local gRPC endpoint:

STEGFLOW_OpenTelemetry__OTLP__Protocol=HttpProtobuf
STEGFLOW_OpenTelemetry__OTLP__Headers__Authorization=Bearer <TOKEN>

Set STEGFLOW_OpenTelemetry__ServiceName to tell several instances apart in the collector.

Already using the standard OTEL_ variables?

Leave the endpoint, protocol and headers unset and the exporter falls back to the SDK defaults, which read OTEL_EXPORTER_OTLP_*. Convenient when a sidecar or platform injects them. You still have to switch the signals on with the settings above.

Result¶

Prometheus scrapes Stegflow, and the signals you enabled reach your collector. For every telemetry setting and its default, see Configuration.