> 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.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/guardrails/_mcp/server.

# nemoguardrails.tracing.spans

Span models for NeMo Guardrails tracing system.

## Module Contents

### Classes

| Name                                                               | Description                                                |
| ------------------------------------------------------------------ | ---------------------------------------------------------- |
| [`ActionSpan`](#nemoguardrails-tracing-spans-ActionSpan)           | Span for an action execution (internal span).              |
| [`BaseSpan`](#nemoguardrails-tracing-spans-BaseSpan)               | Base span with common fields across all span types.        |
| [`InteractionSpan`](#nemoguardrails-tracing-spans-InteractionSpan) | Top-level span for a guardrails interaction (server span). |
| [`LLMSpan`](#nemoguardrails-tracing-spans-LLMSpan)                 | Span for an LLM API call (client span).                    |
| [`RailSpan`](#nemoguardrails-tracing-spans-RailSpan)               | Span for a guardrail execution (internal span).            |
| [`SpanEvent`](#nemoguardrails-tracing-spans-SpanEvent)             | Event that can be attached to a span.                      |
| [`SpanKind`](#nemoguardrails-tracing-spans-SpanKind)               | -                                                          |
| [`SpanLegacy`](#nemoguardrails-tracing-spans-SpanLegacy)           | Simple span model (v1) for basic tracing.                  |

### Functions

| Name                                                                           | Description                              |
| ------------------------------------------------------------------------------ | ---------------------------------------- |
| [`is_opentelemetry_span`](#nemoguardrails-tracing-spans-is_opentelemetry_span) | Check if an object is a typed span (V2). |

### Data

[`SpanOpentelemetry`](#nemoguardrails-tracing-spans-SpanOpentelemetry)

[`TypedSpan`](#nemoguardrails-tracing-spans-TypedSpan)

### API

```python
class nemoguardrails.tracing.spans.ActionSpan()
```

**Bases:** [BaseSpan](#nemoguardrails-tracing-spans-BaseSpan)

Span for an action execution (internal span).

**`action_name`** `str`

---

**`action_params`** `Dict[str, Any]`

---

**`has_llm_calls`** `bool`

---

**`llm_calls_count`** `int`

---

**`span_kind`** `SpanKind = SpanKind.INTERNAL`

---

```python
nemoguardrails.tracing.spans.ActionSpan.to_otel_attributes() -> typing.Dict[str, typing.Any]
```

Convert to OTel attributes.

```python
class nemoguardrails.tracing.spans.BaseSpan()
```

Abstract

**Bases:** `BaseModel`

Base span with common fields across all span types.

**`custom_attributes`** `Dict[str, Any]`

---

**`duration`** `float`

---

**`end_time`** `float`

---

**`error`** `Optional[bool]`

---

**`error_message`** `Optional[str]`

---

**`error_type`** `Optional[str]`

---

**`events`** `List[SpanEvent]`

---

**`name`** `str`

---

**`parent_id`** `Optional[str]`

---

**`span_id`** `str`

---

**`span_kind`** `SpanKind = Field(description='OpenTelemetry span kind')`

---

**`start_time`** `float`

---

```python
nemoguardrails.tracing.spans.BaseSpan._base_attributes() -> typing.Dict[str, typing.Any]
```

Get common attributes for all span types.

```python
nemoguardrails.tracing.spans.BaseSpan.to_otel_attributes() -> typing.Dict[str, typing.Any]
```

abstract

Convert typed fields to legacy OpenTelemetry attributes dictionary.

**Returns:** `Dict[str, Any]`

Dict containing OTel semantic convention attributes.

```python
class nemoguardrails.tracing.spans.InteractionSpan()
```

**Bases:** [BaseSpan](#nemoguardrails-tracing-spans-BaseSpan)

Top-level span for a guardrails interaction (server span).

**`operation_name`** `str`

---

**`request_id`** `Optional[str]`

---

**`service_name`** `str`

---

**`session_id`** `Optional[str]`

---

**`span_kind`** `SpanKind = SpanKind.SERVER`

---

**`user_id`** `Optional[str] = Field(default=None, description='User identifier')`

---

```python
nemoguardrails.tracing.spans.InteractionSpan.to_otel_attributes() -> typing.Dict[str, typing.Any]
```

Convert to OTel attributes.

```python
class nemoguardrails.tracing.spans.LLMSpan()
```

**Bases:** [BaseSpan](#nemoguardrails-tracing-spans-BaseSpan)

Span for an LLM API call (client span).

**`cache_hit`** `bool`

---

**`frequency_penalty`** `Optional[float]`

---

**`max_tokens`** `Optional[int]`

---

**`operation_name`** `str`

---

**`presence_penalty`** `Optional[float]`

---

**`provider_name`** `str`

---

**`request_model`** `str = Field(description='Model requested (e.g., gpt-4)')`

---

**`response_finish_reasons`** `Optional[List[str]]`

---

**`response_id`** `Optional[str]`

---

**`response_model`** `str`

---

**`span_kind`** `SpanKind = SpanKind.CLIENT`

---

**`stop_sequences`** `Optional[List[str]] = Field(default=None, description='Stop sequences')`

---

**`temperature`** `Optional[float]`

---

**`top_k`** `Optional[int] = Field(default=None, description='Top-k parameter')`

---

**`top_p`** `Optional[float] = Field(default=None, description='Top-p parameter')`

---

**`usage_input_tokens`** `Optional[int]`

---

**`usage_output_tokens`** `Optional[int]`

---

**`usage_total_tokens`** `Optional[int]`

---

```python
nemoguardrails.tracing.spans.LLMSpan.to_otel_attributes() -> typing.Dict[str, typing.Any]
```

Convert to OTel attributes.

```python
class nemoguardrails.tracing.spans.RailSpan()
```

**Bases:** [BaseSpan](#nemoguardrails-tracing-spans-BaseSpan)

Span for a guardrail execution (internal span).

**`rail_decisions`** `Optional[List[str]]`

---

**`rail_name`** `str`

---

**`rail_stop`** `Optional[bool]`

---

**`rail_type`** `str`

---

**`span_kind`** `SpanKind = SpanKind.INTERNAL`

---

```python
nemoguardrails.tracing.spans.RailSpan.to_otel_attributes() -> typing.Dict[str, typing.Any]
```

Convert to OTel attributes.

```python
class nemoguardrails.tracing.spans.SpanEvent()
```

**Bases:** `BaseModel`

Event that can be attached to a span.

**`attributes`** `Dict[str, Any]`

---

**`body`** `Optional[Dict[str, Any]]`

---

**`name`** `str`

---

**`timestamp`** `float`

---

```python
class nemoguardrails.tracing.spans.SpanKind
```

**Bases:** `enum.Enum`

**`CLIENT`** `= 'client'`

---

**`INTERNAL`** `= 'internal'`

---

**`SERVER`** `= 'server'`

---

```python
class nemoguardrails.tracing.spans.SpanLegacy()
```

**Bases:** `BaseModel`

Simple span model (v1) for basic tracing.

**`duration`** `float`

---

**`end_time`** `float = Field(description='The end time of the span.')`

---

**`metrics`** `Dict[str, Union[int, float]]`

---

**`name`** `str`

---

**`parent_id`** `Optional[str]`

---

**`resource_id`** `Optional[str]`

---

**`span_id`** `str = Field(description='The id of the span.')`

---

**`start_time`** `float = Field(description='The start time of the span.')`

---

```python
nemoguardrails.tracing.spans.is_opentelemetry_span(
    span: typing.Any
) -> bool
```

Check if an object is a typed span (V2).

**Parameters:**

**`span`** `Any`

Object to check

---

**Returns:** `bool`

True if the object is a typed span, False otherwise

```python
nemoguardrails.tracing.spans.SpanOpentelemetry = TypedSpan
```

```python
nemoguardrails.tracing.spans.TypedSpan = Union[InteractionSpan, RailSpan, ActionSpan, LLMSpan]
```