loongsuite-util-genai

What it is and what it does

loongsuite-util-genai is an extension of OpenTelemetry's GenAI semantic conventions, designed to capture observability data from large language model calls, agent orchestration, vector retrieval, tool execution, and related AI workflows. It provides a unified telemetry handler that maps these operations into standardized OpenTelemetry Spans with semantic attributes, optional structured events, and configurable message content capture. The package imports as opentelemetry.util.genai but is distributed as loongsuite-util-genai to avoid conflicts with the upstream community package.

The handler supports LLM chat/completion calls with multimodal message handling, agent creation and invocation, embedding operations, tool execution with skill metadata, retrieval and reranking, memory operations, application entry points with session/user ID propagation via Baggage, and ReAct iteration tracking. Message content (prompts, responses) is not captured by default to protect sensitive data and reduce trace volume; it must be explicitly enabled via environment variables. The package integrates with OpenTelemetry's standard export pipeline and is designed to work with auto-instrumentation frameworks or direct SDK initialization.

Use it for:

• Trace LLM API calls end-to-end with standardized span attributes, token counts, and model metadata for debugging and performance monitoring.
• Monitor agent orchestration workflows by capturing agent creation, invocation, tool execution, and memory operations as linked spans.
• Observe vector retrieval and reranking operations within RAG pipelines to identify latency and quality bottlenecks.
• Correlate user sessions and requests across distributed AI services using Baggage-based span coloring at application entry points.
• Audit LLM inputs and outputs by enabling structured event capture with full message content when compliance or debugging requires it.
• Integrate GenAI telemetry into existing OpenTelemetry observability stacks (Jaeger, Datadog, Honeycomb, etc.) without custom instrumentation.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Extends OpenTelemetry's GenAI semantic conventions to capture telemetry from large language models, agents, tool calls, vector retrieval, and related operations, mapping them to standardized Span attributes, optional message content, and GenAI events.

Yes, if you are building AI applications with OpenTelemetry and need standardized tracing for LLMs, agents, and retrieval workflows. The package is actively maintained, has low install friction, and is Apache-2.0 licensed. Install via LoongSuite's recommended instrumentation chain to avoid dependency conflicts with the upstream package. Be aware that message content capture requires explicit environment variable configuration and that the extended semantic model for some scenarios (Agent, ReAct, memory) may still be evolving.

Install

loongsuite-util-genai on PyPI

pip install loongsuite-util-genai

uv add loongsuite-util-genai

poetry add loongsuite-util-genai

Installing loongsuite-util-genai

Before you install

Low install friction with a pure-Python wheel and three lightweight OpenTelemetry runtime dependencies. Active maintenance as of 2026-08-13 with recent releases; part of a larger LoongSuite monorepo. Note: mixing this package with the upstream opentelemetry-util-genai can cause dependency resolution conflicts—prefer installing via LoongSuite's recommended instrumentation chain.

License in practice

Licensed under Apache-2.0 (permissive), allowing commercial and private use with minimal restrictions. No license-related barriers to adoption.

Quickstart

pip install loongsuite-util-genai

from opentelemetry import trace
from opentelemetry.util.genai.extended_handler import get_extended_telemetry_handler
from opentelemetry.util.genai.types import InputMessage, LLMInvocation, OutputMessage, Text

handler = get_extended_telemetry_handler()
invocation = LLMInvocation(
    provider="openai",
    request_model="gpt-4o-mini",
    input_messages=[InputMessage(role="user", parts=[Text(content="Hello")])],
)
with handler.llm(invocation) as inv:
    inv.output_messages = [OutputMessage(role="assistant", parts=[Text(content="Hi")], finish_reason="stop")]
    inv.input_tokens = 10
    inv.output_tokens = 20

Requires Python 3.9 or later. Global TracerProvider, MeterProvider, and LoggerProvider must be initialized before calling get_extended_telemetry_handler()—either via OpenTelemetry auto-instrumentation or explicit SDK setup. Message content capture requires environment variables OTEL_SEMCONV_STABILITY_OPT_IN and OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT to be configured.

Verify before relying

• Whether the package's extended semantic model for Agent, retrieval, memory, and ReAct scenarios is stable or still experimental.
• Performance overhead of message content capture modes (SPAN_ONLY, EVENT_ONLY, SPAN_AND_EVENT) at scale.
• Compatibility guarantees with upstream opentelemetry-util-genai API changes.
• Whether external storage and URI replacement for multimodal messages is production-ready.

Package facts

Evidence: loongsuite_util_genai-0.5.0-py3-none-any.whl

Tags

More Monitoring packages

Further reading