> 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.distributed

Cross-rank trace context broadcast and linked spans.

Provides helpers for sharing a trace\_id across all ranks (so that
distributed training appears as a single trace) and for creating
linked spans that reference remote contexts.

## Module Contents

### Functions

| Name                                                                   | Description                                                    |
| ---------------------------------------------------------------------- | -------------------------------------------------------------- |
| [`broadcast_trace_context`](#lens-distributed-broadcast_trace_context) | Broadcast W3C trace context from src\_rank to all other ranks. |
| [`create_linked_span`](#lens-distributed-create_linked_span)           | Create a span with a link to a remote span context.            |

### API

```python
lens.distributed.broadcast_trace_context(
    rank: int,
    src_rank: int = 0
) -> dict | None
```

Broadcast W3C trace context from src\_rank to all other ranks.

Must be called after `torch.distributed.init_process_group()`.
Returns a carrier dict with the broadcasted trace context.

**Parameters:**

**`rank`**

Current process rank.

---

**`src_rank`**

Rank that holds the source context.

---

**Returns:** `dict | None`

A carrier dict with the broadcasted trace context, or None if

```python
lens.distributed.create_linked_span(
    tracer: opentelemetry.trace.Tracer,
    name: str,
    remote_context: opentelemetry.context.Context | None = None,
    remote_carrier: dict | None = None,
    attributes = {}
) -> opentelemetry.trace.Span
```

Create a span with a link to a remote span context.

Use this for cross-rank or cross-service span correlation where
parent-child relationships don't make sense (e.g., pipeline parallel
stages).

**Parameters:**

**`tracer`**

OTel tracer.

---

**`name`**

Span name.

---

**`remote_context`**

An OTel Context from extract\_context().

---

**`remote_carrier`**

A W3C carrier dict (alternative to remote\_context).

---

**`**attributes`** — default: \{}

Span attributes.

---

**Returns:** `trace.Span`

The created Span (already started, caller must end it).