mcpField
O
otel-livekit-style

otel-livekit-style

github.com/superloglabs开发13380 次安装21 周前更新
代码仓库

关于 otel-livekit-style

为 LiveKit 语音 Agent 使用 OpenTelemetry 进行监测的风格指南，规定会话生命周期、有限操作和 LLM 调用的跨度与指标约定。

主要功能

  1. 01定义完整会话的跨度生命周期
  2. 02为有限会话操作添加监测
  3. 03记录会话计数和时长
  4. 04追踪 LLM 调用及令牌数

适用场景

  1. 01为 LiveKit 语音会话添加监测
  2. 02记录会话启动和持续时间指标
  3. 03追踪语音 Agent 中的 LLM 操作

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/superloglabs/skills --skill otel-livekit-style

安装后在 Claude Code 中输入/otel-livekit-style确认已加载。

详细介绍

OTel LiveKit 风格

LiveKit 会话生命周期从 entrypoint(ctx) 开始，并在 ctx.add_shutdown_callback(on_shutdown) 中结束清理。

整个会话的 Span

由于操作跨越了框架回调边界，voice.session span 在 on_shutdown 中结束是可以的。在子任务注册并启动期间，应让它保持活跃。

async def entrypoint(ctx: agents.JobContext) -> None:
    await ctx.connect()
    started_at = asyncio.get_running_loop().time()
    session_span = tracer.start_span(
        "voice.session",
        attributes={
            "tenant.id": tenant_id,
            "user.id": user_id,
            "voice.room_name": room_name,
        },
    )

    with trace.use_span(session_span, end_on_exit=False):
        voice_sessions_started.add(1, {
            "tenant.id": tenant_id,
            "voice.room_name.present": room_name != "unknown",
        })

        async def on_shutdown() -> None:
            duration_ms = int((asyncio.get_running_loop().time() - started_at) * 1000)
            session_span.set_attribute("voice.duration_ms", duration_ms)
            voice_session_duration.record(duration_ms, {
                "tenant.id": tenant_id,
                "voice.disconnect_reason": disconnect_reason,
                "outcome": "success",
            })
            session_span.end()

        ctx.add_shutdown_callback(on_shutdown)
        await _deliver_initial_greeting(...)

不要将其替换为 shutdown 内部一个很短的 voice.session.end span。

有界会话工作

有界操作仍需使用各自的装饰器。

@tracer.start_as_current_span("voice.deliver_initial_greeting")
async def _deliver_initial_greeting(...):
    ...

会话指标

同时使用：

  • 在 entrypoint 开始时记录 voice.sessions.started 计数器
  • 在 shutdown 时记录 voice.session.duration_ms 直方图

为重要的语音事件添加产品指标，例如 voice.greetings.delivered。

冒烟检查

对于最小化的 LiveKit fixture，一个合适的冒烟测试流程是导入 Agent，并执行一个很小的插桩函数，或通过本地 OTLP 端点启动一个 span／日志记录。仅检查 tracer／meter 对象非 None 是不够的。

LLM 轮次

语音 Agent 中每个 LLM 提供商／调用点都需要：

  • 在调用周围创建 span
  • 记录 token 计数器（llm.tokens.input、llm.tokens.output）
  • 添加租户／提供商／模型／用例／调用点／结果属性

不要添加 llm.cost_usd 指标；Superlog 会根据提供商／模型／token 数据集中估算成本。

span 名称应描述产品操作，而非提供商传输调用。 例如，优先使用 llm.voice_response 或 llm.generate_copy，而不是 llm.anthropic.messages.create。

attrs = {
    "tenant.id": tenant_id,
    "llm.provider": "anthropic",
    "llm.model": model,
    "llm.use_case": "voice.initial_greeting",
    "llm.call_site": "_call_mug_copy_llm",
    "outcome": "success",
}
llm_tokens_input.add(input_tokens, attrs)
llm_tokens_output.add(output_tokens, attrs)

评论

支持 Markdown