loongsuite-util-genai 0.5.0

本仓库与 opentelemetry-util-genai 的关系

本模块在设计与演进上作为 OpenTelemetry 生态中 GenAI Util（包名 opentelemetry-util-genai）的扩展：在兼容上游 API 与约定方向的前提下，由 LoongSuite 先行落地 更丰富、更完整的 GenAI 语义与属性模型，并在合入社区前于本仓库迭代。覆盖范围包括 Agent、检索、记忆、入口与 ReAct 等场景。

发行名称：交付时，本模块以 loongsuite-util-genai 发布至制品库（如 PyPI）；安装后提供的仍是 opentelemetry.util.genai 包及 ExtendedTelemetryHandler 等扩展接口，与从本 monorepo 构建安装的产物一致。

定位与能力

面向大语言模型、Agent、工具调用与向量检索等场景，将调用语义映射为 OpenTelemetry 遥测数据：统一的 Span 命名与属性、可选的消息内容捕获、可选的 GenAI 事件，以及与 LoongSuite / OpenTelemetry 导出链路的对接。

本实现在上游 GenAI Util 能力之上提供扩展，主要包括：

• llm：聊天/补全类调用；支持多模态消息的**外置存储与 URI 替换**（见第 4 节），减轻 Trace 体积。

• invoke_agent / create_agent：Agent 调用与创建。

• embedding：向量嵌入。

• execute_tool：工具/函数执行。 - 当工具执行对应某个 skill 的加载动作时，可额外写入 gen_ai.skill.* 语义属性。

• retrieval / rerank：检索与重排序。

• memory：记忆读写等操作。

• entry：应用入口；可将 session_id / user_id 写入 Baggage，配合 BaggageSpanProcessor 做整条链路的染色。

• react_step：ReAct 单轮迭代标识。

相关操作对齐 OpenTelemetry GenAI 语义约定 并与上游 LLM 采集 API 衔接：ExtendedTelemetryHandler 在基础 TelemetryHandler 之上扩展（详见上节与语义约定文档）。

安装注意事项

• 与上游包并存：loongsuite-util-genai 与社区发行 opentelemetry-util-genai 混装或重复指定时容易引发依赖解析冲突。建议优先采用 LoongSuite 发行链路，通过 loongsuite-instrument 及根目录 README.md 中的安装说明完成探针与本模块的组合安装与启动。

• monorepo 本地安装探针时：若 instrumentor 是从 本仓库本地路径 安装的（例如 pip install ./instrumentation-loongsuite/...），则 必须 先从 同一 monorepo 源码树 安装本模块（例如 pip install -e ./util/opentelemetry-util-genai）。否则安装 instrumentor 时，解析结果可能回落为**上游** GenAI Util，与本地探针版本不一致，导致扩展能力或行为不符合预期。

2.1. 使用 LoongSuite / OpenTelemetry Instrumentation 接入

前提：已通过 loongsuite-instrument、opentelemetry-instrument 或等价方式在进程启动时配置全局 Provider 与导出器，应用代码不自行构造 TracerProvider / MeterProvider。

安装

pip install loongsuite-util-genai

从本 monorepo 本地安装时（与发行包等价源码树）:

pip install -e ./util/opentelemetry-util-genai

Framework 探针若已声明对本包的依赖，会随探针一并安装；单独手写 GenAI Span 时仍需安装 loongsuite-util-genai（或上述本地路径）。

LLM 示例代码

依赖 Instrumentation 把全局 Tracer/Meter/Logger Provider 配好；业务侧只需通过 OpenTelemetry API 确认 Provider 已就绪（可选），再拿 扩展 Handler 包一层 LLM 调用即可。

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

# 可选：确认当前进程已由 Instrumentation 设置 TracerProvider（未设置时多为 NoOp）
_ = trace.get_tracer_provider()

handler = get_extended_telemetry_handler()

invocation = LLMInvocation(
    provider="openai",
    request_model="gpt-4o-mini",
    input_messages=[
        InputMessage(role="user", parts=[Text(content="用一句话解释 OpenTelemetry。")]),
    ],
)
with handler.llm(invocation) as inv:
    # 此处调用真实模型 API…
    inv.output_messages = [
        OutputMessage(
            role="assistant",
            parts=[Text(content="OpenTelemetry 是用于可观测性的开放标准与实现。")],
            finish_reason="stop",
        )
    ]
    inv.input_tokens = 10
    inv.output_tokens = 20

未向 get_extended_telemetry_handler() 传入 tracer_provider / logger_provider 时，Handler 内部的 get_tracer / get_logger 会使用**当前全局** Provider（由 Instrumentation 注入）。

环境变量

若需在 Trace/Event 中采集**模型输入、输出等正文**（或完整消息结构），必须**按 **2.3 节 设置相关变量；否则默认不采集消息正文。

进程启动（Instrumentation）

使用本仓库推荐的启动方式时，请参阅 仓库根目录 的 README.md``（例如通过 ``loongsuite-instrument 指定导出器与 service_name 后再执行 python your_app.py）。

若尚未安装 LoongSuite Instrumentation，请按根目录 README.md 的 Quick start / INSTALL 安装 opentelemetry-distro、对应框架的 instrumentor，以及本 util 包，再使用包装命令启动进程。

2.2. 使用 OpenTelemetry SDK 直接接入

前提：不依赖进程级 auto-instrument，由应用入口显式注册 TracerProvider、MeterProvider、LoggerProvider 及导出器。

安装

pip install loongsuite-util-genai opentelemetry-sdk

按需增加导出器，例如 opentelemetry-exporter-otlp。

LLM 示例代码

在获取 Handler 之前**初始化全局 Provider；创建 Handler 时把 **TracerProvider 与 LoggerProvider 传入（便于 Span 与 GenAI Event；Metrics 使用 metrics.set_meter_provider 设置全局后，Handler 内 get_meter(..., meter_provider=None) 会使用全局 MeterProvider）。

from opentelemetry import metrics, trace, _logs
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor, ConsoleLogRecordExporter
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import ConsoleMetricExporter, PeriodicExportingMetricReader
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
from opentelemetry.util.genai.extended_handler import get_extended_telemetry_handler
from opentelemetry.util.genai.types import InputMessage, LLMInvocation, OutputMessage, Text

# 以下使用 Console*Exporter 便于本地调试。生产环境可将 SpanExporter / MetricExporter /
# LogRecordExporter 替换为 OTLP、gRPC、Jaeger 等实现，以上报到 Collector 或兼容后端。
trace.set_tracer_provider(TracerProvider())
trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(ConsoleSpanExporter())
)

metrics.set_meter_provider(
    MeterProvider(
        metric_readers=[PeriodicExportingMetricReader(ConsoleMetricExporter())]
    )
)

logger_provider = LoggerProvider()
logger_provider.add_log_record_processor(
    BatchLogRecordProcessor(ConsoleLogRecordExporter())
)
_logs.set_logger_provider(logger_provider)

handler = get_extended_telemetry_handler(
    tracer_provider=trace.get_tracer_provider(),
    logger_provider=logger_provider,
)

with handler.llm() as inv:
    inv.provider = "openai"
    inv.request_model = "gpt-4o-mini"
    inv.input_messages = [
        InputMessage(role="user", parts=[Text(content="你好")]),
    ]
    inv.output_messages = [
        OutputMessage(
            role="assistant",
            parts=[Text(content="你好！")],
            finish_reason="stop",
        )
    ]

环境变量

若需在 Trace/Event 中采集**输入输出正文**，必须**按 **2.3 节 配置。

进程启动（直接运行）

python your_app.py

无需 opentelemetry-instrument / loongsuite-instrument，除非你还在同进程使用其他 auto-instrumentation。

2.3. 环境变量

本节是 GenAI 遥测是否**完整、可用**的关键：默认策略不将提示词、模型回复等消息正文写入遥测（NO_CONTENT），以降低敏感数据暴露与导出体积。若需要在可观测平台中排查或审计「输入与输出」正文，或以 Event 形式查看结构化消息，则必须以本节为准配置 OTEL_SEMCONV_STABILITY_OPT_IN、OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT，并在选用 Event 路径时配合 OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT 及 LoggerProvider（参见 2.2 节）。

OTEL_SEMCONV_STABILITY_OPT_IN

取值 gen_ai_latest_experimental 时启用 GenAI 实验性语义约定，便于与文档及导出器行为一致；未设置时部分属性可能不可用或与约定不一致。

OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT（消息内容落点）

• NO_CONTENT：不采集消息正文（默认）。

• SPAN_ONLY：正文写入 Span 属性（如 JSON 字符串）。

• EVENT_ONLY：正文写入结构化 Event（需 LoggerProvider 及下方事件开关）。

• SPAN_AND_EVENT：Span 与 Event 同时携带内容。

OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT（GenAI Event）

• true：在 EVENT_ONLY / SPAN_AND_EVENT 且已配置 LoggerProvider 时，按约定发出例如 gen_ai.client.*.operation.details 等事件。

• false：不发出（默认）。

配置示例

export OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_AND_EVENT
export OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT=true

显式生命周期

推荐采用上下文管理器（with handler.llm(...) 等）。需与既有控制流对接时，可使用 start_* / stop_* / fail_*，例如 Agent 调用：

from opentelemetry.util.genai.extended_types import InvokeAgentInvocation
from opentelemetry.util.genai.types import Error

inv = InvokeAgentInvocation(provider="openai")
inv.request_model = "gpt-4"
inv.agent_name = "A"
handler.start_invoke_agent(inv)
try:
    inv.input_messages = [...]
    inv.output_messages = [...]
    handler.stop_invoke_agent(inv)
except Exception as e:
    handler.fail_invoke_agent(inv, Error(type=type(e), message=str(e)))

错误处理

在 with 块内抛出异常时，Handler 会将 Span 标为错误并记录类型等信息；你也可以在业务层捕获后自行决定如何 re-raise。

try:
    with handler.invoke_agent() as inv:
        inv.provider = "openai"
        inv.request_model = "gpt-4"
        raise RuntimeError("downstream failed")
except RuntimeError:
    pass  # Span 上已反映错误；若需自定义 error 字段可改用 start/fail API

进程退出与上传收尾

from opentelemetry.util.genai.extended_handler import ExtendedTelemetryHandler

ExtendedTelemetryHandler.shutdown()

可在 Web 框架或运行时的 shutdown 回调中调用，以便收尾异步上传等逻辑（以实现代码为准）。