Configuration

NemoLensConfig is the single configuration object consumed by setup_telemetry. It holds every knob exposed by the library.

Construction

Construct a NemoLensConfig object using either environment variables or direct instantiation in Python.

From Environment

1
from nemo.lens import NemoLensConfig
2
3
cfg = NemoLensConfig.from_env()

Reads NEMO_LENS_* env vars. For library-specific prefixes, pass prefix and fallback_prefix:

1
cfg = NemoLensConfig.from_env(
2
    prefix='MEGATRON_OTEL',
3
    fallback_prefix='NEMO_LENS',
4
    span_group_cls=MegatronSpanGroup,
5
)

The prefix and fallback pattern lets each consumer have library-scoped env vars while sharing common defaults. The primary prefix wins; the fallback applies only if the primary is unset.

Direct Construction

1
cfg = NemoLensConfig(
2
    enabled=True,
3
    service_name='my-training-run',
4
    export_strategy='all_ranks',
5
    span_groups='per_step',
6
)

Field validation runs in __post_init__: export_sample_rate must be in [0.0, 1.0], otherwise ValueError.

Fields

A NemoLensConfig object contains fields divided into several functional categories.

Core

Export Strategy

Controls which ranks send telemetry to the collector. Three strategies are available: single_rank (default), all_ranks, and sampled. See Sampling for detailed semantics, when to use each, and how they compose with OTel SDK samplers. Unknown strategy names raise a ValueError at setup_telemetry time, not at configuration construction; register custom strategies before initializing telemetry. See Custom Export Strategies.

Signal Toggles

Granularity

Backend

With exporter="console" (the env var NEMO_LENS_EXPORTER=console), NeMo Lens uses the ConsoleSpanExporter and ConsoleMetricExporter from the SDK, which print spans and metrics to stdout. Any value other than "otlp" or "console" raises a ValueError("Unknown exporter type: ...") when the providers are built.

Identification

W&B Weave

Environment Variables

Most configuration fields have a corresponding <PREFIX>_<KEY> env var. Three are exceptions that bypass the prefix and fallback model entirely: service_name reads the bare OTEL_SERVICE_NAME, and wandb_entity and wandb_project read the bare WANDB_ENTITY and WANDB_PROJECT (without a prefix or fallback). Note also that the user field’s env var is <PREFIX>_USER_ID (e.g., NEMO_LENS_USER_ID), not _USER. Using NEMO_LENS as the prefix:

Boolean parsing accepts: 1/0, true/false, yes/no, on/off (case-insensitive). Any other value raises ValueError.

Standard OTel SDK Env Vars

Standard OTel SDK env vars are honored; most are read by the SDK directly, but a few are consumed by NeMo Lens’s provider-building code: OTEL_EXPORTER_OTLP_PROTOCOL (and the signal-specific OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_PROTOCOL, which wins; default grpc) selects the OTLP transport, and OTEL_METRIC_EXPORT_INTERVAL (default 10000 ms) sets the metric reader’s export interval:

In addition, build_providers reads the non-prefixed DEPLOYMENT_ENV (falling back to ENVIRONMENT) and, when set, emits it as the deployment.environment resource attribute.

setup_telemetry Signature

1
setup_telemetry(
2
    config: NemoLensConfig,
3
    rank: int = 0,
4
    world_size: int = 1,
5
    resource_attributes: dict | None = None,
6
    span_exporter=None,
7
    metric_reader=None,
8
    export_strategy: ExportStrategy | None = None,
9
    _allow_reinit: bool = False,
10
) -> TelemetryHandle

Returns a TelemetryHandle exposing:

• .tracer and .meter: read-only properties holding the OTel tracer and meter (no-op objects on non-exporting ranks).
• .is_exporting: a bool indicating whether this rank built real exporting providers.
• .shutdown(timeout_ms=5000): force-flushes and shuts down both the tracer and meter providers.