Tracing

OpenTelemetry tracing helpers for gllm-datastore.

This module provides a lazy singleton tracer accessor and semantic constants for OpenTelemetry span attributes and events used by datastore capabilities and cache operations. Library code emits spans through opentelemetry-api only; applications remain responsible for configuring tracer providers, exporters, sampling, and resources.

`SpanAttributes`

Semantic attribute keys for datastore OpenTelemetry spans.

These constants define the safe attribute namespace used by datastore and cache instrumentation. All keys follow the grouped gllm.datastore.* convention and should stay low-cardinality. Raw chunk content, query text, metadata values, vectors, credentials, headers, and backend request bodies must not be added to spans by default.

Attributes:

Name	Type	Description
`BACKEND`	`str`	Backend or datastore class name.
`CAPABILITY`	`str`	Capability name, such as `fulltext`, `vector`, `hybrid`, or `cache`.
`OPERATION`	`str`	Operation name, such as `retrieve`, `create`, `update`, `delete`, or `clear`.
`INPUT_COUNT`	`str`	Number of input chunks, items, or update fields when applicable.
`RESULT_COUNT`	`str`	Number of returned chunks when the result is a list.
`BATCH_SIZE`	`str`	Effective batch size for batched operations when applicable.
`FILTER_PRESENT`	`str`	Boolean flag indicating that filters were supplied.
`OPTIONS_LIMIT`	`str`	Safe query option for result limits.
`OPTIONS_OFFSET`	`str`	Safe query option for result offsets.
`OPTIONS_INCLUDE_FIELDS_COUNT`	`str`	Count of requested include fields.
`OPTIONS_ORDER_BY_PRESENT`	`str`	Boolean flag indicating legacy order_by was supplied.
`OPTIONS_ORDER_COUNT`	`str`	Count of structured order specs.
`OPTIONS_ORDER_DESC`	`str`	Boolean flag indicating descending legacy order.
`CACHE_MATCHING_STRATEGY`	`str`	Cache matching strategy name.
`CACHE_HIT`	`str`	Boolean flag indicating whether cache retrieval hit.

`SpanCapability`

Bases: StrEnum

Datastore capability names used in span names and attributes.

`SpanEvents`

Semantic event names for datastore OpenTelemetry spans.

Attributes:

Name	Type	Description
`ERROR`	`str`	Event name emitted when a datastore operation raises an exception. The event contains only safe exception type metadata.

`SpanOperation`

Bases: StrEnum

Datastore operation names used in span names and attributes.

`datastore_span_attributes(backend, capability, operation, *, filters=None, options=None, input_count=None, batch_size=None, extra=None)`

Build safe, low-cardinality span attributes for datastore operations.

This helper records only semantic operation metadata. It intentionally stores filter presence as a boolean and extracts only safe QueryOptions facts. It must not serialize filter values, raw query text, chunk content, metadata values, vectors, credentials, headers, or backend request bodies.

Parameters:

Name	Type	Description	Default
`backend`	`object`	Backend, capability, cache, or datastore instance used to derive the class-name attribute.	required
`capability`	`SpanCapability \| str`	Capability name for the span.	required
`operation`	`SpanOperation \| str`	Operation name for the span.	required
`filters`	`object \| None`	Filters supplied to the operation. Only presence is recorded. Defaults to None.	`None`
`options`	`object \| None`	Query options supplied to the operation. Numeric values and low-cardinality facts are recorded; field names and sort expressions are summarized by count/presence only. Defaults to None.	`None`
`input_count`	`int \| None`	Number of input chunks, items, or update fields when applicable. Defaults to None.	`None`
`batch_size`	`int \| None`	Effective batch size when applicable. Defaults to None.	`None`
`extra`	`dict[str, bool \| int \| str] \| None`	Additional safe, low-cardinality attributes to merge into the result. Defaults to None.	`None`

Returns:

Type	Description
`dict[str, bool \| int \| str]`	dict[str, bool \| int \| str]: Attributes ready to pass to `Tracer.start_as_current_span`.

`datastore_span_name(capability, operation)`

Build a stable span name for a datastore operation.

Parameters:

Name	Type	Description	Default
`capability`	`SpanCapability \| str`	Datastore capability name, such as `fulltext`, `vector`, `hybrid`, or `cache`.	required
`operation`	`SpanOperation \| str`	Operation name, such as `retrieve`, `create`, `update`, `delete`, or `clear`.	required

Returns:

Name	Type	Description
`str`	`str`	Span name using the `gllm.datastore.<capability>.<operation>` convention.

`get_tracer()`

Return the gllm-datastore tracer singleton.

When no tracer provider is configured, OpenTelemetry returns a no-op tracer.

Returns:

Type	Description
`Tracer`	trace.Tracer: Tracer instance for datastore instrumentation.

`set_span_error(span, exception)`

Record an exception and mark a datastore span as failed.

Parameters:

Name	Type	Description	Default
`span`	`Span`	The active span to update.	required
`exception`	`BaseException`	Exception raised by the datastore operation.	required

`set_span_success(span, result=None)`

Mark a datastore span as successful.

When the result is a list, this helper records the list length as the safe result-count attribute. It does not inspect list items or record their content.

Parameters:

Name	Type	Description	Default
`span`	`Span`	The active span to update.	required
`result`	`object \| None`	Operation result used only for safe result-count derivation. Defaults to None.	`None`