GitHub

telemetry

API reference for telemetry.

GenAI span attributes (Effect's Telemetry): the OpenTelemetry semantic conventions for generative AI, written onto a span::

telemetry.add_gen_ai_annotations(
    span,
    {"provider": {"name": "openai"}, "usage": {"input_tokens": 10}},
)

Each group's keys are written under its prefix (gen_ai.usage.input_tokens); None values are skipped. Effect spells the keys in camelCase and converts them; the Python keys are already the attribute names.

Types

TypeDefinitionDescription
WellKnownOperationNametype WellKnownOperationName = Literal['chat', 'embeddings', 'text_completion']
WellKnownOutputTypetype WellKnownOutputType = Literal['text', 'json', 'image', 'speech']
WellKnownProviderNametype WellKnownProviderName = Literal['anthropic', 'aws.bedrock', 'azure.ai.inference', 'azure.ai.openai', 'cohere', 'deepseek', 'gcp.gemini', 'gcp.gen_ai', 'gcp.vertex_ai', 'groq', 'ibm.watsonx.ai', 'mistral_ai', 'moonshot_ai', 'openai', 'perplexity', 'x_ai']
SpanTransformertype SpanTransformer = Callable[[ProviderOptions, Sequence[Any]], None]

Called with the options a language model sent its provider (span is the request's span) and the response's parts (Effect's SpanTransformer), to write attributes onto the span.

Classes

Functions

add_span_attributes

add_span_attributes(span, prefix, attributes) -> None

Each value of attributes that is not None as "{prefix}.{key}" (Effect's addSpanAttributes).

ParameterTypeDescription
spanSpan
prefixstr
attributesMapping[str, object]
def add_span_attributes(span: Span, prefix: str, attributes: Mapping[str, object]) -> None:
    """Each value of ``attributes`` that is not ``None`` as
    ``"{prefix}.{key}"`` (Effect's ``addSpanAttributes``)."""
    for key, value in attributes.items():
        if value is not None:
            span.attribute(f"{prefix}.{key}", _attribute_value(value))

add_gen_ai_annotations

add_gen_ai_annotations(span, options) -> None

Write each group of options under gen_ai.<group>.

ParameterTypeDescription
spanSpan
optionsGenAIAttributeOptions
def add_gen_ai_annotations(span: Span, options: GenAIAttributeOptions) -> None:
    """Write each group of ``options`` under ``gen_ai.<group>``."""
    for group in _GROUPS:
        attributes = options.get(group)
        if attributes is not None:
            add_span_attributes(span, f"gen_ai.{group}", attributes)