> This page is for version Latest (default).
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo/guardrails/latest/llms.txt
> - v0.25.0: https://docs.nvidia.com/nemo/guardrails/v0.25.0/llms.txt
> - v0.24.1: https://docs.nvidia.com/nemo/guardrails/v0.24.1/llms.txt
> - v0.24.0: https://docs.nvidia.com/nemo/guardrails/v0.24.0/llms.txt
> - v0.23.0: https://docs.nvidia.com/nemo/guardrails/v0.23.0/llms.txt
> - v0.22.0: https://docs.nvidia.com/nemo/guardrails/v0.22.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/llms.txt.

# 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

| Name                                                                                      | Description                                                                     |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [`MetricsExporter`](#nemoguardrails-server-metrics-MetricsExporter)                       | Supported values for `NEMO_GUARDRAILS_SERVER_METRICS_EXPORTER`.                 |
| [`MetricsExporterConfigError`](#nemoguardrails-server-metrics-MetricsExporterConfigError) | The metrics exporter cannot start with the current configuration.               |
| [`MetricsExporterSettings`](#nemoguardrails-server-metrics-MetricsExporterSettings)       | Resolved exporter settings; `from_env` is the only reader of the env vars.      |
| [`PrometheusMetricsExporter`](#nemoguardrails-server-metrics-PrometheusMetricsExporter)   | A running Prometheus scrape endpoint serving the installed provider's registry. |
| [`_InstalledProvider`](#nemoguardrails-server-metrics-_InstalledProvider)                 | The process-wide `MeterProvider` this module installed, plus the                |

### Functions

| Name                                                                                                          | Description                                                                                                |
| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| [`_display_host`](#nemoguardrails-server-metrics-_display_host)                                               | Render a listen address as the host a scraper would dial.                                                  |
| [`_hold_metrics_exporter`](#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. |
| [`_install_meter_provider`](#nemoguardrails-server-metrics-_install_meter_provider)                           | Install the global `MeterProvider` on first use and return it thereafter.                                  |
| [`_is_meter_provider_configured`](#nemoguardrails-server-metrics-_is_meter_provider_configured)               | True when something other than the API's own placeholder is installed.                                     |
| [`_release_metrics_exporter`](#nemoguardrails-server-metrics-_release_metrics_exporter)                       | Count a holder out, and stop the exporter if it was the last, a holder started it, and it still runs.      |
| [`_require_otel_sdk`](#nemoguardrails-server-metrics-_require_otel_sdk)                                       | Raise `MetricsExporterConfigError` unless every optional symbol is importable.                             |
| [`_warn_if_another_exporter_is_running`](#nemoguardrails-server-metrics-_warn_if_another_exporter_is_running) | Warn that the running exporter is served in place of the one `settings` ask for, when they differ.         |
| [`build_meter_provider`](#nemoguardrails-server-metrics-build_meter_provider)                                 | Build a `MeterProvider` that exports the scoped metrics into `registry`.                                   |
| [`build_views`](#nemoguardrails-server-metrics-build_views)                                                   | Return the SDK views that restrict export to `EXPORTED_INSTRUMENT_PATTERNS`.                               |
| [`get_active_metrics_exporter`](#nemoguardrails-server-metrics-get_active_metrics_exporter)                   | Return the running exporter, or `None` when none is active.                                                |
| [`running_metrics_exporter`](#nemoguardrails-server-metrics-running_metrics_exporter)                         | Yield the running exporter, starting one if none runs; the last holder to exit stops one a holder started. |
| [`shutdown_metrics_exporter`](#nemoguardrails-server-metrics-shutdown_metrics_exporter)                       | Stop the running exporter's listener, if any.  Safe to call repeatedly.                                    |
| [`start_metrics_exporter`](#nemoguardrails-server-metrics-start_metrics_exporter)                             | Start the configured exporter and return it.                                                               |

### Data

[`DEFAULT_HOST`](#nemoguardrails-server-metrics-DEFAULT_HOST)

[`DEFAULT_PORT`](#nemoguardrails-server-metrics-DEFAULT_PORT)

[`DEFAULT_SERVICE_NAME`](#nemoguardrails-server-metrics-DEFAULT_SERVICE_NAME)

[`ENV_EXPORTER`](#nemoguardrails-server-metrics-ENV_EXPORTER)

[`ENV_HOST`](#nemoguardrails-server-metrics-ENV_HOST)

[`ENV_PORT`](#nemoguardrails-server-metrics-ENV_PORT)

[`ENV_SERVICE_NAME`](#nemoguardrails-server-metrics-ENV_SERVICE_NAME)

[`EXPORTED_INSTRUMENT_PATTERNS`](#nemoguardrails-server-metrics-EXPORTED_INSTRUMENT_PATTERNS)

[`INSTALL_HINT`](#nemoguardrails-server-metrics-INSTALL_HINT)

[`_WILDCARD_HOSTS`](#nemoguardrails-server-metrics-_WILDCARD_HOSTS)

[`_active_exporter`](#nemoguardrails-server-metrics-_active_exporter)

[`_holders_lock`](#nemoguardrails-server-metrics-_holders_lock)

[`_installed_provider`](#nemoguardrails-server-metrics-_installed_provider)

[`log`](#nemoguardrails-server-metrics-log)

### API

```python
class nemoguardrails.server.metrics.MetricsExporter
```

**Bases:** `enum.Enum`

Supported values for `NEMO_GUARDRAILS_SERVER_METRICS_EXPORTER`.

**`NONE`** `= 'none'`

---

**`PROMETHEUS`** `= 'prometheus'`

---

```python
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.

```python
class nemoguardrails.server.metrics.MetricsExporterSettings(
    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`

---

```python
nemoguardrails.server.metrics.MetricsExporterSettings.from_env(
    environ: typing.Optional[typing.Mapping[str, str]] = None,
    defaults: typing.Optional[nemoguardrails.server.metrics.MetricsExporterSettings] = None
) -> nemoguardrails.server.metrics.MetricsExporterSettings
```

classmethod

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

```python
class nemoguardrails.server.metrics.PrometheusMetricsExporter(
    settings: nemoguardrails.server.metrics.MetricsExporterSettings,
    installed: nemoguardrails.server.metrics._InstalledProvider
)
```

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.

---

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

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

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

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

```python
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.

```python
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`

---

```python
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.

```python
nemoguardrails.server.metrics._hold_metrics_exporter(
    settings: nemoguardrails.server.metrics.MetricsExporterSettings
) -> typing.Optional[nemoguardrails.server.metrics.PrometheusMetricsExporter]
```

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

```python
nemoguardrails.server.metrics._install_meter_provider(
    settings: nemoguardrails.server.metrics.MetricsExporterSettings
) -> nemoguardrails.server.metrics._InstalledProvider
```

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.

```python
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.

```python
nemoguardrails.server.metrics._release_metrics_exporter(
    exporter: nemoguardrails.server.metrics.PrometheusMetricsExporter
) -> None
```

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

```python
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.

```python
nemoguardrails.server.metrics._warn_if_another_exporter_is_running(
    running: typing.Optional[nemoguardrails.server.metrics.PrometheusMetricsExporter],
    settings: nemoguardrails.server.metrics.MetricsExporterSettings
) -> None
```

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

```python
nemoguardrails.server.metrics.build_meter_provider(
    settings: nemoguardrails.server.metrics.MetricsExporterSettings,
    registry: prometheus_client.CollectorRegistry
) -> opentelemetry.sdk.metrics.MeterProvider
```

Build a `MeterProvider` that exports the scoped metrics into `registry`.

```python
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.

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

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

```python
nemoguardrails.server.metrics.running_metrics_exporter(
    settings: typing.Optional[nemoguardrails.server.metrics.MetricsExporterSettings] = None
) -> 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.

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

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

```python
nemoguardrails.server.metrics.start_metrics_exporter(
    settings: typing.Optional[nemoguardrails.server.metrics.MetricsExporterSettings] = None
) -> typing.Optional[nemoguardrails.server.metrics.PrometheusMetricsExporter]
```

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.

```python
nemoguardrails.server.metrics.DEFAULT_HOST = '0.0.0.0'
```

```python
nemoguardrails.server.metrics.DEFAULT_PORT = 9464
```

```python
nemoguardrails.server.metrics.DEFAULT_SERVICE_NAME = 'nemoguardrails-server'
```

```python
nemoguardrails.server.metrics.ENV_EXPORTER = 'NEMO_GUARDRAILS_SERVER_METRICS_EXPORTER'
```

```python
nemoguardrails.server.metrics.ENV_HOST = 'NEMO_GUARDRAILS_SERVER_METRICS_HOST'
```

```python
nemoguardrails.server.metrics.ENV_PORT = 'NEMO_GUARDRAILS_SERVER_METRICS_PORT'
```

```python
nemoguardrails.server.metrics.ENV_SERVICE_NAME = 'NEMO_GUARDRAILS_SERVER_METRICS_SERVICE_NAME'
```

```python
nemoguardrails.server.metrics.EXPORTED_INSTRUMENT_PATTERNS = ('guardrails.nonstream.*',)
```

```python
nemoguardrails.server.metrics.INSTALL_HINT = 'pip install "nemoguardrails[server]"'
```

```python
nemoguardrails.server.metrics._WILDCARD_HOSTS = frozenset({'0.0.0.0', '::', ''})
```

```python
nemoguardrails.server.metrics._active_exporter: Optional[PrometheusMetricsExporter] = None
```

```python
nemoguardrails.server.metrics._holders_lock = threading.Lock()
```

```python
nemoguardrails.server.metrics._installed_provider: Optional[_InstalledProvider] = None
```

```python
nemoguardrails.server.metrics.log = logging.getLogger(__name__)
```