实现分布式追踪

有时，你需要跨多个服务追踪一个请求。 LangSmith 开箱即用地支持分布式追踪，通过上下文传播标头（langsmith-trace，以及用于元数据/标签的可选 baggage）关联跨服务的追踪运行。客户端-服务器设置示例：

追踪从客户端开始
在服务器上继续

只接受来自受信任服务的分布式追踪标头。 langsmith-trace 和 baggage 标头会被当作受信任的追踪上下文使用。不要在直接接收不受信任的第三方或公共互联网请求的服务上添加 TracingMiddleware（或将传入请求标头作为追踪的 parent 传入）。请将分布式追踪限制在内部服务间调用，并在网关或代理处移除来自不受信任请求的这些标头。信任来自外部调用方的 baggage 会让对方影响运行记录方式。

Python 中的分布式追踪

# client.py
from langsmith.run_helpers import get_current_run_tree, traceable
import httpx

@traceable
async def my_client_function():
    headers = {}
    async with httpx.AsyncClient(base_url="...") as client:
        if run_tree := get_current_run_tree():
            # 将 langsmith-id 添加到标头
            headers.update(run_tree.to_headers())
        return await client.post("/my-route", headers=headers)

然后，服务器（或其他服务）可以通过适当处理这些标头来继续追踪。如果你使用的是 ASGI 应用 Starlette 或 FastAPI，可以通过 LangSmith 的 TracingMiddleware 连接分布式追踪。

TracingMiddleware 类是在 langsmith==0.1.133 中添加的。

使用 FastAPI 的示例：

from langsmith import traceable
from langsmith.middleware import TracingMiddleware
from fastapi import FastAPI, Request

app = FastAPI()  # 或 Flask、Django 或任何其他框架
app.add_middleware(TracingMiddleware)

@traceable
async def some_function():
    ...

@app.post("/my-route")
async def fake_route(request: Request):
    return await some_function()

或者使用 Starlette：

from starlette.applications import Starlette
from starlette.middleware import Middleware
from langsmith.middleware import TracingMiddleware

routes = ...
middleware = [
    Middleware(TracingMiddleware),
]
app = Starlette(..., middleware=middleware)

如果你使用的是其他服务器框架，也可以通过将标头传入 langsmith_extra 来“接收”分布式追踪：

# server.py
import langsmith as ls
from fastapi import FastAPI, Request

@ls.traceable
async def my_application():
    ...

app = FastAPI()  # 或 Flask、Django 或任何其他框架

@app.post("/my-route")
async def fake_route(request: Request):
    # request.headers:  {"langsmith-trace": "..."}
    # 以及位于 `baggage` 中的可选元数据/标签
    with ls.tracing_context(parent=request.headers):
        return await my_application()

上面的示例使用了 tracing_context 上下文管理器。你也可以在使用 @traceable 包装的方法的 langsmith_extra 参数中直接指定父运行上下文。

# ... 与上面相同

@app.post("/my-route")
async def fake_route(request: Request):
    # request.headers:  {"langsmith-trace": "..."}
    my_application(langsmith_extra={"parent": request.headers})

TypeScript 中的分布式追踪

TypeScript 中的分布式追踪要求 langsmith 版本为 >=0.1.31

首先，我们从客户端获取当前运行树，并将其转换为 langsmith-trace 和 baggage 标头值，然后将这些值传递给服务器：

// client.mts
import { getCurrentRunTree, traceable } from "langsmith/traceable";

const client = traceable(
    async () => {
        const runTree = getCurrentRunTree();
        return await fetch("...", {
            method: "POST",
            headers: runTree.toHeaders(),
        }).then((a) => a.text());
    },
    { name: "client" }
);

await client();

然后，服务器会将这些标头转换回运行树，并使用该运行树继续追踪。要将新创建的运行树传递给可追踪函数，我们可以使用 withRunTree 辅助函数，它会确保运行树在可追踪调用中传播。

// server.mts
import { RunTree } from "langsmith";
import { traceable, withRunTree } from "langsmith/traceable";
import express from "express";
import bodyParser from "body-parser";

    const server = traceable(
        (text: string) => `来自服务器的问候！收到“${text}”`,
        { name: "server" }
    );

    const app = express();
    app.use(bodyParser.text());

app.post("/", async (req, res) => {
    const runTree = RunTree.fromHeaders(req.headers);
    const result = await withRunTree(runTree, () => server(req.body));
    res.send(result);
});

// server.mts
import { RunTree } from "langsmith";
import { traceable, withRunTree } from "langsmith/traceable";
import { Hono } from "hono";

    const server = traceable(
        (text: string) => `来自服务器的问候！收到“${text}”`,
        { name: "server" }
    );

    const app = new Hono();

app.post("/", async (c) => {
    const body = await c.req.text();
    const runTree = RunTree.fromHeaders(c.req.raw.headers);
    const result = await withRunTree(runTree, () => server(body));
    return c.body(result);
});

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

Edit this page on GitHub or file an issue.

Tracing setup

Configuration & troubleshooting

Python 中的分布式追踪

TypeScript 中的分布式追踪

​Python 中的分布式追踪

​TypeScript 中的分布式追踪

Python 中的分布式追踪

TypeScript 中的分布式追踪