nemoguardrails.server.metrics
Opt-in metrics export for the Guardrails servers.
The IORails engine records its metrics through the OpenTelemetry API only;
something has to install an SDK MeterProvider or every emission is a
silent no-op. For library users that “something” is their application. For
the packaged nemoguardrails server and nemoguardrails hooks-server
commands it is this module: it builds a
MeterProvider backed by a PrometheusMetricReader, serves the scrape
endpoint on a dedicated port, and stops the listener with the server.
Scope is deliberately narrow. Only the non-streaming admission-queue metrics
are exported (see EXPORTED_INSTRUMENT_PATTERNS); everything else the
engine records is dropped by an SDK view so the scrape output stays small and
stable while the GenAI semantic conventions are still evolving.
Lifecycle: the OpenTelemetry API allows exactly one global MeterProvider
per process and never lets it be replaced, so the provider is installed once
and kept for the life of the process (the SDK shuts it down at interpreter
exit). start/shutdown only manage the HTTP listener, which is what
lets an embedded application or a test client cycle the server lifespan
repeatedly without losing metrics export. The listener is process-wide too,
so each lifespan holds it through running_metrics_exporter: the
listener stops when the last lifespan holding it exits, if a lifespan started
it. One started directly with start_metrics_exporter, as the CLIs do,
is left for its starter to stop.
All OpenTelemetry SDK and Prometheus imports are deferred into
_require_otel_sdk and the functions that use them, so importing this
module never requires the optional dependencies; they are pulled in by the
server extra.
Module Contents
Classes
Functions
Data
API
Bases: enum.Enum
Supported values for NEMO_GUARDRAILS_SERVER_METRICS_EXPORTER.
Bases: ValueError
The metrics exporter cannot start with the current configuration.
Raised for invalid settings, missing optional dependencies, a port that
cannot be bound, and a global MeterProvider that some other code
already installed. Callers turn it into a startup failure with the
message shown to the operator verbatim.
Resolved exporter settings; from_env is the only reader of the env vars.
Whether an exporter is configured at all.
Resolve settings from environment variables, raising MetricsExporterConfigError on invalid values.
A running Prometheus scrape endpoint serving the installed provider’s registry.
Create it through start_metrics_exporter; the constructor binds
the listener so a half-built exporter is never handed out. Only the HTTP
listener belongs to this object: the MeterProvider behind it is
process-wide (see _install_meter_provider). The object also
counts the running_metrics_exporter blocks holding the listener,
so the last of them can stop it.
The bound port; differs from the requested one only when port 0 was asked for.
Scrape URL of the running listener, as a client would dial it.
Count a running_metrics_exporter block in, noting whether it started this listener.
Count a block out; true when it was the last holder and a holder started this listener.
Stop the listener and join its thread. The provider keeps collecting
so a later start_metrics_exporter resumes export seamlessly.
The process-wide MeterProvider this module installed, plus the
registry its Prometheus reader writes into.
Render a listen address as the host a scraper would dial.
A wildcard bind is not an address a client can connect to, so it is shown
as localhost; an IPv6 literal is bracketed so the result is a valid URL.
Start or reuse the exporter and count a holder on it; None, uncounted, when export is off and none runs.
Install the global MeterProvider on first use and return it thereafter.
The OpenTelemetry API refuses to replace a provider once set, so this is
a one-way door per process: the first exporter start decides the
service.name resource and the export view, and later starts reuse
them. The SDK registers its own atexit hook to shut the provider
down, so nothing here needs to.
True when something other than the API’s own placeholder is installed.
Before set_meter_provider runs, the API hands out its no-op or proxy
provider, both defined inside the opentelemetry.metrics package. Any
real provider comes from an SDK package, so the defining module is the
stable way to tell the two apart without importing private names.
Count a holder out, and stop the exporter if it was the last, a holder started it, and it still runs.
Raise MetricsExporterConfigError unless every optional symbol is importable.
Callers import the symbols they need right after this check, so the module never holds the optional imports at import time and the error the operator sees names the missing distribution and how to install it.
Warn that the running exporter is served in place of the one settings ask for, when they differ.
Build a MeterProvider that exports the scoped metrics into registry.
Return the SDK views that restrict export to EXPORTED_INSTRUMENT_PATTERNS.
The SDK applies only the matching views to an instrument and falls back to its default aggregation when none match, so a catch-all drop view must be paired with an explicit keep view for every exported pattern.
Return the running exporter, or None when none is active.
Yield the running exporter, starting one if none runs; the last holder to exit stops one a holder started.
Stop the running exporter’s listener, if any. Safe to call repeatedly.
Start the configured exporter and return it.
Returns None when no exporter is configured. Repeated calls while an
exporter is running return it unchanged, which lets both the CLI entry
point and the FastAPI lifespan call it without coordinating: whichever
runs first wins, and the provider is in place before the first
IORails instance is built. After shutdown_metrics_exporter
the next call starts a fresh listener against the same provider.