> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-zh.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 条件追踪

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

[`tracing_context`](https://reference.langchain.com/python/langsmith/run_helpers/tracing_context) 上下文管理器（Python）和 [`tracingEnabled`](https://reference.langchain.com/javascript/classes/langsmith.run_trees.RunTree.html#tracingenabled) 选项（TypeScript）允许你在运行时覆盖全局追踪设置，而无需重构代码或更改环境变量。

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

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

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

<Tabs>
  <Tab title="Python" icon="brand-python">
    ## 追踪上下文的工作原理

    当你使用 [`tracing_context`](https://reference.langchain.com/python/langsmith/run_helpers/tracing_context) 上下文管理器时，它会覆盖其作用域内执行的代码的全局追踪配置。这意味着你可以在全局保持自动追踪启用的同时，选择性地控制特定函数调用的追踪行为。

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

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

    ## 为特定调用禁用追踪

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

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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")  # 不被追踪
    ```

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

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

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

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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")  # 根据客户端设置决定是否追踪
    ```

    ## 按请求自定义追踪配置

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

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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`](https://reference.langchain.com/python/langsmith/run_helpers/tracing_context) 上下文管理器可与自动追踪配合使用。你可以全局保持 `LANGSMITH_TRACING=true` 设置，并使用 `tracing_context` 来覆盖特定请求的设置：

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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 Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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](/langsmith/agent-server) 中，默认启用追踪。使用 [工厂函数](/langsmith/graph-rebuild) 时，你可以用 `tracing_context` 包装生成的图，以控制每次执行的追踪。这对于添加自定义元数据、完全禁用追踪或根据已认证用户自定义追踪非常有用。

    ### 为图禁用追踪

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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
    ```

    ### 按用户追踪

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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 Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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")
    ```
  </Tab>

  <Tab title="TypeScript" icon="brand-javascript">
    ## tracingEnabled 的工作原理

    在 TypeScript 中，你可以在调用 [`traceable()`](https://reference.langchain.com/python/langsmith/run_helpers/traceable) 时使用 [`tracingEnabled`](https://reference.langchain.com/javascript/classes/langsmith.run_trees.RunTree.html#tracingenabled) 参数来控制每个函数的追踪。这允许你在函数级别选择性地启用或禁用追踪。

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

    1. **`tracingEnabled` 参数**：最高优先级（传递给 [`traceable()`](https://reference.langchain.com/python/langsmith/run_helpers/traceable) 配置）。
    2. **环境变量**：最低优先级（`LANGSMITH_TRACING`）。

    ## 为特定调用禁用追踪

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

    ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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 中，最高效的方法是预先创建函数的追踪和非追踪变体，然后根据业务逻辑在运行时选择它们。这避免了每次请求都创建新的追踪包装器的性能开销，同时仍能提供对追踪发生时间的细粒度控制。例如：

    ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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`](https://reference.langchain.com/javascript/classes/langsmith.run_trees.RunTree.html#tracingenabled) 选项可与自动追踪无缝配合使用。你可以全局保持 `LANGSMITH_TRACING=true` 设置，并使用 `tracingEnabled` 来覆盖特定函数的设置。

    ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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"
    ```
  </Tab>
</Tabs>

## 与采样的比较

条件追踪和 [采样](/langsmith/sample-traces) 服务于不同的目的：

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

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

## 相关链接

* [无需环境变量进行追踪](/langsmith/trace-without-env-vars)：以编程方式配置追踪，而不是使用环境变量。
* [设置追踪采样率](/langsmith/sample-traces)：概率性采样追踪以减少数据量
* [屏蔽输入和输出](/langsmith/mask-inputs-outputs)：在追踪中隐藏敏感数据，而不是完全禁用追踪。
* [向追踪添加元数据和标签](/langsmith/add-metadata-tags)：使用自定义属性对追踪进行分类和过滤。

***

<div className="source-links">
  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\langsmith\conditional-tracing.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>

  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>
</div>