WSGITelemetryService

Description:

Enable the in-process telemetry reporter and point it at an external ingester.

Syntax:

WSGITelemetryService unix:/path [interval=SECONDS]

Default:

Not set (reporter disabled)

Context:

server config

Enables the mod_wsgi telemetry reporter and configures the local UNIX socket the reporter sends its binary datagrams to. When set, every mod_wsgi process started by Apache (each daemon-mode worker and each embedded-mode Apache child) starts a single dedicated reporter thread at process initialisation. The thread emits three kinds of record over the configured socket:

  • An aggregate per-interval sample on every tick, covering the request throughput, per-phase latency distribution (mean / min / max / histogram), capacity utilisation, in-flight worker-slot state, HTTP response-class counts, CPU consumption, and resident memory of the process for the interval that just closed.

  • Process lifecycle events (start, draining, stop) emitted as state changes happen.

  • Per-request slow records when WSGISlowRequests is also configured: a record when an in-flight request crosses the configured elapsed-time threshold, and a follow-up when the same request later completes carrying the final elapsed time and HTTP status.

See The External Telemetry Service for the full enumeration of fields in each record kind.

This is a server-wide directive: it may only appear at the top level of the Apache configuration, outside any <VirtualHost> block. Apache rejects the configuration at startup if the directive appears in a per-vhost or per-directory context. One configuration line enables the reporter for the entire Apache instance, covering every daemon process group and every embedded-mode Apache child.

Note that the telemetry reporter, and so the WSGITelemetryService, WSGISlowRequests and WSGITelemetryOptions directives, are not available on Windows. The reporter delivers its datagrams over a UNIX SOCK_DGRAM socket, which Windows does not provide, so the feature is not built there and these directives are not registered. Using one of them on Windows is reported by Apache as an unknown directive.

Arguments

unix:/path/to/socket

Path of the listening UNIX SOCK_DGRAM socket on the same host. Only the unix: scheme is accepted; udp:host:port targets are rejected at configuration-parse time, since the reporter is intended for a co-located ingester and no provision is made for cross-host transport.

The ingester that creates the socket is distributed separately as the mod_wsgi-telemetry package on PyPi. See The External Telemetry Service for installing and running it.

interval=SECONDS

Optional. Sampling interval in seconds for the reporter loop. Defaults to 1.0. Sub-second intervals down to 0.5 are permitted; smaller intervals produce more datagrams and finer resolution at a higher per-tick cost. Values below 0.5 are rejected at configuration-parse time, since a faster cadence has the reporter consuming meaningful CPU on its own bookkeeping without producing visibly better signal for diagnostic use.

Validation

  • WSGITelemetryService with no argument is rejected at configuration-parse time.

  • A target without the unix: prefix, including a remote udp:host:port form, is rejected with a clear error.

  • An interval= value below 0.5 (including zero or negative) is rejected.

  • A second argument other than interval=N is rejected.

Interaction with other surfaces

When WSGITelemetryService is set, the external reporter is the canonical metrics consumer for the process. The Python accessors mod_wsgi.request_metrics() and mod_wsgi.process_metrics() return None regardless of whether mod_wsgi.start_recording_metrics() has been called, so an in-application reporter detects the external configuration with a single None check and stands down. See The Internal Metrics API for the in-process accessor API and how an application-side reporter coexists with the external one.

The ingester socket is created by the ingester process at its own bind time, owned by the ingester user. The mod_wsgi processes that report (daemon-mode workers and Apache children) need write permission on the socket file to sendto() it; The External Telemetry Service covers the shared-group pattern for multi-user deployments.

See also