条件追踪 - Docs by LangChain

当您全局设置了环境变量 LANGSMITH_TRACING=true 时，追踪数据会自动发送到 LangSmith。本指南将向您展示如何为特定请求选择性地禁用或自定义追踪。 tracing_context 上下文管理器（Python）和 tracingEnabled 选项（TypeScript）允许您在运行时覆盖全局追踪设置，无需重构代码或更改环境变量。当您需要以下情况时，请使用条件追踪：

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

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

Python
TypeScript

追踪上下文的工作原理

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

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

为特定调用禁用追踪

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

import langsmith as ls
from langsmith import traceable

# LANGSMITH_TRACING=true is set globally

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

# Default invocation - is traced
result = my_function("regular data")

# Disable tracing for sensitive data
with ls.tracing_context(enabled=False):
    result = my_function("sensitive data")  # not traced

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

根据业务逻辑启用条件追踪

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

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:
    """
    Check if a client has a zero-retention policy.

    In production, this would query a database, configuration service,
    or feature flag system. Consider caching results for performance.
    """
    # Example: Query from database or config
    zero_retention_clients = get_zero_retention_clients()  # Your implementation
    return client_id in zero_retention_clients

def handle_request(client_id: str, user_input: str):
    """
    Process a request with conditional tracing based on client requirements.
    """
    should_disable = client_requires_zero_retention(client_id)

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

# Example usage
handle_request("client-a", "some input")  # Traced or not based on client settings

根据请求自定义追踪配置

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

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):
    """
    Route traces to client-specific projects with custom metadata.
    """
    client_tier = get_client_tier(client_id)  # e.g., "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)

# Traces go to "client-abc" project with custom tags and metadata
handle_request("abc", "some input", "us-west")

此模式适用于：

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

与自动追踪配合使用

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

import os
import langsmith as ls

# Global environment variable set
os.environ["LANGSMITH_TRACING"] = "true"

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

# Automatically traced (respects LANGSMITH_TRACING)
process_data("hello")

# Override global setting - disable for this call
with ls.tracing_context(enabled=False):
    process_data("sensitive")  # not traced

# Override global setting - enable with custom config
with ls.tracing_context(
    enabled=True,
    project_name="special-project"
):
    process_data("important")  # Traced to "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):
    # This call respects the inner context
    return inner_function(data)

# Outer context disables tracing
with ls.tracing_context(enabled=False):
    # But inner context re-enables it
    with ls.tracing_context(enabled=True):
        outer_function("data")  # is traced

当您想在通常不追踪的部分中临时启用追踪进行调试时，这会很有用。

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

在 LangSmith 部署的 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()

    # You can use tracing_context to dynamically enable/disable tracing,
    # set metadata or tags, override the tracing project, etc.
    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
    # Route traces to a different project depending on user or disable tracing entirely
    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):
    """
    Decorator that conditionally traces based on a check function.

    Args:
        check_function: Function that returns True if tracing should be enabled
    """
    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

# Usage
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()

# Automatically applies conditional tracing based on client_id
process_request("client-a", "some data")

追踪启用的工作原理

在 TypeScript 中，您在调用 traceable() 时使用 tracingEnabled 参数来按函数控制追踪。这允许您在函数级别选择性地启用或禁用追踪。一个两级系统，其中追踪按函数控制：

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

为特定调用禁用追踪

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

import { traceable } from "langsmith/traceable";

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

// Default invocation - is traced
await myFunction("regular data");

// Disable tracing for sensitive data
const myFunctionNoTrace = traceable(
    (inputText: string) => {
        return process(inputText);
    },
    { name: "my_function", tracingEnabled: false }
);

await myFunctionNoTrace("sensitive data");  // not traced

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

根据业务逻辑启用条件追踪

在许多应用程序中，您需要根据运行时条件（如客户端隐私要求、法规合规性或功能标志）动态控制追踪。在 TypeScript 中，最有效的方法是预先创建函数的已追踪和未追踪变体，然后在运行时根据业务逻辑在它们之间进行选择。这避免了在每个请求上创建新的追踪包装器的性能开销，同时仍然提供对追踪发生时间的细粒度控制。例如：

import { traceable } from "langsmith/traceable";

// Define the core logic once
function processText(inputText: string): string {
    // Your actual processing logic
    return inputText.toUpperCase();
}

// Create traced and non-traced variants upfront
const myFunction = traceable(processText, { name: "my_function" });
const myFunctionNoTrace = traceable(processText, {
    name: "my_function",
    tracingEnabled: false
});

function clientRequiresZeroRetention(clientId: string): boolean {
    /**
     * Check if a client has a zero-retention policy.
     *
     * In production, this would query a database, configuration service,
     * or feature flag system. Consider caching results for performance.
     */
    const zeroRetentionClients = getZeroRetentionClients();  // Your implementation
    return zeroRetentionClients.includes(clientId);
}

async function handleRequest(clientId: string, userInput: string) {
    /**
     * Process a request with conditional tracing based on client requirements.
     * Efficiently selects pre-created traced or non-traced variant.
     */
    const shouldDisable = clientRequiresZeroRetention(clientId);

    // Select the appropriate pre-created variant
    const fn = shouldDisable ? myFunctionNoTrace : myFunction;
    return await fn(userInput);
}

// Example usage
await handleRequest("client-a", "some input");  // Traced or not based on client settings

与自动追踪配合使用

tracingEnabled 选项与自动追踪无缝协作。您可以保持 LANGSMITH_TRACING=true 全局设置，并使用 tracingEnabled 为特定函数覆盖设置。

import { traceable } from "langsmith/traceable";

// Global tracing enabled via environment
process.env.LANGSMITH_TRACING = "true";

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

// Automatically traced (respects LANGSMITH_TRACING)
await processData("hello");

// Override global setting - disable for this call
const processDataNoTrace = traceable(
    (data: string) => {
        return data.toUpperCase();
    },
    { name: "process_data", tracingEnabled: false }
);

await processDataNoTrace("sensitive");  // not traced

// Override global setting - enable with custom config
const processDataCustom = traceable(
    (data: string) => {
        return data.toUpperCase();
    },
    {
        name: "process_data",
        project_name: "special-project",
        tracingEnabled: true
    }
);

await processDataCustom("important");  // Traced to "special-project"

与采样的比较

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

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

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

​追踪上下文的工作原理

​为特定调用禁用追踪

​根据业务逻辑启用条件追踪

​根据请求自定义追踪配置

​与自动追踪配合使用

​嵌套追踪上下文

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

​为图禁用追踪

​按用户追踪

​可复用的追踪包装器

​追踪启用的工作原理

​为特定调用禁用追踪

​根据业务逻辑启用条件追踪

​与自动追踪配合使用

​与采样的比较

​相关内容

追踪上下文的工作原理

为特定调用禁用追踪

根据业务逻辑启用条件追踪

根据请求自定义追踪配置

与自动追踪配合使用

嵌套追踪上下文

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

为图禁用追踪

按用户追踪

可复用的追踪包装器

追踪启用的工作原理

为特定调用禁用追踪

根据业务逻辑启用条件追踪

与自动追踪配合使用

与采样的比较

相关内容