文档 / Trace ID 与分布式追踪

Trace ID 与分布式追踪

trace ID 是一个唯一标识符,在请求流经你的系统时跟随它。在分布式系统中,trace ID 让你能够关联跨多个服务的操作,并重建完整的请求生命周期。

默认情况下,Langfuse 分配随机的 32 位十六进制字符 trace ID 和 16 位十六进制字符 observation ID。

创建和访问 Trace ID

使用 create_trace_id() 生成 trace ID。如果提供了 seed,则 ID 是确定性的。使用相同的 seed 会得到相同的 ID。这对于将外部 ID 与 Langfuse traces 关联很有用。

python

from langfuse import get_client, Langfuse
langfuse = get_client()

external_request_id = "req_12345"
deterministic_trace_id = langfuse.create_trace_id(seed=external_request_id)

使用 get_current_trace_id() 获取当前 trace ID,使用 get_current_observation_id 获取当前 observation ID。

你也可以使用 observation.trace_id 和 observation.id 直接从 LangfuseSpan 或 LangfuseGeneration 对象访问 trace 和 observation ID。

python

from langfuse import get_client, Langfuse
langfuse = get_client()

with langfuse.start_as_current_observation(as_type="span", name="my-op") as current_op:
    trace_id = langfuse.get_current_trace_id()
    observation_id = langfuse.get_current_observation_id()
    print(trace_id, observation_id)

使用 createTraceId 从 seed 生成确定性的 trace ID。

import { createTraceId, startObservation } from "@langfuse/tracing";

const externalId = "support-ticket-54321";
const langfuseTraceId = await createTraceId(externalId);

使用 getActiveTraceId 获取活动的 trace ID,使用 getActiveSpanId 获取当前 observation ID。

import { startObservation, getActiveTraceId } from "@langfuse/tracing";

await startObservation("run", async (span) => {
  const traceId = getActiveTraceId();
  console.log(`Current trace ID: ${traceId}`);
});

设置自定义 Trace ID

在用 Langfuse SDK 包装应用代码时,你可以设置自定义 trace ID。

使用上下文管理器

python

from langfuse import get_client

langfuse = get_client()

# Use a predefined trace ID with trace_context parameter
with langfuse.start_as_current_observation(
    as_type="span",
    name="my-operation",
    trace_context={
        "trace_id": "abcdef1234567890abcdef1234567890",  # Must be 32 hex chars
        "parent_span_id": "fedcba0987654321"  # Optional, 16 hex chars
    }
) as observation:
    print(f"This observation has trace_id: {observation.trace_id}")
    # YOUR APPLICATION CODE HERE

使用装饰器

python

from langfuse import observe

@observe()
def my_operation(input):
    # YOUR APPLICATION CODE HERE
    result = call_llm(input)
    return result

process_user_request(
    input="Hello",
    langfuse_trace_id="abcdef1234567890abcdef1234567890" # Must be 32 hex chars
)

确定性 trace ID

当用预定的 traceId 启动新 trace 时,你还必须为父 observation 提供一个任意的父 spanId。父 span ID 的值无关紧要,只要它是有效的 16 位十六进制字符串即可,因为该 span 实际上并不存在于 trace 中,而仅用于所创建 observation 的 trace ID 继承。

你可以使用 createTraceId 从 seed 字符串创建有效的确定性 trace ID。这对于将 Langfuse traces 与外部系统的 ID(如支持工单 ID)关联很有用。

typescript

import { createTraceId, startObservation } from "@langfuse/tracing";

const externalId = "support-ticket-54321";

// Generate a valid, deterministic traceId from the external ID
const langfuseTraceId = await createTraceId(externalId);

// You can now start a new trace with this ID
const rootSpan = startObservation(
  "process-ticket",
  {},
  {
    parentSpanContext: {
      traceId: langfuseTraceId,
      spanId: "0123456789abcdef", // A valid 16 hexchar string; value is irrelevant as parent span does not exist but only used for inheritance
      traceFlags: 1, // mark trace as sampled
    },
  }
);

// Later, you can regenerate the same traceId to score or retrieve the trace
const scoringTraceId = await createTraceId(externalId);
// scoringTraceId will be the same as langfuseTraceId

设置 parentSpanContext 会使创建的 span 脱离活动的 span 上下文,因为它不再从上下文中的当前活动 span 继承。

在 Langfuse SDK 埋点文档中了解更多。