nemoguardrails.tracing.span_extractors | NVIDIA NeMo Guardrails Library Developer Guide

Span extraction logic for different span versions.

Module Contents

Classes

Name	Description
`SpanExtractor`	Base class for span extractors.
`SpanExtractorV1`	Extract v1 spans (legacy format).
`SpanExtractorV2`	Extract v2 spans with OpenTelemetry semantic conventions.

Functions

Name	Description
`create_span_extractor`	Create a span extractor based on format and configuration.

API

class nemoguardrails.tracing.span_extractors.SpanExtractor()

Abstract

Base class for span extractors.

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]]) -> typing.List[typing.Union[nemoguardrails.tracing.spans.SpanLegacy, nemoguardrails.tracing.spans.SpanOpentelemetry]]

abstract

Extract spans from activated rails.

class nemoguardrails.tracing.span_extractors.SpanExtractorV1()

Bases: SpanExtractor

Extract v1 spans (legacy format).

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]]) -> typing.List[typing.Union[nemoguardrails.tracing.spans.SpanLegacy, nemoguardrails.tracing.spans.SpanOpentelemetry]]

Extract v1 spans from activated rails.

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

Bases: SpanExtractor

Extract v2 spans with OpenTelemetry semantic conventions.

internal_events

= events or []

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.

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

Extract finish reasons from raw LLM response.

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.

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

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]]) -> typing.List[typing.Union[nemoguardrails.tracing.spans.SpanLegacy, nemoguardrails.tracing.spans.SpanOpentelemetry]]

Extract v2 spans from activated rails with OpenTelemetry attributes.

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:

span_format

strDefaults to 'legacy'

Format of span extractor (‘legacy’ or ‘opentelemetry’)

events

Optional[List[dict]]Defaults to None

Internal events for OpenTelemetry extractor

enable_content_capture

boolDefaults to True

Whether to capture content in spans

Returns: SpanExtractor

Configured span extractor instance

Raises:

ValueError: If span_format is not supported