ReferencePython SDK ReferenceNemoguardrailsTracing

nemoguardrails.tracing.spans

View as Markdown

Span models for NeMo Guardrails tracing system.

Module Contents

Classes

NameDescription
ActionSpanSpan for an action execution (internal span).
BaseSpanBase span with common fields across all span types.
InteractionSpanTop-level span for a guardrails interaction (server span).
LLMSpanSpan for an LLM API call (client span).
RailSpanSpan for a guardrail execution (internal span).
SpanEventEvent that can be attached to a span.
SpanKind-
SpanLegacySimple span model (v1) for basic tracing.

Functions

NameDescription
is_opentelemetry_spanCheck if an object is a typed span (V2).

Data

SpanOpentelemetry

TypedSpan

API

class nemoguardrails.tracing.spans.ActionSpan()

Bases: BaseSpan

Span for an action execution (internal span).

action_name
str
action_params
Dict[str, Any]
has_llm_calls
bool
llm_calls_count
int
span_kind
SpanKind = SpanKind.INTERNAL
nemoguardrails.tracing.spans.ActionSpan.to_otel_attributes() -> typing.Dict[str, typing.Any]

Convert to OTel attributes.

class nemoguardrails.tracing.spans.BaseSpan()
Abstract

Bases: BaseModel

Base span with common fields across all span types.

custom_attributes
Dict[str, Any]
duration
float
end_time
float
error
Optional[bool]
error_message
Optional[str]
error_type
Optional[str]
events
List[SpanEvent]
name
str
parent_id
Optional[str]
span_id
str
span_kind
SpanKind = Field(description='OpenTelemetry span kind')
start_time
float
nemoguardrails.tracing.spans.BaseSpan._base_attributes() -> typing.Dict[str, typing.Any]

Get common attributes for all span types.

nemoguardrails.tracing.spans.BaseSpan.to_otel_attributes() -> typing.Dict[str, typing.Any]
abstract

Convert typed fields to legacy OpenTelemetry attributes dictionary.

Returns: Dict[str, Any]

Dict containing OTel semantic convention attributes.

class nemoguardrails.tracing.spans.InteractionSpan()

Bases: BaseSpan

Top-level span for a guardrails interaction (server span).

operation_name
str
request_id
Optional[str]
service_name
str
session_id
Optional[str]
span_kind
SpanKind = SpanKind.SERVER
user_id
Optional[str] = Field(default=None, description='User identifier')
nemoguardrails.tracing.spans.InteractionSpan.to_otel_attributes() -> typing.Dict[str, typing.Any]

Convert to OTel attributes.

class nemoguardrails.tracing.spans.LLMSpan()

Bases: BaseSpan

Span for an LLM API call (client span).

cache_hit
bool
frequency_penalty
Optional[float]
max_tokens
Optional[int]
operation_name
str
presence_penalty
Optional[float]
provider_name
str
request_model
str = Field(description='Model requested (e.g., gpt-4)')
response_finish_reasons
Optional[List[str]]
response_id
Optional[str]
response_model
str
span_kind
SpanKind = SpanKind.CLIENT
stop_sequences
Optional[List[str]] = Field(default=None, description='Stop sequences')
temperature
Optional[float]
top_k
Optional[int] = Field(default=None, description='Top-k parameter')
top_p
Optional[float] = Field(default=None, description='Top-p parameter')
usage_input_tokens
Optional[int]
usage_output_tokens
Optional[int]
usage_total_tokens
Optional[int]
nemoguardrails.tracing.spans.LLMSpan.to_otel_attributes() -> typing.Dict[str, typing.Any]

Convert to OTel attributes.

class nemoguardrails.tracing.spans.RailSpan()

Bases: BaseSpan

Span for a guardrail execution (internal span).

rail_decisions
Optional[List[str]]
rail_name
str
rail_stop
Optional[bool]
rail_type
str
span_kind
SpanKind = SpanKind.INTERNAL
nemoguardrails.tracing.spans.RailSpan.to_otel_attributes() -> typing.Dict[str, typing.Any]

Convert to OTel attributes.

class nemoguardrails.tracing.spans.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.spans.SpanKind

Bases: enum.Enum

CLIENT
= 'client'
INTERNAL
= 'internal'
SERVER
= 'server'
class nemoguardrails.tracing.spans.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.')
nemoguardrails.tracing.spans.is_opentelemetry_span(
    span: typing.Any
) -> bool

Check if an object is a typed span (V2).

Parameters:

span
Any

Object to check

Returns: bool

True if the object is a typed span, False otherwise

nemoguardrails.tracing.spans.SpanOpentelemetry = TypedSpan
 
nemoguardrails.tracing.spans.TypedSpan = Union[InteractionSpan, RailSpan, ActionSpan, LLMSpan]