truefoundry-tracing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Routing note: For ambiguous user intents, use the shared clarification templates in references/intent-clarification.md.

路由提示：如果遇到歧义的用户意图，请使用 references/intent-clarification.md 中的通用澄清模板。

Tracing

链路追踪

Add OpenTelemetry-based tracing and observability to applications using TrueFoundry's tracing platform (powered by Traceloop SDK). Creates tracing projects, installs dependencies, and instruments code to capture LLM calls, workflows, and custom spans.

使用TrueFoundry的追踪平台（基于Traceloop SDK驱动）为应用添加基于OpenTelemetry的链路追踪和可观测能力。支持创建追踪项目、安装依赖、对代码埋点，以捕获LLM调用、工作流和自定义span。

When to Use

适用场景

Set up tracing projects, install Traceloop SDK, and instrument Python or TypeScript applications for LLM call tracing and observability on TrueFoundry.

</objective> <instructions>

需要在TrueFoundry上搭建追踪项目、安装Traceloop SDK、对Python或TypeScript应用进行埋点，以实现LLM调用追踪和可观测的场景。

</objective> <instructions>

Step 1: Preflight

步骤1：前置检查

Run the

status

skill first to verify

TFY_BASE_URL

and

TFY_API_KEY

are set and valid.

When using direct API, set

TFY_API_SH

to the full path of this skill's

scripts/tfy-api.sh

. See

references/tfy-api-setup.md

for paths per agent.

运行

status

skill首先验证

TFY_BASE_URL

和

TFY_API_KEY

已设置且有效。

使用直接API时，请将

TFY_API_SH

设置为该skill的

scripts/tfy-api.sh

文件的完整路径。各agent对应的路径可查看

references/tfy-api-setup.md

。

Step 2: Tracing Project Setup

步骤2：追踪项目设置

Ask the user: "Do you already have a tracing project FQN, or should I create one?"

询问用户："你是否已经有追踪项目的FQN，还是需要我新建一个？"

List Existing Projects

列出现有项目

Via Tool Call

通过工具调用

tfy_tracing_list_projects()

tfy_tracing_list_projects()

Via Direct API

通过直接API

bash

TFY_API_SH=~/.claude/skills/truefoundry-tracing/scripts/tfy-api.sh

bash

TFY_API_SH=~/.claude/skills/truefoundry-tracing/scripts/tfy-api.sh

List tracing projects

列出所有追踪项目

$TFY_API_SH GET /api/ml/v1/tracing-projects

undefined

$TFY_API_SH GET /api/ml/v1/tracing-projects

undefined

Create a New Project

创建新项目

Ask for a project name, then create:

询问项目名称后执行创建：

Via Tool Call

通过工具调用

tfy_tracing_create_project(name="my-tracing-project")

tfy_tracing_create_project(name="my-tracing-project")

Via Direct API

通过直接API

bash

undefined

bash

undefined

Create tracing project

创建追踪项目

$TFY_API_SH POST /api/ml/v1/tracing-projects '{"name": "my-tracing-project"}'


Save the returned project `id` for the next step.

$TFY_API_SH POST /api/ml/v1/tracing-projects '{"name": "my-tracing-project"}'


保存返回的项目`id`供下一步使用。

Create an Application Under the Project

在项目下创建应用

Each tracing project can have multiple applications (e.g., "chatbot", "rag-pipeline").

每个追踪项目可包含多个应用（例如"chatbot"、"rag-pipeline"）。

Via Tool Call

通过工具调用

tfy_tracing_create_application(project_id="PROJECT_ID", name="my-app")

tfy_tracing_create_application(project_id="PROJECT_ID", name="my-app")

Via Direct API

通过直接API

bash

undefined

bash

undefined

Create application under project

在项目下创建应用

$TFY_API_SH POST /api/ml/v1/tracing-projects/PROJECT_ID/applications '{"name": "my-app"}'


> **Fallback**: If any of these API endpoints return 404, the tracing API may have changed. Direct the user to create the tracing project via the TrueFoundry UI at `$TFY_BASE_URL` → Tracing section, then return here with the project FQN.

$TFY_API_SH POST /api/ml/v1/tracing-projects/PROJECT_ID/applications '{"name": "my-app"}'


> **降级方案**：如果上述任意API接口返回404，说明追踪API可能已变更。引导用户通过`$TFY_BASE_URL`→追踪模块的TrueFoundry UI创建追踪项目，拿到项目FQN后再回到当前流程。

Step 3: Detect Application Type

步骤3：检测应用类型

Scan the project to determine the language and LLM libraries in use:

Python — look for

requirements.txt

pyproject.toml

setup.py

Pipfile

Check for LLM libraries:

openai

anthropic

langchain

llama-index

litellm

cohere

bedrock

vertexai

transformers

TypeScript/JavaScript — look for
```
package.json
```
- Check for LLM libraries:
```
openai
```
  ,
```
@anthropic-ai/sdk
```
  ,
```
langchain
```
  ,
```
@langchain/core
```

Report what was detected to the user before proceeding.

扫描项目判断使用的编程语言和LLM库：

Python — 查找

requirements.txt

、

pyproject.toml

、

setup.py

、

Pipfile

文件

检查使用的LLM库：

openai

、

anthropic

、

langchain

、

llama-index

、

litellm

、

cohere

、

bedrock

、

vertexai

、

transformers

TypeScript/JavaScript — 查找
```
package.json
```
文件
- 检查使用的LLM库：
```
openai
```
  、
```
@anthropic-ai/sdk
```
  、
```
langchain
```
  、
```
@langchain/core
```

继续下一步前，先将检测结果告知用户。

Step 4: Install Dependencies

步骤4：安装依赖

Python

bash

pip install traceloop-sdk

Also add

traceloop-sdk

requirements.txt

or the appropriate dependency file.

bash

pip install traceloop-sdk

同时将

traceloop-sdk

添加到

requirements.txt

或对应的依赖文件中。

TypeScript/JavaScript

bash

npm install @traceloop/node-server-sdk

Also add to

package.json

dependencies.

bash

npm install @traceloop/node-server-sdk

同时添加到

package.json

的依赖中。

Step 5: Instrument the Application

步骤5：应用埋点

CRITICAL:

Traceloop.init()

MUST be called at the TOP of the entry point, BEFORE any LLM library imports. This is required for auto-instrumentation to work.

重要提示：

Traceloop.init()

必须在入口文件的最顶部调用，早于所有LLM库的导入。这是自动埋点生效的必要条件。

Python Instrumentation

Python埋点

Add this to the very top of the entry point file (e.g.,

main.py

app.py

python

undefined

将以下代码添加到入口文件（例如

main.py

、

app.py

）的最顶部：

python

undefined

--- Traceloop init MUST be before any LLM imports ---

--- Traceloop init 必须放在所有LLM导入之前 ---

from traceloop.sdk import Traceloop

Traceloop.init( app_name="<APP_NAME>", api_endpoint=f"<TFY_BASE_URL>/api/otel", headers={ "Authorization": f"Bearer <TFY_API_KEY>", "X-TFY-TRACING-PROJECT-FQN": "<TRACING_PROJECT_FQN>", }, disable_batch=False, )

from traceloop.sdk import Traceloop

--- Now import LLM libraries ---

--- 现在导入LLM库 ---

from openai import OpenAI

from anthropic import Anthropic

etc.

其他库


Replace placeholders:
- `<APP_NAME>` — the application name (e.g., "my-chatbot")
- `<TFY_BASE_URL>` — from environment or `.env`
- `<TFY_API_KEY>` — from environment or `.env`
- `<TRACING_PROJECT_FQN>` — the tracing project FQN from Step 2

**Best practice**: Read `TFY_BASE_URL` and `TFY_API_KEY` from environment variables:

```python
import os
from traceloop.sdk import Traceloop

Traceloop.init(
    app_name="<APP_NAME>",
    api_endpoint=f"{os.environ['TFY_BASE_URL']}/api/otel",
    headers={
        "Authorization": f"Bearer {os.environ['TFY_API_KEY']}",
        "X-TFY-TRACING-PROJECT-FQN": "<TRACING_PROJECT_FQN>",
    },
    disable_batch=False,
)


替换占位符：
- `<APP_NAME>` — 应用名称（例如"my-chatbot"）
- `<TFY_BASE_URL>` — 来自环境变量或`.env`文件
- `<TFY_API_KEY>` — 来自环境变量或`.env`文件
- `<TRACING_PROJECT_FQN>` — 步骤2中获取的追踪项目FQN

**最佳实践**：从环境变量读取`TFY_BASE_URL`和`TFY_API_KEY`：

```python
import os
from traceloop.sdk import Traceloop

Traceloop.init(
    app_name="<APP_NAME>",
    api_endpoint=f"{os.environ['TFY_BASE_URL']}/api/otel",
    headers={
        "Authorization": f"Bearer {os.environ['TFY_API_KEY']}",
        "X-TFY-TRACING-PROJECT-FQN": "<TRACING_PROJECT_FQN>",
    },
    disable_batch=False,
)

TypeScript/JavaScript Instrumentation

TypeScript/JavaScript埋点

Add this to the very top of the entry point file (e.g.,

index.ts

app.ts

typescript

// --- Traceloop init MUST be before any LLM imports ---
import * as traceloop from "@traceloop/node-server-sdk";

traceloop.initialize({
  appName: "<APP_NAME>",
  apiEndpoint: `${process.env.TFY_BASE_URL}/api/otel`,
  headers: {
    Authorization: `Bearer ${process.env.TFY_API_KEY}`,
    "X-TFY-TRACING-PROJECT-FQN": "<TRACING_PROJECT_FQN>",
  },
  disableBatch: false,
});

// --- Now import LLM libraries ---
// import OpenAI from "openai";
// etc.

将以下代码添加到入口文件（例如

index.ts

、

app.ts

）的最顶部：

typescript

// --- Traceloop init 必须放在所有LLM导入之前 ---
import * as traceloop from "@traceloop/node-server-sdk";

traceloop.initialize({
  appName: "<APP_NAME>",
  apiEndpoint: `${process.env.TFY_BASE_URL}/api/otel`,
  headers: {
    Authorization: `Bearer ${process.env.TFY_API_KEY}`,
    "X-TFY-TRACING-PROJECT-FQN": "<TRACING_PROJECT_FQN>",
  },
  disableBatch: false,
});

// --- 现在导入LLM库 ---
// import OpenAI from "openai";
// 其他库

Step 6: Optional — Add Decorators for Multi-Step Apps

步骤6：可选 — 为多步骤应用添加装饰器

For applications with multiple logical steps (agents, RAG pipelines, etc.), offer to add decorators for better trace structure:

对于包含多个逻辑步骤的应用（Agent、RAG流水线等），可以添加装饰器来优化链路结构：

Python Decorators

Python装饰器

python

from traceloop.sdk.decorators import workflow, task, agent, tool

@workflow(name="rag_pipeline")
def run_pipeline(query: str):
    context = retrieve(query)
    return generate(query, context)

@task(name="retrieve_context")
def retrieve(query: str):
    # retrieval logic
    ...

@task(name="generate_response")
def generate(query: str, context: str):
    # LLM call
    ...

@agent(name="research_agent")
def research_agent(topic: str):
    # agent logic
    ...

@tool(name="web_search")
def web_search(query: str):
    # tool logic
    ...

python

from traceloop.sdk.decorators import workflow, task, agent, tool

@workflow(name="rag_pipeline")
def run_pipeline(query: str):
    context = retrieve(query)
    return generate(query, context)

@task(name="retrieve_context")
def retrieve(query: str):
    # 检索逻辑
    ...

@task(name="generate_response")
def generate(query: str, context: str):
    # LLM调用
    ...

@agent(name="research_agent")
def research_agent(topic: str):
    # Agent逻辑
    ...

@tool(name="web_search")
def web_search(query: str):
    # 工具逻辑
    ...

TypeScript Decorators

TypeScript装饰器

typescript

import { withWorkflow, withTask, withAgent, withTool } from "@traceloop/node-server-sdk";

const runPipeline = withWorkflow({ name: "rag_pipeline" }, async (query: string) => {
  const context = await retrieve(query);
  return generate(query, context);
});

const retrieve = withTask({ name: "retrieve_context" }, async (query: string) => {
  // retrieval logic
});

const generate = withTask({ name: "generate_response" }, async (query: string, context: string) => {
  // LLM call
});

typescript

import { withWorkflow, withTask, withAgent, withTool } from "@traceloop/node-server-sdk";

const runPipeline = withWorkflow({ name: "rag_pipeline" }, async (query: string) => {
  const context = await retrieve(query);
  return generate(query, context);
});

const retrieve = withTask({ name: "retrieve_context" }, async (query: string) => {
  // 检索逻辑
});

const generate = withTask({ name: "generate_response" }, async (query: string, context: string) => {
  // LLM调用
});

Step 7: Optional — Configure Sampling for Production

步骤7：可选 — 为生产环境配置采样

For high-traffic production apps, configure sampling to reduce trace volume:

对于高流量的生产应用，可配置采样规则降低链路数据量：

Python

python

from opentelemetry.sdk.trace.sampling import ParentBased, TraceIdRatioBased

Traceloop.init(
    app_name="<APP_NAME>",
    api_endpoint=f"{os.environ['TFY_BASE_URL']}/api/otel",
    headers={
        "Authorization": f"Bearer {os.environ['TFY_API_KEY']}",
        "X-TFY-TRACING-PROJECT-FQN": "<TRACING_PROJECT_FQN>",
    },
    disable_batch=False,
    sampler=ParentBased(root=TraceIdRatioBased(0.1)),  # 10% sampling
)

python

from opentelemetry.sdk.trace.sampling import ParentBased, TraceIdRatioBased

Traceloop.init(
    app_name="<APP_NAME>",
    api_endpoint=f"{os.environ['TFY_BASE_URL']}/api/otel",
    headers={
        "Authorization": f"Bearer {os.environ['TFY_API_KEY']}",
        "X-TFY-TRACING-PROJECT-FQN": "<TRACING_PROJECT_FQN>",
    },
    disable_batch=False,
    sampler=ParentBased(root=TraceIdRatioBased(0.1)),  # 10%采样率
)

TypeScript

typescript

import { ParentBasedSampler, TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";

traceloop.initialize({
  appName: "<APP_NAME>",
  apiEndpoint: `${process.env.TFY_BASE_URL}/api/otel`,
  headers: {
    Authorization: `Bearer ${process.env.TFY_API_KEY}`,
    "X-TFY-TRACING-PROJECT-FQN": "<TRACING_PROJECT_FQN>",
  },
  disableBatch: false,
  sampler: new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(0.1) }), // 10%
});

</instructions>

<success_criteria>

typescript

import { ParentBasedSampler, TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";

traceloop.initialize({
  appName: "<APP_NAME>",
  apiEndpoint: `${process.env.TFY_BASE_URL}/api/otel`,
  headers: {
    Authorization: `Bearer ${process.env.TFY_API_KEY}`,
    "X-TFY-TRACING-PROJECT-FQN": "<TRACING_PROJECT_FQN>",
  },
  disableBatch: false,
  sampler: new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(0.1) }), // 10%采样率
});

</instructions>

<success_criteria>

Success Criteria

成功判定标准

Tracing project exists (created or pre-existing) on TrueFoundry
```
traceloop-sdk
```
(Python) or
```
@traceloop/node-server-sdk
```
(TypeScript) is installed
```
Traceloop.init()
```
is placed at the top of the entry point, BEFORE LLM imports
Auth headers include
```
Authorization
```
and
```
X-TFY-TRACING-PROJECT-FQN
```
The app runs without import errors
Traces appear in the TrueFoundry tracing dashboard after a test request

</success_criteria>

TrueFoundry上已存在追踪项目（新建或预先存在）
已安装
```
traceloop-sdk
```
（Python）或
```
@traceloop/node-server-sdk
```
（TypeScript）
```
Traceloop.init()
```
已放置在入口文件顶部，早于LLM库导入
认证头包含
```
Authorization
```
和
```
X-TFY-TRACING-PROJECT-FQN
```
应用运行无导入错误
测试请求发送后，链路数据出现在TrueFoundry追踪面板中

</success_criteria>

Composability

可组合能力

Preflight: Use
```
status
```
skill to verify TFY_BASE_URL and TFY_API_KEY
Secrets: Use
```
secrets
```
skill to store TFY_API_KEY as a secret instead of hardcoding
Deploy: After instrumenting, use
```
deploy
```
skill to deploy the traced application
Logs: Use
```
logs
```
skill to debug if traces aren't appearing

前置检查：使用
```
status
```
skill验证TFY_BASE_URL和TFY_API_KEY
密钥管理：使用
```
secrets
```
skill存储TFY_API_KEY，避免硬编码
部署：埋点完成后，使用
```
deploy
```
skill部署已接入追踪的应用
日志：如果链路数据未出现，使用
```
logs
```
skill调试

API Endpoints

API接口

See

references/api-endpoints.md

for the full Tracing API reference.

</references> <troubleshooting>

完整的追踪API参考可查看

references/api-endpoints.md

。

</references> <troubleshooting>

Error Handling

错误处理

401 Unauthorized on Trace Export

链路导出时返回401未授权

Check that TFY_API_KEY is valid and not expired.
Regenerate at $TFY_BASE_URL → Settings → API Keys.

检查TFY_API_KEY是否有效且未过期。
可在$TFY_BASE_URL → 设置 → API Keys页面重新生成。

No Traces Appearing in Dashboard

面板中无链路数据

1. Verify Traceloop.init() is called BEFORE LLM library imports — this is the #1 cause.
2. Check that api_endpoint ends with /api/otel (not /api/otel/).
3. Verify X-TFY-TRACING-PROJECT-FQN header matches the project FQN exactly.
4. Set disable_batch=True temporarily to force immediate export and check for errors.
5. Check application logs for OTLP export errors.

1. 确认Traceloop.init()调用早于LLM库导入 — 这是最常见的原因。
2. 检查api_endpoint以/api/otel结尾（不要带末尾的/）。
3. 验证X-TFY-TRACING-PROJECT-FQN头与项目FQN完全匹配。
4. 临时将disable_batch设为True强制立即导出，检查是否有报错。
5. 查看应用日志排查OTLP导出错误。

ImportError: No module named 'traceloop'

Run: pip install traceloop-sdk
Ensure you're installing in the correct virtual environment.

执行：pip install traceloop-sdk
确保你在正确的虚拟环境中执行安装。

Traces Missing LLM Call Details

链路缺失LLM调用详情

Traceloop.init() must be called BEFORE importing the LLM library.
Move the init call to the very top of your entry point file.

Traceloop.init()必须在导入LLM库之前调用。
将init调用移动到入口文件的最顶部。

High Trace Volume in Production

生产环境链路数据量过高

Add sampling — see Step 7 for ParentBased(TraceIdRatioBased) configuration.
Start with 10% sampling (0.1) and adjust based on needs.

添加采样配置 — 参考步骤7的ParentBased(TraceIdRatioBased)配置。
初始可设置10%采样率（0.1），再根据需求调整。

Tracing Project API Returns 404

追踪项目API返回404

The tracing API endpoints may differ on your TrueFoundry version.
Create the tracing project via the TrueFoundry UI instead:
$TFY_BASE_URL → Tracing → New Project
Then use the project FQN in your Traceloop.init() configuration.

</troubleshooting>

你使用的TrueFoundry版本的追踪API接口可能有差异。
改为通过TrueFoundry UI创建追踪项目：
$TFY_BASE_URL → 追踪 → 新建项目
然后将项目FQN填入Traceloop.init()配置中即可。

</troubleshooting>