条件追踪

当全局设置了环境变量 LANGSMITH_TRACING=true 时，追踪数据会自动发送到 LangSmith。本指南将展示如何针对特定请求选择性地禁用或自定义追踪。

tracing_context 上下文管理器（Python）和 tracingEnabled 选项（TypeScript）允许你在运行时覆盖全局追踪设置，而无需重构代码或更改环境变量。

在以下情况下使用条件追踪：

• 遵守数据保留政策：某些客户可能出于合规性或隐私原因要求零数据保留。
• 处理敏感操作：对涉及个人身份信息（PII）、凭证或机密数据的操作禁用追踪。
• 实现按租户配置：根据客户将追踪路由到不同的项目或应用不同的设置。
• 控制成本：对低价值请求禁用追踪，同时保持对关键操作的可见性。
• 支持功能开关：仅在特定功能或实验性代码路径激活时启用追踪。

以下部分提供了特定语言的示例，你可以根据你的应用程序逻辑和业务需求进行调整。

Python

追踪上下文的工作原理

当你使用 tracing_context 上下文管理器时，它会覆盖其作用域内执行的代码的全局追踪配置。这意味着你可以在全局保持自动追踪启用的同时，选择性地控制特定函数调用的追踪行为。

控制优先级分为三个级别：

1. tracing_context(enabled=...)：最高优先级（用于作用域追踪控制的上下文管理器）。
2. ls.configure(enabled=...)：全局配置（设置全局追踪行为）。
3. 环境变量：最低优先级（LANGSMITH_TRACING）。

为特定调用禁用追踪

要为特定操作禁用追踪，将其包装在 enabled=False 的 tracing_context 中：

import langsmith as ls
from langsmith import traceable

# 全局设置了 LANGSMITH_TRACING=true

@traceable
def my_function(input_text: str):
    return process(input_text)

# 默认调用 - 会被追踪
result = my_function("regular data")

# 为敏感数据禁用追踪
with ls.tracing_context(enabled=False):
    result = my_function("sensitive data")  # 不被追踪

这种模式适用于你知道特定数据不应被记录的一次性情况。

基于业务逻辑启用条件追踪

你可以根据运行时条件（例如客户端设置或请求属性）动态启用或禁用追踪。

import langsmith as ls
from langsmith import traceable

@traceable
def my_function(input_text: str):
    return process(input_text)

def client_requires_zero_retention(client_id: str) -> bool:
    """
    检查客户端是否具有零保留策略。

    在生产环境中，这将查询数据库、配置服务或功能开关系统。考虑缓存结果以提高性能。
    """
    # 示例：从数据库或配置中查询
    zero_retention_clients = get_zero_retention_clients()  # 你的实现
    return client_id in zero_retention_clients

def handle_request(client_id: str, user_input: str):
    """
    根据客户端要求处理带有条件追踪的请求。
    """
    should_disable = client_requires_zero_retention(client_id)

    with ls.tracing_context(enabled=not should_disable):
        return my_function(user_input)

# 示例用法
handle_request("client-a", "some input")  # 根据客户端设置决定是否追踪

按请求自定义追踪配置

你还可以动态自定义追踪设置，例如将追踪路由到不同的项目或添加请求特定的元数据。

import langsmith as ls
from langsmith import traceable

@traceable
def my_function(input_text: str):
    return process(input_text)

def handle_request(client_id: str, user_input: str, region: str):
    """
    将追踪路由到特定于客户端的项目，并附带自定义元数据。
    """
    client_tier = get_client_tier(client_id)  # 例如："enterprise"、"standard"

    with ls.tracing_context(
        enabled=True,
        project_name=f"client-{client_id}",
        tags=["production", f"tier-{client_tier}", f"region-{region}"],
        metadata={
            "client_id": client_id,
            "region": region,
            "tier": client_tier
        }
    ):
        return my_function(user_input)

# 追踪数据将发送到 "client-abc" 项目，并带有自定义标签和元数据
handle_request("abc", "some input", "us-west")

这种模式适用于：

• 多租户应用程序：将不同客户的追踪隔离在单独的项目中
• 区域部署：按地理区域跟踪性能和行为
• 功能分支：将实验性功能的追踪路由到专用项目
• 用户细分：按用户层级、群组或 A/B 测试组分析行为

与自动追踪配合使用

tracing_context 上下文管理器可与自动追踪配合使用。你可以全局保持 LANGSMITH_TRACING=true 设置，并使用 tracing_context 来覆盖特定请求的设置：

import os
import langsmith as ls

# 全局环境变量已设置
os.environ["LANGSMITH_TRACING"] = "true"

@ls.traceable
def process_data(data: str):
    return data.upper()

# 自动追踪（遵循 LANGSMITH_TRACING）
process_data("hello")

# 覆盖全局设置 - 为此调用禁用
with ls.tracing_context(enabled=False):
    process_data("sensitive")  # 不被追踪

# 覆盖全局设置 - 使用自定义配置启用
with ls.tracing_context(
    enabled=True,
    project_name="special-project"
):
    process_data("important")  # 追踪到 "special-project"

嵌套追踪上下文

当你嵌套 tracing_context 块时，最内层的上下文具有最高优先级。

Python

import langsmith as ls

@ls.traceable
def inner_function(data: str):
    return data

@ls.traceable
def outer_function(data: str):
    # 此调用遵循内部上下文
    return inner_function(data)

# 外部上下文禁用追踪
with ls.tracing_context(enabled=False):
    # 但内部上下文重新启用它
    with ls.tracing_context(enabled=True):
        outer_function("data")  # 被追踪

当你想要在通常不被追踪的部分内临时启用追踪以进行调试时，这很有用。

在已部署的代理中自定义追踪

在 LangSmith Deployment 的 Agent Server 中，默认启用追踪。使用 工厂函数 时，你可以用 tracing_context 包装生成的图，以控制每次执行的追踪。这对于添加自定义元数据、完全禁用追踪或根据已认证用户自定义追踪非常有用。

为图禁用追踪

import contextlib
import langsmith as ls
from langgraph_sdk.runtime import ServerRuntime


@contextlib.asynccontextmanager
async def make_graph(runtime: ServerRuntime):
    graph = build_my_graph()

    # 你可以使用 tracing_context 动态启用/禁用追踪、
    # 设置元数据或标签、覆盖追踪项目等。
    with ls.tracing_context(enabled=False, metadata={"foo": "bar"}):
        yield graph

按用户追踪

import contextlib
import langsmith as ls
from langgraph_sdk.runtime import ServerRuntime

def get_project_for_user(user_id: str) -> str | None:
    ...
    return "my-project"

graph = build_my_graph()

@contextlib.asynccontextmanager
async def make_graph(runtime: ServerRuntime):
    user = runtime.user
    # 根据用户将追踪路由到不同的项目，或完全禁用追踪
    project_name = get_project_for_user(user.identity)

    if project_name is None:
        with ls.tracing_context(enabled=False):
            yield graph
    else:
        with ls.tracing_context(
            enabled=True,
            project_name=project_name,
            metadata={"user_id": user.identity, "foo": "bar"},
        ):
            yield graph

可重用的追踪包装器

创建一个装饰器来自动应用条件追踪逻辑。

Python

import functools
import langsmith as ls
from langsmith import traceable

def conditional_trace(check_function):
    """
    根据检查函数条件性追踪的装饰器。

    参数：
        check_function: 返回 True 表示应启用追踪的函数
    """
    def decorator(func):
        traced_func = traceable(func)

        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            should_trace = check_function(*args, **kwargs)
            with ls.tracing_context(enabled=should_trace):
                return traced_func(*args, **kwargs)
        return wrapper
    return decorator

# 用法
def should_trace_client(client_id: str, *args, **kwargs) -> bool:
    return not client_requires_zero_retention(client_id)

@conditional_trace(should_trace_client)
def process_request(client_id: str, data: str):
    return data.upper()

# 根据 client_id 自动应用条件追踪
process_request("client-a", "some data")

TypeScript

tracingEnabled 的工作原理

在 TypeScript 中，你可以在调用 traceable() 时使用 tracingEnabled 参数来控制每个函数的追踪。这允许你在函数级别选择性地启用或禁用追踪。

一个两级系统，其中追踪按函数控制：

1. tracingEnabled 参数：最高优先级（传递给 traceable() 配置）。
2. 环境变量：最低优先级（LANGSMITH_TRACING）。

为特定调用禁用追踪

要为特定操作禁用追踪，创建一个带有 tracingEnabled: false 的可追踪函数版本：

import { traceable } from "langsmith/traceable";

const myFunction = traceable(
    (inputText: string) => {
        return process(inputText);
    },
    { name: "my_function" }
);

// 默认调用 - 会被追踪
await myFunction("regular data");

// 为敏感数据禁用追踪
const myFunctionNoTrace = traceable(
    (inputText: string) => {
        return process(inputText);
    },
    { name: "my_function", tracingEnabled: false }
);

await myFunctionNoTrace("sensitive data");  // 不被追踪

这种模式适用于你知道特定数据不应被记录的一次性情况。

基于业务逻辑启用条件追踪

在许多应用程序中，你需要根据运行时条件（例如客户端隐私要求、法规遵从性或功能开关）动态控制追踪。

在 TypeScript 中，最高效的方法是预先创建函数的追踪和非追踪变体，然后根据业务逻辑在运行时选择它们。这避免了每次请求都创建新的追踪包装器的性能开销，同时仍能提供对追踪发生时间的细粒度控制。例如：

import { traceable } from "langsmith/traceable";

// 一次性定义核心逻辑
function processText(inputText: string): string {
    // 你的实际处理逻辑
    return inputText.toUpperCase();
}

// 预先创建追踪和非追踪变体
const myFunction = traceable(processText, { name: "my_function" });
const myFunctionNoTrace = traceable(processText, {
    name: "my_function",
    tracingEnabled: false
});

function clientRequiresZeroRetention(clientId: string): boolean {
    /**
     * 检查客户端是否具有零保留策略。
     *
     * 在生产环境中，这将查询数据库、配置服务或功能开关系统。考虑缓存结果以提高性能。
     */
    const zeroRetentionClients = getZeroRetentionClients();  // 你的实现
    return zeroRetentionClients.includes(clientId);
}

async function handleRequest(clientId: string, userInput: string) {
    /**
     * 根据客户端要求处理带有条件追踪的请求。
     * 高效地选择预先创建的追踪或非追踪变体。
     */
    const shouldDisable = clientRequiresZeroRetention(clientId);

    // 选择适当的预先创建的变体
    const fn = shouldDisable ? myFunctionNoTrace : myFunction;
    return await fn(userInput);
}

// 示例用法
await handleRequest("client-a", "some input");  // 根据客户端设置决定是否追踪

与自动追踪配合使用

tracingEnabled 选项可与自动追踪无缝配合使用。你可以全局保持 LANGSMITH_TRACING=true 设置，并使用 tracingEnabled 来覆盖特定函数的设置。

import { traceable } from "langsmith/traceable";

// 通过环境全局启用追踪
process.env.LANGSMITH_TRACING = "true";

const processData = traceable(
    (data: string) => {
        return data.toUpperCase();
    },
    { name: "process_data" }
);

// 自动追踪（遵循 LANGSMITH_TRACING）
await processData("hello");

// 覆盖全局设置 - 为此调用禁用
const processDataNoTrace = traceable(
    (data: string) => {
        return data.toUpperCase();
    },
    { name: "process_data", tracingEnabled: false }
);

await processDataNoTrace("sensitive");  // 不被追踪

// 覆盖全局设置 - 使用自定义配置启用
const processDataCustom = traceable(
    (data: string) => {
        return data.toUpperCase();
    },
    {
        name: "process_data",
        project_name: "special-project",
        tracingEnabled: true
    }
);

await processDataCustom("important");  // 追踪到 "special-project"

与采样的比较

条件追踪和 采样 服务于不同的目的：

特性	条件追踪	采样
控制	确定性（显式启用/禁用）	概率性（随机采样）
用例	业务逻辑、合规性、按请求决策	成本优化、高流量可观测性
可预测性	对特定请求保证行为	流量的统计表示
配置	运行时代码逻辑	环境变量或客户端配置

你可以结合两种方法以实现细粒度控制。

相关链接

• 无需环境变量进行追踪：以编程方式配置追踪，而不是使用环境变量。
• 设置追踪采样率：概率性采样追踪以减少数据量
• 屏蔽输入和输出：在追踪中隐藏敏感数据，而不是完全禁用追踪。
• 向追踪添加元数据和标签：使用自定义属性对追踪进行分类和过滤。

---

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.