> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/lens/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/lens/_mcp/server.

# lens.helpers

Telemetry helper utilities: span\_cm, managed\_span, trace\_fn, safe\_set\_span\_attributes.

## Module Contents

### Functions

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

### Data

[`DEFAULT_REDACT_KEYS`](#lens-helpers-DEFAULT_REDACT_KEYS)

[`_SCALAR_TYPES`](#lens-helpers-_SCALAR_TYPES)

### API

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

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

---

**`name`**

Span name.

---

**`tracer`**

OTel tracer. Defaults to the global tracer.

---

**`**attributes`**

Key/value pairs set as span attributes.

---

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

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

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

Span name.

---

**`tracer`**

OTel tracer. Defaults to the global tracer.

---

**`record_exception`**

If True, record exceptions as span events.

---

**`**attributes`**

Key/value pairs set as span attributes.

---

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

Span group name.

---

**`name`**

OTel span name.

---

**`tracer`**

OTel tracer. Defaults to the global tracer.

---

**Returns:**

A decorator that wraps the target function.

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

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