Skip to navigation

Subpackages

Submodules

Package Contents

Classes

NameDescription
InteractionLogDetailed log about the execution of an interaction.
InteractionOutputSimple model for interaction output used in tracer.
SpanEventEvent that can be attached to a span.
SpanExtractorBase class for span extractors.
SpanExtractorV1Extract v1 spans (legacy format).
SpanExtractorV2Extract v2 spans with OpenTelemetry semantic conventions.
SpanLegacySimple span model (v1) for basic tracing.
Tracer-

Functions

NameDescription
create_log_adapters-
create_span_extractorCreate a span extractor based on format and configuration.

Data

SpanOpentelemetry

API

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]]
class nemoguardrails.tracing.InteractionOutput()

Bases: BaseModel

Simple model for interaction output used in tracer.

id
str
input
Any
output
Optional[Any]
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
class nemoguardrails.tracing.SpanExtractor()
Abstract

Base class for span extractors.

nemoguardrails.tracing.SpanExtractor.extract_spans(
activated_rails: typing.List[nemoguardrails.rails.llm.options.ActivatedRail]
abstract

Extract spans from activated rails.

class nemoguardrails.tracing.SpanExtractorV1()

Bases: SpanExtractor

Extract v1 spans (legacy format).

nemoguardrails.tracing.SpanExtractorV1.extract_spans(
activated_rails: typing.List[nemoguardrails.rails.llm.options.ActivatedRail]

Extract v1 spans from activated rails.

class nemoguardrails.tracing.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.SpanExtractorV2._extract_conversation_events(
ref_time: float

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

Extract finish reasons from raw LLM response.

nemoguardrails.tracing.SpanExtractorV2._extract_llm_events(
llm_call,
start_time: float

Extract OpenTelemetry GenAI message events from an LLM call.

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

nemoguardrails.tracing.SpanExtractorV2.extract_spans(
activated_rails: typing.List[nemoguardrails.rails.llm.options.ActivatedRail]

Extract v2 spans from activated rails with OpenTelemetry attributes.

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.')
class nemoguardrails.tracing.Tracer(
input,
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 []
nemoguardrails.tracing.Tracer.add_adapter(
)

Adds an adapter to the tracer.

nemoguardrails.tracing.Tracer.export()

Exports the interaction log using the configured adapters.

nemoguardrails.tracing.Tracer.export_async()
async

Exports the interaction log using the configured adapters.

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

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

nemoguardrails.tracing.create_log_adapters(
nemoguardrails.tracing.create_span_extractor(
span_format: str = 'legacy',
events: typing.Optional[typing.List[dict]] = None,
enable_content_capture: bool = True

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
nemoguardrails.tracing.spans.SpanOpentelemetry = TypedSpan