操作场景
本文介绍如何将 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:创建应用
通过控制台创建
1. 登录 Agent 可观测控制台。
2. 单击应用接入,选择接入类型并填写应用名称。使用方案一时选择
Agent,使用方案二时选择 Langfuse。3. 创建完成后,在应用右侧单击编辑,复制 Trace 日志主题 ID,用于后续配置。
通过 API 创建
参数 | 是否必填 | 说明 |
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 mainimport ("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 = provideratrace.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 mainimport ("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.Directorproxy.Director = func(r *http.Request) {originalDirector(r)r.URL.Path = "/v1/traces"r.URL.RawPath = ""r.Host = target.Hostr.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 的处理。