文档 / 日志级别

日志级别

Traces 可能包含大量 observations(数据模型)。你可以用 level 属性区分 observations 的重要程度,以控制 traces 的详细程度,并突出错误和警告。可用的 levels:DEBUG、DEFAULT、WARNING、ERROR。

除了级别,你还可以包含 statusMessage 以提供额外上下文。

Trace 日志级别和 statusMessage

使用 @observe() 装饰器时:

python

from langfuse import observe, get_client

@observe()
def my_function():
    langfuse = get_client()

    # ... processing logic ...
    # Update the current span with a warning level
    langfuse.update_current_span(
        level="WARNING",
        status_message="This is a warning"
    )

直接创建 spans 或 generations 时:

python

from langfuse import get_client

langfuse = get_client()

# Using context managers (recommended)
with langfuse.start_as_current_observation(as_type="span", name="my-operation") as span:
    # Set level and status message on creation
    with span.start_as_current_observation(
        name="potentially-risky-operation",
        level="WARNING",
        status_message="Operation may fail"
    ) as risky_span:
        # ... do work ...

        # Or update level and status message later
        risky_span.update(
            level="ERROR",
            status_message="Operation failed with unexpected input"
        )

# You can also update the currently active span without a direct reference
with langfuse.start_as_current_observation(as_type="span", name="another-operation"):
    # ... some processing ...
    langfuse.update_current_span(
        level="DEBUG",
        status_message="Processing intermediate results"
    )

创建 generations 时也可以设置级别:

python

langfuse = get_client()

with langfuse.start_as_current_observation(
    as_type="generation",
    name="llm-call",
    model="gpt-4o",
    level="DEFAULT"  # Default level
) as generation:
    # ... make LLM call ...

    if error_detected:
        generation.update(
            level="ERROR",
            status_message="Model returned malformed output"
        )

使用上下文管理器时:

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

await startActiveObservation("context-manager", async (span) => {
  span.update({
    input: { query: "What is the capital of France?" },
  });

  updateActiveObservation({
    level: "WARNING",
    statusMessage: "This is a warning",
  });
});

使用 observe 包装器时:

import { observe, updateActiveObservation } from "@langfuse/tracing";

// An existing function
async function fetchData(source: string) {
  updateActiveObservation({
    level: "WARNING",
    statusMessage: "This is a warning",
  });

  // ... logic to fetch data
  return { data: `some data from ${source}` };
}

// Wrap the function to trace it
const tracedFetchData = observe(fetchData, {
  name: "observe-wrapper",
});

const result = await tracedFetchData("API");

手动创建 observations 时:

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

const span = startObservation("manual-observation", {
  input: { query: "What is the capital of France?" },
});

span.update({
  level: "WARNING",
  statusMessage: "This is a warning",
});

span.update({ output: "Paris" }).end();

更多细节参见 JS/TS SDK 文档。

使用 OpenAI SDK 集成时,level 和 statusMessage 会根据 OpenAI API 响应自动设置。参见示例。

使用 LangChain 集成时,level 和 statusMessage 会为 LangChain 流水线中的每一步自动设置。

按日志级别过滤 Trace

查看单个 trace 时,你可以按日志级别过滤 observations。