Skip to navigation

nemoguardrails.server.metrics

View as MarkdownOpen in Claude

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

NameDescription
MetricsExporterSupported values for NEMO_GUARDRAILS_SERVER_METRICS_EXPORTER.
MetricsExporterConfigErrorThe metrics exporter cannot start with the current configuration.
MetricsExporterSettingsResolved exporter settings; from_env is the only reader of the env vars.
PrometheusMetricsExporterA running Prometheus scrape endpoint serving the installed provider’s registry.
_InstalledProviderThe process-wide MeterProvider this module installed, plus the

Functions

NameDescription
_display_hostRender a listen address as the host a scraper would dial.
_hold_metrics_exporterStart or reuse the exporter and count a holder on it; None, uncounted, when export is off and none runs.
_install_meter_providerInstall the global MeterProvider on first use and return it thereafter.
_is_meter_provider_configuredTrue when something other than the API’s own placeholder is installed.
_release_metrics_exporterCount a holder out, and stop the exporter if it was the last, a holder started it, and it still runs.
_require_otel_sdkRaise MetricsExporterConfigError unless every optional symbol is importable.
_warn_if_another_exporter_is_runningWarn that the running exporter is served in place of the one settings ask for, when they differ.
build_meter_providerBuild a MeterProvider that exports the scoped metrics into registry.
build_viewsReturn the SDK views that restrict export to EXPORTED_INSTRUMENT_PATTERNS.
get_active_metrics_exporterReturn the running exporter, or None when none is active.
running_metrics_exporterYield the running exporter, starting one if none runs; the last holder to exit stops one a holder started.
shutdown_metrics_exporterStop the running exporter’s listener, if any. Safe to call repeatedly.
start_metrics_exporterStart the configured exporter and return it.

Data

DEFAULT_HOST

DEFAULT_PORT

DEFAULT_SERVICE_NAME

ENV_EXPORTER

ENV_HOST

ENV_PORT

ENV_SERVICE_NAME

EXPORTED_INSTRUMENT_PATTERNS

INSTALL_HINT

_WILDCARD_HOSTS

_active_exporter

_holders_lock

_installed_provider

log

API

class nemoguardrails.server.metrics.MetricsExporter

Bases: enum.Enum

Supported values for NEMO_GUARDRAILS_SERVER_METRICS_EXPORTER.

NONE
= 'none'
PROMETHEUS
= 'prometheus'
class nemoguardrails.server.metrics.MetricsExporterConfigError()

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.

exporter: nemoguardrails.server.metrics.MetricsExporter = MetricsExporter.NONE,
host: str = DEFAULT_HOST,
port: int = DEFAULT_PORT,
service_name: str = DEFAULT_SERVICE_NAME
)
Dataclass

Resolved exporter settings; from_env is the only reader of the env vars.

enabled
bool

Whether an exporter is configured at all.

exporter
MetricsExporter = MetricsExporter.NONE
host
str = DEFAULT_HOST
port
int = DEFAULT_PORT
service_name
str = DEFAULT_SERVICE_NAME
environ: typing.Optional[typing.Mapping[str, str]] = None,
classmethod

Resolve settings from environment variables, raising MetricsExporterConfigError on invalid values.

class nemoguardrails.server.metrics.PrometheusMetricsExporter(
)

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.

_holders
= 0
port
int

The bound port; differs from the requested one only when port 0 was asked for.

provider
= installed.provider
registry
= installed.registry
url
str

Scrape URL of the running listener, as a client would dial it.

nemoguardrails.server.metrics.PrometheusMetricsExporter.hold(
started_it: bool
) -> None

Count a running_metrics_exporter block in, noting whether it started this listener.

nemoguardrails.server.metrics.PrometheusMetricsExporter.release() -> bool

Count a block out; true when it was the last holder and a holder started this listener.

nemoguardrails.server.metrics.PrometheusMetricsExporter.shutdown() -> None

Stop the listener and join its thread. The provider keeps collecting so a later start_metrics_exporter resumes export seamlessly.

class nemoguardrails.server.metrics._InstalledProvider(
provider: opentelemetry.sdk.metrics.MeterProvider,
registry: prometheus_client.CollectorRegistry,
service_name: str
)
Dataclass

The process-wide MeterProvider this module installed, plus the registry its Prometheus reader writes into.

provider
MeterProvider
registry
CollectorRegistry
service_name
str
nemoguardrails.server.metrics._display_host(
host: str
) -> str

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.

nemoguardrails.server.metrics._hold_metrics_exporter(

Start or reuse the exporter and count a holder on it; None, uncounted, when export is off and none runs.

nemoguardrails.server.metrics._install_meter_provider(

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.

nemoguardrails.server.metrics._is_meter_provider_configured(
provider: object
) -> bool

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.

nemoguardrails.server.metrics._release_metrics_exporter(
) -> None

Count a holder out, and stop the exporter if it was the last, a holder started it, and it still runs.

nemoguardrails.server.metrics._require_otel_sdk() -> None

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.

nemoguardrails.server.metrics._warn_if_another_exporter_is_running(
) -> None

Warn that the running exporter is served in place of the one settings ask for, when they differ.

nemoguardrails.server.metrics.build_meter_provider(
registry: prometheus_client.CollectorRegistry
) -> opentelemetry.sdk.metrics.MeterProvider

Build a MeterProvider that exports the scoped metrics into registry.

nemoguardrails.server.metrics.build_views() -> typing.List[opentelemetry.sdk.metrics.view.View]

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.

nemoguardrails.server.metrics.get_active_metrics_exporter() -> typing.Optional[nemoguardrails.server.metrics.PrometheusMetricsExporter]

Return the running exporter, or None when none is active.

nemoguardrails.server.metrics.running_metrics_exporter(
) -> typing.Iterator[typing.Optional[nemoguardrails.server.metrics.PrometheusMetricsExporter]]

Yield the running exporter, starting one if none runs; the last holder to exit stops one a holder started.

nemoguardrails.server.metrics.shutdown_metrics_exporter() -> None

Stop the running exporter’s listener, if any. Safe to call repeatedly.

nemoguardrails.server.metrics.start_metrics_exporter(

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.

nemoguardrails.server.metrics.DEFAULT_HOST = '0.0.0.0'
nemoguardrails.server.metrics.DEFAULT_PORT = 9464
nemoguardrails.server.metrics.DEFAULT_SERVICE_NAME = 'nemoguardrails-server'
nemoguardrails.server.metrics.ENV_EXPORTER = 'NEMO_GUARDRAILS_SERVER_METRICS_EXPORTER'
nemoguardrails.server.metrics.ENV_HOST = 'NEMO_GUARDRAILS_SERVER_METRICS_HOST'
nemoguardrails.server.metrics.ENV_PORT = 'NEMO_GUARDRAILS_SERVER_METRICS_PORT'
nemoguardrails.server.metrics.ENV_SERVICE_NAME = 'NEMO_GUARDRAILS_SERVER_METRICS_SERVICE_NAME'
nemoguardrails.server.metrics.EXPORTED_INSTRUMENT_PATTERNS = ('guardrails.nonstream.*',)
nemoguardrails.server.metrics.INSTALL_HINT = 'pip install "nemoguardrails[server]"'
nemoguardrails.server.metrics._WILDCARD_HOSTS = frozenset({'0.0.0.0', '::', ''})
nemoguardrails.server.metrics._active_exporter: Optional[PrometheusMetricsExporter] = None
nemoguardrails.server.metrics._holders_lock = threading.Lock()
nemoguardrails.server.metrics._installed_provider: Optional[_InstalledProvider] = None
nemoguardrails.server.metrics.log = logging.getLogger(__name__)