lens.helpers | NVIDIA NeMo Lens

Telemetry helper utilities: span_cm, managed_span, trace_fn, safe_set_span_attributes.

Module Contents

Functions

Name	Description
`managed_span`	Explicit-lifecycle span guarded by a span-group check.
`redact_value`	Return `'[REDACTED]'` if key is in redact_keys, else value.
`safe_set_span_attributes`	Set span attributes, silently skipping non-scalar values.
`span_cm`	Context manager that creates an OTel span for a code block.
`trace_fn`	Decorator that wraps a function in a group-gated OTel span.

Data

DEFAULT_REDACT_KEYS

_SCALAR_TYPES

API

lens.helpers.managed_span(
    group: str,
    name: str,
    tracer: opentelemetry.trace.Tracer | None = None,
    attributes: typing.Any = {}
)

Explicit-lifecycle span guarded by a span-group check.

When the group is disabled the body executes normally and None is yielded — no span object is created. When enabled, the span is started, its context attached, and always ended in a finally block.

Parameters:

group

str

Span group name. If not enabled, this is a zero-overhead no-op.

name

str

Span name.

tracer

trace.Tracer | None" default="None

OTel tracer. Defaults to the global tracer.

**attributes

Any" default="{}

Key/value pairs set as span attributes.

lens.helpers.redact_value(
    key: str,
    value: str,
    redact_keys: frozenset = DEFAULT_REDACT_KEYS
) -> str

Return '[REDACTED]' if key is in redact_keys, else value.

lens.helpers.safe_set_span_attributes(
    span: opentelemetry.trace.Span,
    attributes: dict,
    redact_keys: frozenset = DEFAULT_REDACT_KEYS
) -> None

Set span attributes, silently skipping non-scalar values.

OTel span attributes must be scalars (bool, int, float, str) or sequences of scalars. Redacts string values whose keys are in redact_keys.

lens.helpers.span_cm(
    name: str,
    tracer: opentelemetry.trace.Tracer | None = None,
    record_exception: bool = True,
    attributes: typing.Any = {}
)

Context manager that creates an OTel span for a code block.

Safe to use with no-op tracers.

Parameters:

name

str

Span name.

tracer

trace.Tracer | None" default="None

OTel tracer. Defaults to the global tracer.

record_exception

bool" default="True

If True, record exceptions as span events.

**attributes

Any" default="{}

Key/value pairs set as span attributes.

lens.helpers.trace_fn(
    group: str,
    name: str,
    tracer: opentelemetry.trace.Tracer | None = None
)

Decorator that wraps a function in a group-gated OTel span.

The span group is checked at call time (not decoration time).

Parameters:

group

str

Span group name.

name

str

OTel span name.

tracer

trace.Tracer | None" default="None

OTel tracer. Defaults to the global tracer.

Returns:

A decorator that wraps the target function.

lens.helpers.DEFAULT_REDACT_KEYS: frozenset = frozenset({'prompt', 'input_text', 'output_text', 'text', 'password', 'token', '...

lens.helpers._SCALAR_TYPES = (bool, int, float, str)