帮你快速理解、总结文档立即下载

接入 trpc-agent-go 数据

最近更新时间:2026-11-18 14:40:31
我的收藏

操作场景

本文介绍如何将 trpc-agent-go 应用生成的 Trace 数据接入 Agent 可观测(Agent Observability,AgentObs)。完成接入后,您可以在 AgentObs 中查看模型调用、工具调用及其耗时、输入输出和 Token 用量。
本文提供以下两种方案,请根据应用使用的数据语义选择。
对比项
方案一:Agent 类型
方案二:Langfuse 类型
上报方式
通过 OTLP/HTTP 直接上报 CLS
通过框架的 telemetry/langfuse 转换后,经本地代理上报 CLS
数据语义
保留框架生成的 OpenTelemetry GenAI 属性(gen_ai.*)
转换为 Langfuse 属性(langfuse.observation.*)
适用场景
使用框架原生 OpenTelemetry 埋点
已依赖 Langfuse 数据模型或语义
协议适配
无需本地代理
本地代理改写上报路径并添加 topic_id 请求头
说明:
两种方案需分别创建对应接入类型的应用,并使用各自的 Trace 日志主题 ID。以下代码为接入片段,需要集成到已有且可正常运行的 Agent 项目,不包含模型、工具及 Agent 的完整业务实现。

前提条件

已准备 SecretId 和 SecretKey,且密钥具备向目标 Trace 日志主题写入数据的权限。获取方式请参见 API 密钥管理。
已安装 Go 1.21或更高版本,并在项目中引入 trpc.group/trpc-go/trpc-agent-go v1.11.2或更高版本。本文以 v1.11.2为基准,其他版本请核对相关接口及 Go 版本要求。
Agent 应用已完成模型接入,并可正常执行模型和工具调用。
应用运行环境能够访问 Trace 日志主题所在地域的 CLS 接入点。本文代码使用公网域名 地域.cls.tencentcs.com。

步骤1:创建应用

通过控制台创建

2. 单击应用接入,选择接入类型并填写应用名称。使用方案一时选择 Agent,使用方案二时选择 Langfuse。
3. 创建完成后,在应用右侧单击编辑,复制 Trace 日志主题 ID,用于后续配置。

通过 API 创建

如需自动化创建应用,可调用 CreateAgentApplication。接口请求域名为 cls.tencentcloudapi.com,主要参数如下。
参数
是否必填
说明
ApplicationName
是
应用名称,不能为空,不能包含竖线字符,最多64个字符
AccessType
是
接入类型,取值为 Agent 或 Langfuse
LogsetId
否
需要复用的日志集 ID;未指定时由系统创建
以下为业务请求参数示例,不包含云 API 公共参数及签名。请通过官方 SDK 或 API Explorer 生成完整请求。
{
"ApplicationName": "trpc-agent-demo",
"AccessType": "Langfuse",
"LogsetId": "<日志集ID>"
}
在接口返回的 Response.LogTopics 中,找到 Flag 为 trace 的记录,取其 TopicId。返回结构示例如下。
{
"Response": {
"ApplicationId": "<应用ID>",
"LogTopics": [
{
"Flag": "trace",
"TopicId": "<Trace日志主题ID>"
}
],
"RequestId": "<请求ID>"
}
}
注意:
请通过应用接入或 CreateAgentApplication 创建应用。单独调用 CreateLogset 或 CreateTopic 创建日志资源,不等同于创建 AgentObs 应用。

步骤2:配置上报

配置环境变量

两种方案均使用以下环境变量。本文代码通过环境变量读取密钥,请勿将真实密钥写入代码或提交到代码仓库。
环境变量
是否必填
说明
TENCENTCLOUD_SECRET_ID
是
腾讯云 SecretId
TENCENTCLOUD_SECRET_KEY
是
腾讯云 SecretKey
CLS_REGION
否
Trace 日志主题所在地域,示例代码默认使用 ap-guangzhou
CLS_TOPIC_ID
方案一必填
Agent 类型应用的 Trace 日志主题 ID
CLS_LANGFUSE_TOPIC_ID
方案二必填
Langfuse 类型应用的 Trace 日志主题 ID
在启动应用的同一终端中配置环境变量。以下以 macOS 或 Linux 为例,请替换占位符。
export TENCENTCLOUD_SECRET_ID='<SecretId>'
export TENCENTCLOUD_SECRET_KEY='<SecretKey>'
export CLS_REGION='ap-guangzhou'

# 方案一使用此变量。
export CLS_TOPIC_ID='<Agent类型应用的Trace日志主题ID>'

# 方案二使用此变量。
export CLS_LANGFUSE_TOPIC_ID='<Langfuse类型应用的Trace日志主题ID>'

方案一:通过 OTLP/HTTP 直接上报

将 OTLP/HTTP Exporter 注册到框架使用的 TracerProvider。该方案不执行 Langfuse 语义转换,使用 gen_ai.* 等框架原生属性。
在已有 Agent 项目中添加以下文件。若项目不使用 main 包,请相应调整包名。
package main

import (
"context"
"encoding/base64"
"fmt"
"os"

otlptracehttp "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
sdktrace "go.opentelemetry.io/otel/sdk/trace"
atrace "trpc.group/trpc-go/trpc-agent-go/telemetry/trace"
)

func startCLSExporter(ctx context.Context, topicID string) (func(context.Context) error, error) {
secretID := os.Getenv("TENCENTCLOUD_SECRET_ID")
secretKey := os.Getenv("TENCENTCLOUD_SECRET_KEY")
if topicID == "" || secretID == "" || secretKey == "" {
return nil, fmt.Errorf("missing CLS topic ID or credentials")
}
region := os.Getenv("CLS_REGION")
if region == "" {
region = "ap-guangzhou"
}
auth := base64.StdEncoding.EncodeToString([]byte(secretID + ":" + secretKey))
exporter, err := otlptracehttp.New(ctx,
otlptracehttp.WithEndpoint(region+".cls.tencentcs.com"),
otlptracehttp.WithURLPath("/v1/traces"),
otlptracehttp.WithHeaders(map[string]string{
"Authorization": "Basic " + auth,
"topic_id": topicID,
}),
)
if err != nil {
return nil, err
}
processor := sdktrace.NewBatchSpanProcessor(exporter)
if provider, ok := atrace.TracerProvider.(*sdktrace.TracerProvider); ok && provider != nil {
provider.RegisterSpanProcessor(processor)
return provider.Shutdown, nil
}
provider := sdktrace.NewTracerProvider(
sdktrace.WithSampler(sdktrace.AlwaysSample()),
sdktrace.WithSpanProcessor(processor),
)
atrace.TracerProvider = provider
atrace.Tracer = provider.Tracer("trpc-agent-demo")
return provider.Shutdown, nil
}
在已有 main 函数中、发起 Agent 请求前调用以下初始化片段,并在该函数所在文件的导入列表中补充 context、log、os 和 time。
ctx := context.Background()
clean, err := startCLSExporter(ctx, os.Getenv("CLS_TOPIC_ID"))
if err != nil {
log.Printf("CLS 上报初始化失败: %v", err)
return
}
defer func() {
shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := clean(shutdownCtx); err != nil {
log.Printf("CLS 上报关闭失败: %v", err)
}
}()

// 在此继续执行已有的 Agent 业务逻辑。
新建 Provider 时,示例使用全量采样,适用于接入验证;生产环境请按业务需要调整采样策略。复用已有 Provider 时,保留其原有采样配置。返回的关闭函数会关闭整个 Provider,请在全部 Agent 请求结束后调用。

方案二:通过 Langfuse 转换和本地代理上报

框架的 telemetry/langfuse 包负责将原生埋点转换为 Langfuse 语义。主要转换关系如下,具体字段以所用框架版本和实际请求为准。
转换项
说明
Span 类型
invoke_agent、chat、execute_tool、workflow 分别转换为 agent、generation、tool、chain,写入 langfuse.observation.type
输入输出
将 gen_ai.input.messages 和 gen_ai.output.messages 转换为 langfuse.observation.input 和 langfuse.observation.output
Token 用量
转换为 langfuse.observation.usage_details,具体分桶取决于模型提供方
会话和用户
将 baggage 中的 langfuse.session.id 和 langfuse.user.id 写入 Span
根 Span 用量
转换链路会移除根 Span 的 Usage 属性,避免重复聚合
对于使用 /api/public/otel/v1/traces 路径的 langfuse.Start 实现,不能仅将 Host 替换为 CLS 域名。本文通过本地代理,将路径改写为 /v1/traces,并补充 topic_id 请求头。
trpc-agent-go 埋点
→ telemetry/langfuse 语义转换
→ 本地回环代理:改写路径、添加 topic_id、透传 Authorization
→ https://<地域>.cls.tencentcs.com/v1/traces
在已有 Agent 项目中添加以下文件。
package main

import (
"context"
"fmt"
"log"
"net"
"net/http"
"net/http/httputil"
"net/url"
"os"
"time"

"trpc.group/trpc-go/trpc-agent-go/telemetry/langfuse"
)

func startLangfuseCLSExporter(ctx context.Context, topicID string) (func(context.Context) error, error) {
secretID := os.Getenv("TENCENTCLOUD_SECRET_ID")
secretKey := os.Getenv("TENCENTCLOUD_SECRET_KEY")
if topicID == "" || secretID == "" || secretKey == "" {
return nil, fmt.Errorf("missing CLS topic ID or credentials")
}
region := os.Getenv("CLS_REGION")
if region == "" {
region = "ap-guangzhou"
}
addr, server, err := startLangfuseCLSProxy(region, topicID)
if err != nil {
return nil, err
}
clean, err := langfuse.Start(ctx,
langfuse.WithHost(addr),
langfuse.WithPublicKey(secretID),
langfuse.WithSecretKey(secretKey),
langfuse.WithInsecure(), // 仅应用到本地回环连接;代理到 CLS 使用 HTTPS。
)
if err != nil {
_ = server.Close()
return nil, err
}
return func(shutdownCtx context.Context) error {
// 先完成 Trace 导出,再关闭代理。
exportErr := clean(shutdownCtx)
proxyErr := server.Shutdown(shutdownCtx)
if exportErr != nil {
return exportErr
}
return proxyErr
}, nil
}

func startLangfuseCLSProxy(region, topicID string) (string, *http.Server, error) {
target, err := url.Parse("https://" + region + ".cls.tencentcs.com")
if err != nil {
return "", nil, err
}
proxy := httputil.NewSingleHostReverseProxy(target)
originalDirector := proxy.Director
proxy.Director = func(r *http.Request) {
originalDirector(r)
r.URL.Path = "/v1/traces"
r.URL.RawPath = ""
r.Host = target.Host
r.Header.Set("topic_id", topicID)
// Authorization 由 exporter 设置,此处透传。
}
listener, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
return "", nil, err
}
server := &http.Server{Handler: proxy, ReadHeaderTimeout: 5 * time.Second}
go func() {
if err := server.Serve(listener); err != nil && err != http.ErrServerClosed {
log.Printf("CLS 本地代理退出: %v", err)
}
}()
return listener.Addr().String(), server, nil
}
在已有 main 函数中、发起 Agent 请求前调用以下初始化片段,并在该函数所在文件的导入列表中补充 context、log、os 和 time。若只使用本方案,无需执行方案一的初始化代码。
ctx := context.Background()
clean, err := startLangfuseCLSExporter(ctx, os.Getenv("CLS_LANGFUSE_TOPIC_ID"))
if err != nil {
log.Printf("CLS Langfuse 上报初始化失败: %v", err)
return
}
defer func() {
shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := clean(shutdownCtx); err != nil {
log.Printf("CLS Langfuse 上报关闭失败: %v", err)
}
}()

// 在此继续执行已有的 Agent 业务逻辑。
本方案使用 SecretId 和 SecretKey 作为 Langfuse Exporter 的 Public Key 和 Secret Key,使其生成 CLS 所需的 Basic 鉴权。代理仅监听 127.0.0.1,请勿将其开放到公网或作为通用代理使用。

步骤3:运行应用并验证

按项目原有方式启动 Agent,发起一次包含模型或工具调用的请求,并在退出前完成 Trace 导出。
例如,若您的项目已实现 -prompt 命令行参数,可执行以下命令。该命令是原示例项目的调用方式,不是任意 trpc-agent-go 项目都支持的通用命令。
go run . -prompt "帮我用计算器算一下 123 + 456"

在控制台查看调用链

1. 登录 Agent 可观测控制台,进入 步骤1 创建的应用。
2. 打开调用链页面,选择包含测试请求的时间范围。
3. 打开对应 Trace,检查 Agent、模型和工具 Span 的父子关系、耗时及输入输出。
4. 根据模型实际返回的数据,检查 Token 用量。您也可以在仪表盘中查看请求数、Token 消耗等指标。

在日志主题中检索

在日志服务控制台进入检索分析,选择对应的 Trace 日志主题及时间范围,先使用 * 检索原始记录。若日志主题具有以下字段并已配置相应分析索引,可执行以下 SQL。
* | SELECT traceID, name, duration ORDER BY __TIMESTAMP__ DESC LIMIT 10
不同接入类型的数据结构可能不同。若提示字段不存在,请根据原始记录中的字段及索引配置调整语句。

数据结构示例

以下内容根据接入素材中的记录整理,仅用于说明两种方案的数据差异,不代表所有版本或模型均产生相同属性。
Trace
├─ invoke_agent demo-agent gen_ai.* 属性
├─ chat demo-model 输入输出、模型及用量属性
├─ execute_tool calculator 工具名称、参数及结果属性
└─ chat demo-model
Trace
├─ invoke_agent langfuse.observation.type=agent
├─ chat langfuse.observation.type=generation
└─ execute_tool langfuse.observation.type=tool
输入输出、会话和用量字段是否存在,取决于框架版本、上下文传递及模型返回值。请以实际检索结果为准。

常见问题

应用运行正常,但检索不到 Trace 数据

请依次检查:
1. 是否实际触发了模型或工具调用,且对应 Span 已结束。
2. 是否在进程退出前调用关闭函数。批量上报是异步过程,进程提前退出可能导致最后一批数据未完成导出。
3. 是否记录了初始化、导出或关闭过程中的错误。
4. Trace 日志主题 ID、地域及访问密钥是否正确,密钥是否具备目标主题的写入权限。
5. 检索时间范围和索引配置是否正确。新建主题后,如暂未查到记录,可稍后重试,并结合上报错误排查,不能仅凭检索结果判断写入失败。

单独创建日志主题后,为什么应用列表中没有对应应用

日志主题和 AgentObs 应用不是同一资源。请通过应用接入或 CreateAgentApplication 创建应用,再使用返回的 Trace 日志主题 ID。

Langfuse 直连 CLS 时返回404

请检查请求路径。若框架请求的是 /api/public/otel/v1/traces,请按方案二配置本地代理,将上报路径改写为 /v1/traces,并添加 topic_id 请求头。框架接口及默认路径可能随版本变化,请核对所用版本。

如何同时向 Langfuse 和 CLS 上报

避免先后初始化多个会覆盖框架全局 Tracer 的组件。对于可复用 sdktrace.TracerProvider 的版本,可先初始化 Langfuse,再通过 RegisterSpanProcessor 注册 CLS Exporter,使用同一个 Provider 导出。
共用 Provider 时,两个出口接收的是同一批 Span,CLS 出口不会因此恢复转换前的原生属性。请按数据语义选择应用类型,并统一管理 Provider 的关闭时机。该方式与分别初始化本文两种方案不同,请先核对框架版本的 Provider 行为。

OTLP 上报使用什么鉴权格式

本文代码使用以下请求头,密钥从环境变量读取。
Authorization: Basic base64(SecretId + ":" + SecretKey)
topic_id: <Trace日志主题ID>
Basic 编码不等于加密,请保持到 CLS 的 HTTPS 连接。本文示例仅展示 SecretId 和 SecretKey 鉴权,不包含 STS 临时凭证 Token 的处理。

相关文档