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 on it.

Install

loongsuite-util-genai on PyPI

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.

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.

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

Package facts

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

Tags

More Monitoring packages

See also opentelemetry-util-genai · opentelemetry-instrumentation-openai-v2 · opentelemetry-instrumentation-google-genai · aliyun-semantic-conventions · openinference-instrumentation-google-genai · opentelemetry-semantic-conventions-ai · opentelemetry-instrumentation-openai-agents · microsoft-agents-a365-observability-core · opentelemetry-instrumentation-google-generativeai · openinference-instrumentation-portkey

Further reading