> 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 full documentation content, see https://docs.nvidia.com/nemo/guardrails/llms-full.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.span_extractors

Span extraction logic for different span versions.

## Module Contents

### Classes

| Name                                                                         | Description                                               |
| ---------------------------------------------------------------------------- | --------------------------------------------------------- |
| [`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. |

### Functions

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

### API

```python
class nemoguardrails.tracing.span_extractors.SpanExtractor()
```

Abstract

Base class for span extractors.

```python
nemoguardrails.tracing.span_extractors.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.span_extractors.SpanExtractorV1()
```

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

Extract v1 spans (legacy format).

```python
nemoguardrails.tracing.span_extractors.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.span_extractors.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.

```python
nemoguardrails.tracing.span_extractors.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.span_extractors.SpanExtractorV2._extract_finish_reasons(
    raw_response: dict
) -> typing.Optional[typing.List[str]]
```

Extract finish reasons from raw LLM response.

```python
nemoguardrails.tracing.span_extractors.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.span_extractors.SpanExtractorV2._get_event_timestamp(
    event: dict,
    ref_time: float
) -> float
```

Extract timestamp from event or use reference time.

**Parameters:**

The internal event dictionary

Reference time to use as fallback (trace start time)

**Returns:** `float`

Timestamp in seconds relative to trace start

```python
nemoguardrails.tracing.span_extractors.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
nemoguardrails.tracing.span_extractors.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:**

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

Internal events for OpenTelemetry extractor

Whether to capture content in spans

**Returns:** `SpanExtractor`

Configured span extractor instance

**Raises:**

* `ValueError`: If span\_format is not supported