> This page is for version v0.25.0.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo/guardrails/latest/llms.txt
> - v0.25.0: https://docs.nvidia.com/nemo/guardrails/v0.25.0/llms.txt
> - v0.24.1: https://docs.nvidia.com/nemo/guardrails/v0.24.1/llms.txt
> - v0.24.0: https://docs.nvidia.com/nemo/guardrails/v0.24.0/llms.txt
> - v0.23.0: https://docs.nvidia.com/nemo/guardrails/v0.23.0/llms.txt
> - v0.22.0: https://docs.nvidia.com/nemo/guardrails/v0.22.0/llms.txt

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

# nemoguardrails.tracing

## Subpackages

* **[`nemoguardrails.tracing.adapters`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/adapters)**

## Submodules

* **[`nemoguardrails.tracing.constants`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/constants)**
* **[`nemoguardrails.tracing.interaction_types`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/interaction_types)**
* **[`nemoguardrails.tracing.span_extractors`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/span_extractors)**
* **[`nemoguardrails.tracing.span_format`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/span_format)**
* **[`nemoguardrails.tracing.span_formatting`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/span_formatting)**
* **[`nemoguardrails.tracing.spans`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/spans)**
* **[`nemoguardrails.tracing.tracer`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/tracer)**

## Package Contents

### Classes

| Name                                                                               | Description                                               |
| ---------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [`InteractionLog`](#nemoguardrails-tracing-interaction_types-InteractionLog)       | Detailed log about the execution of an interaction.       |
| [`InteractionOutput`](#nemoguardrails-tracing-interaction_types-InteractionOutput) | Simple model for interaction output used in tracer.       |
| [`SpanEvent`](#nemoguardrails-tracing-spans-SpanEvent)                             | Event that can be attached to a span.                     |
| [`SpanExtractor`](#nemoguardrails-tracing-span_extractors-SpanExtractor)           | Base class for span extractors.                           |
| [`SpanExtractorV1`](#nemoguardrails-tracing-span_extractors-SpanExtractorV1)       | Extract v1 spans (legacy format).                         |
| [`SpanExtractorV2`](#nemoguardrails-tracing-span_extractors-SpanExtractorV2)       | Extract v2 spans with OpenTelemetry semantic conventions. |
| [`SpanLegacy`](#nemoguardrails-tracing-spans-SpanLegacy)                           | Simple span model (v1) for basic tracing.                 |
| [`Tracer`](#nemoguardrails-tracing-tracer-Tracer)                                  | -                                                         |

### Functions

| Name                                                                                     | Description                                                |
| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [`create_log_adapters`](#nemoguardrails-tracing-tracer-create_log_adapters)              | -                                                          |
| [`create_span_extractor`](#nemoguardrails-tracing-span_extractors-create_span_extractor) | Create a span extractor based on format and configuration. |

### Data

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

### API

```python
class nemoguardrails.tracing.InteractionLog()
```

**Bases:** `BaseModel`

Detailed log about the execution of an interaction.

**`activated_rails`** `List[ActivatedRail]`

---

**`events`** `List[dict]`

---

**`id`** `str`

---

**`trace`** `List[Union[SpanLegacy, SpanOpentelemetry]]`

---

```python
class nemoguardrails.tracing.InteractionOutput()
```

**Bases:** `BaseModel`

Simple model for interaction output used in tracer.

**`id`** `str`

---

**`input`** `Any`

---

**`output`** `Optional[Any]`

---

```python
class nemoguardrails.tracing.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.SpanExtractor()
```

Abstract

Base class for span extractors.

```python
nemoguardrails.tracing.SpanExtractor.extract_spans(
    activated_rails: typing.List[nemoguardrails.rails.llm.options.ActivatedRail]
) -> typing.List[typing.Union[nemoguardrails.tracing.spans.SpanLegacy, nemoguardrails.tracing.spans.SpanOpentelemetry]]
```

abstract

Extract spans from activated rails.

```python
class nemoguardrails.tracing.SpanExtractorV1()
```

**Bases:** [SpanExtractor](#nemoguardrails-tracing-span_extractors-SpanExtractor)

Extract v1 spans (legacy format).

```python
nemoguardrails.tracing.SpanExtractorV1.extract_spans(
    activated_rails: typing.List[nemoguardrails.rails.llm.options.ActivatedRail]
) -> typing.List[typing.Union[nemoguardrails.tracing.spans.SpanLegacy, nemoguardrails.tracing.spans.SpanOpentelemetry]]
```

Extract v1 spans from activated rails.

```python
class nemoguardrails.tracing.SpanExtractorV2(
    events: typing.Optional[typing.List[dict]] = None,
    enable_content_capture: bool = False
)
```

**Bases:** [SpanExtractor](#nemoguardrails-tracing-span_extractors-SpanExtractor)

Extract v2 spans with OpenTelemetry semantic conventions.

**`internal_events`** `= events or []`

---

```python
nemoguardrails.tracing.SpanExtractorV2._extract_conversation_events(
    ref_time: float
) -> typing.List[nemoguardrails.tracing.spans.SpanEvent]
```

Extract guardrails-specific conversation events from internal events.

NOTE: These are NeMo Guardrails internal events, NOT OpenTelemetry GenAI events.
We use guardrails-specific namespacing to avoid confusion with OTel GenAI semantic conventions.

```python
nemoguardrails.tracing.SpanExtractorV2._extract_finish_reasons(
    raw_response: dict
) -> typing.Optional[typing.List[str]]
```

Extract finish reasons from raw LLM response.

```python
nemoguardrails.tracing.SpanExtractorV2._extract_llm_events(
    llm_call,
    start_time: float
) -> typing.List[nemoguardrails.tracing.spans.SpanEvent]
```

Extract OpenTelemetry GenAI message events from an LLM call.

```python
nemoguardrails.tracing.SpanExtractorV2._get_event_timestamp(
    event: dict,
    ref_time: float
) -> float
```

Extract timestamp from event or use reference time.

**Parameters:**

**`event`** `dict`

The internal event dictionary

---

**`ref_time`** `float`

Reference time to use as fallback (trace start time)

---

**Returns:** `float`

Timestamp in seconds relative to trace start

```python
nemoguardrails.tracing.SpanExtractorV2.extract_spans(
    activated_rails: typing.List[nemoguardrails.rails.llm.options.ActivatedRail]
) -> typing.List[typing.Union[nemoguardrails.tracing.spans.SpanLegacy, nemoguardrails.tracing.spans.SpanOpentelemetry]]
```

Extract v2 spans from activated rails with OpenTelemetry attributes.

```python
class nemoguardrails.tracing.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
class nemoguardrails.tracing.Tracer(
    input,
    response: nemoguardrails.rails.llm.options.GenerationResponse,
    adapters: typing.Optional[typing.List[nemoguardrails.tracing.adapters.base.InteractionLogAdapter]] = None,
    span_format: str = 'opentelemetry',
    enable_content_capture: bool = False
)
```

**`_generation_log`** `= response.log`

---

**`_interaction_output`**

---

**`adapters`** `= adapters or []`

---

```python
nemoguardrails.tracing.Tracer.add_adapter(
    adapter: nemoguardrails.tracing.adapters.base.InteractionLogAdapter
)
```

Adds an adapter to the tracer.

```python
nemoguardrails.tracing.Tracer.export()
```

Exports the interaction log using the configured adapters.

```python
nemoguardrails.tracing.Tracer.export_async()
```

async

Exports the interaction log using the configured adapters.

```python
nemoguardrails.tracing.Tracer.generate_interaction_log(
    interaction_output: typing.Optional[nemoguardrails.tracing.interaction_types.InteractionOutput] = None,
    generation_log: typing.Optional[nemoguardrails.rails.llm.options.GenerationLog] = None
) -> nemoguardrails.tracing.interaction_types.InteractionLog
```

Generates an InteractionLog from the given interaction output and generation log.

```python
nemoguardrails.tracing.create_log_adapters(
    config: nemoguardrails.rails.llm.config.TracingConfig
) -> typing.List[nemoguardrails.tracing.adapters.base.InteractionLogAdapter]
```

```python
nemoguardrails.tracing.create_span_extractor(
    span_format: str = 'legacy',
    events: typing.Optional[typing.List[dict]] = None,
    enable_content_capture: bool = True
) -> nemoguardrails.tracing.span_extractors.SpanExtractor
```

Create a span extractor based on format and configuration.

**Parameters:**

**`span_format`** `str` — default: 'legacy'

Format of span extractor ('legacy' or 'opentelemetry')

---

**`events`** `Optional[List[dict]]` — default: None

Internal events for OpenTelemetry extractor

---

**`enable_content_capture`** `bool` — default: True

Whether to capture content in spans

---

**Returns:** [`SpanExtractor`](#nemoguardrails-tracing-span_extractors-SpanExtractor)

Configured span extractor instance

**Raises:**

* `ValueError`: If span_format is not supported

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