> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/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 ``` ## Docs - [nemoguardrails.tracing.adapters](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/adapters.md) - [nemoguardrails.tracing.adapters.base](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/adapters/base.md) - [nemoguardrails.tracing.adapters.filesystem](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/adapters/filesystem.md) - [nemoguardrails.tracing.adapters.opentelemetry](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/adapters/opentelemetry.md) - [nemoguardrails.tracing.adapters.registry](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/adapters/registry.md) - [nemoguardrails.tracing.constants](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/constants.md) - [nemoguardrails.tracing.interaction_types](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/interaction_types.md) - [nemoguardrails.tracing.span_extractors](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/span_extractors.md) - [nemoguardrails.tracing.span_format](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/span_format.md) - [nemoguardrails.tracing.span_formatting](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/span_formatting.md) - [nemoguardrails.tracing.spans](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/spans.md) - [nemoguardrails.tracing.tracer](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/tracing/tracer.md)