通过 OpenTelemetry 实现 LLM 可观测性

OpenTelemetry 是 CNCF 项目，提供一套规范、API 和库，定义了从应用收集分布式 trace 和指标的标准方式。

Litefuse 可以作为 OpenTelemetry Backend 工作，在 /api/public/otel（OTLP）端点接收 trace。除了 Langfuse SDK 和 原生集成 之外，这个 OpenTelemetry 端点旨在提升与 SDK 与原生集成之外的框架、库和语言的兼容性。常用的 OpenTelemetry 库包括 OpenLLMetry 和 OpenLIT，它们将 Litefuse tracing 的语言支持扩展到 Java 与 Go，并覆盖 AutoGen、Semantic Kernel 等框架。

由于 GenAI trace 属性的 Semantic Conventions 仍在演进中，Litefuse 会将收到的 OTel trace 映射到 Litefuse 数据模型，并支持 OTel GenAI 生态中常见的额外属性（属性映射）。如果某个集成未按预期工作或没有解析到正确的属性，请 提交 issue。

同时使用其他基于 OTEL 的工具？ 如果你将 Litefuse 与其他基于 OpenTelemetry 的工具一起使用，可能会出现冲突。配置指引见 将 Litefuse 与已有的 OpenTelemetry 设置一起使用。

接入选项

OpenTelemetry 原生 Langfuse SDK v3

最快开始使用 Litefuse 进行 tracing 的方式是新的 OTEL 原生 Langfuse SDK v3。该 SDK 是官方 OpenTelemetry 客户端之上的薄层，会自动将发出的 span 转换为丰富的 Litefuse observation（spans、generations、events 以及 其他 observation 类型），并为 token 用量、成本追踪、prompt 关联和打分等 LLM 专属能力提供一等公民式的辅助函数。

由于它运行在共享的 OpenTelemetry 上下文中，其他被 OTEL 插桩的库产生的 span 也可以被导出到 Litefuse。默认情况下，Litefuse 会聚焦于与 LLM 相关的 span（Langfuse SDK 的 span、带 gen_ai.* 属性的 span，以及已知的 LLM instrumentor）。如需导出全部内容，可以按 SDK 进阶文档 中的说明使用宽松的自定义过滤器。

可以从这里的 Python 实现专属指南开始：/docs/observability/sdk/overview。

OpenTelemetry 端点

Litefuse 可以在 /api/public/otel（OTLP）端点接收 trace。

如果你使用的是基于 OpenTelemetry SDK 导出 trace 的 Collector，可以使用以下配置：

OTEL_EXPORTER_OTLP_ENDPOINT="https://litefuse.cloud/api/public/otel"
# OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:3000/api/public/otel" # 🏠 Local deployment (>= v3.22.0)
 
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ${AUTH_STRING}"

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://litefuse.cloud/api/public/otel/v1/traces"

请注意，Litefuse 目前支持基于 HTTP 的 OTLP，包括 HTTP/JSON 和 HTTP/protobuf。gRPC 暂不支持。

通过 OpenTelemetry SDK 自定义

你可以使用 OpenTelemetry SDK，按上述配置直接将 trace 导出到 Litefuse。这样 Litefuse 的语言支持就被扩展到 Langfuse SDK（Python 与 JS/TS）之外的语言。

使用 OpenTelemetry GenAI 插桩库

任何兼容 OpenTelemetry 的插桩都可以用来将 trace 导出到 Litefuse。可以参考下面这些常用插桩 SDK 的端到端示例来快速开始：

库

• OpenLIT
• OpenLLMetry
• Arize
• MLflow

基于 OpenTelemetry 的框架集成

• Hugging Face smolagents
• CrewAI
• AutoGen
• Semantic Kernel
• Pydantic AI
• Spring AI
• LlamaIndex
• LlamaIndex Workflows

从 OpenTelemetry Collector 导出

如果你运行了 OpenTelemetry Collector，可以使用以下配置将 trace 导出到 Litefuse：

receivers:
  otlp:
    protocols:
    grpc:
      endpoint: 0.0.0.0:4317
    http:
      endpoint: 0.0.0.0:4318
 
processors:
  batch:
  memory_limiter:
    # 80% of maximum memory up to 2G
    limit_mib: 1500
    # 25% of limit up to 2G
    spike_limit_mib: 512
    check_interval: 5s
 
exporters:
  otlphttp/litefuse:
    endpoint: "https://litefuse.cloud/api/public/otel"
    headers:
      Authorization: "Basic ${AUTH_STRING}" # Previously encoded API keys
 
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp/litefuse]

过滤发送到 Litefuse 的 span

如果你希望有选择地将 OTel span 发送给 Litefuse，可以使用 OTel Collector 的 filterprocessor。 它允许你基于属性、span 名称等条件来过滤 span。 由于过滤是在 span 级别生效的，你可能会得到不完整的 trace，所以在使用复杂过滤规则时要谨慎。 Litefuse 还要求 root span 必须发送到我们的后端，以便正确创建 trace。

下面的配置只会转发 gen_ai.system 属性等于 openai 的 span：

receivers:
  otlp:
    protocols:
    grpc:
      endpoint: 0.0.0.0:4317
    http:
      endpoint: 0.0.0.0:4318
 
processors:
  filter/openaisystem:
    error_mode: ignore
    traces:
      span:
        - 'attributes["gen_ai.system"] != "openai"'
 
exporters:
  otlphttp/litefuse:
    endpoint: "https://litefuse.cloud/api/public/otel"
    headers:
      Authorization: "Basic ${AUTH_STRING}" # Previously encoded API keys
 
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [filter/openaisystem]
      exporters: [otlphttp/litefuse]

属性映射

Litefuse 致力于兼容 OpenTelemetry GenAI 语义约定 并支持主流的 LLM 插桩框架。

此外，Litefuse 在 langfuse.* 命名空间下使用一些属性，把 OpenTelemetry span 属性直接映射到 Litefuse 数据模型。这些专属属性始终优先于通用的 OpenTelemetry 约定，推荐所有手动插桩应用的用户使用。

Litefuse 区分 trace 级别属性和 observation 级别属性。

• Trace 级别属性 表示整次交互的共享上下文。如果 Litefuse 在某个 span 上检测到这些属性，会把它们当作整个 trace 的属性。
• Observation 级别属性 描述 trace 内的单个步骤。Litefuse 会将它们保留在 observation 级别。

元数据映射的工作方式

OpenTelemetry span 可以携带任意属性。Litefuse 会根据它们的命名方式以不同方式处理这些属性：

将 trace 属性传播到所有 span

当你使用 OpenTelemetry 插桩将 trace 发送到 Litefuse 时，某些 trace 级别的属性应该被传播到 trace 内的 所有 span，以便在 Litefuse 中进行准确的聚合与过滤。这些属性包括：

• userId（通过 langfuse.user.id 或 user.id）
• sessionId（通过 langfuse.session.id 或 session.id）
• metadata（通过 langfuse.trace.metadata.* 设置顶级 metadata key）
• version（通过 langfuse.version）
• release（通过 langfuse.release）
• tags（通过 langfuse.trace.tags）

在未来某个版本中，Litefuse 的聚合查询和过滤将作用于单个 observation（span），而不仅是 trace 级别。这意味着如果你想按这些属性进行过滤或聚合，它们必须出现在 trace 中的每一个 span 上。我们强烈建议现在就实现这种传播，以便兼容未来版本的 Litefuse。

使用 OpenTelemetry Baggage 进行传播

推荐的做法是使用 OpenTelemetry Baggage 配合 BaggageSpanProcessor 把这些属性传播到所有 span。Baggage 是 OpenTelemetry 内置的上下文传播机制，可以自动把指定的键值对复制到 trace 上下文中的所有 span。

要实现这个模式：

1. 在 trace 起始处把目标属性设置为 baggage 条目
2. 在当前激活的 span 上设置这些属性
3. 在你的 OpenTelemetry 设置中配置 BaggageSpanProcessor，自动把 baggage 条目复制到 span 属性上
4. 处理器会确保 trace 上下文中所有下游 span 都收到这些属性

实现细节和代码示例可以参考 Python 与 JavaScript 的 OpenTelemetry 文档。

备选：使用 Langfuse SDK

如果你使用 Langfuse SDK 配合 OpenTelemetry 集成，可以使用便捷方法 propagate_attributes()（Python）或 propagateAttributes()（TypeScript），它们会自动处理属性传播。这些方法提供了更简洁的接口，是使用 Langfuse SDK 时的推荐做法。

Trace 级别属性

这些属性会被应用到 Litefuse 中的 trace 记录上。它们可以设置在 trace 中的任意 span 上。

with tracer.start_as_current_span("Langfuse Attributes") as span:
    span.set_attribute("langfuse.trace.metadata.user_name", "user-123")

Observation 级别属性

这些属性会应用到 trace 中的单个 observation（span）上（数据模型）。

with tracer.start_as_current_span("Langfuse Attributes") as span:
    span.set_attribute("langfuse.observation.metadata.user_name", "user-123")

故障排查

• 如果在自托管 Litefuse 时遇到 4xx 错误，请将部署升级到最新版本。OpenTelemetry 端点最早在 Litefuse v3.22.0 引入，之后又有显著改进。
• Litefuse 支持基于 HTTP 的 OTLP，包括 HTTP/JSON 和 HTTP/protobuf。gRPC 暂不支持。