TLS 日志服务

TLSExporter 将 span 数据以 OTLP（HTTP）协议上报至火山引擎日志服务 TLS。数据按 TLS 主题组织，适合集中存储、长期留存与跨服务的链路分析。

何时使用

需要将智能体的执行链路集中存储在火山引擎日志服务 TLS；
需要长期留存与合规审计的追踪数据；
需要结合 TLS 的告警与分析能力进行观测。

接入前准备

先完成安装和模型配置，再设置以下环境变量。占位符需要替换为有权限访问的实际资源和凭证；在启动 Python 前完成配置

TLS 会接收链路数据并可能产生存储费用。建议显式指定已有追踪主题 ID；省略时会调用 TLS 获取或创建默认追踪资源。此示例使用火山引擎 TLS 端点。CLOUD_PROVIDER=byteplus 时，凭据配置可以使用 BytePlus AK/SK；端点、区域和主题仍需与目标服务匹配，不能仅凭模型使用 BytePlus 判断 TLS 已完成配置

export OBSERVABILITY_OPENTELEMETRY_TLS_ENDPOINT="https://tls-cn-beijing.volces.com:4318/v1/traces"
export OBSERVABILITY_OPENTELEMETRY_TLS_REGION="cn-beijing"
export OBSERVABILITY_OPENTELEMETRY_TLS_SERVICE_NAME="your-tls-trace-topic"

# 火山引擎凭证
export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"

使用示例

保存为 app.py，运行 python app.py。示例复用已有资源，完成一次模型调用后刷新待导出的链路数据

app.py

import asyncio

from veadk import Agent, Runner
from veadk.tracing.telemetry.exporters.tls_exporter import TLSExporter
from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer

tracer = OpentelemetryTracer(exporters=[TLSExporter()])
agent = Agent(name="trace_demo", tracers=[tracer])
runner = Runner(agent=agent, app_name="trace_demo", user_id="demo-user")
response = asyncio.run(
    runner.run("用一句话解释智能体的用途", session_id="demo-session")
)
print(response)
tracer.force_export()
print("Trace ID:", tracer.trace_id)

参数

构造参数

TLSExporter 的连接参数由 config 字段承载，类型为 TLSExporterConfig；不传时各字段自动从对应环境变量读取。

参数	类型	默认值	说明
`config`	`TLSExporterConfig`	自动从环境变量读取	TLS 连接与认证配置。
`resource_attributes`	`dict`	`{}`	附加到 span 的资源属性。
`headers`	`dict`	`{}`	TLS 认证头由连接配置生成；当前实现不会把额外自定义请求头发送到上报端点。

TLS 连接配置

config 为 TLSExporterConfig，各字段默认从 TLSConfig 及火山引擎凭证读取，环境变量如下：

配置项	环境变量	类型	默认值	说明
`endpoint`	`OBSERVABILITY_OPENTELEMETRY_TLS_ENDPOINT`	`str`	`https://tls-cn-beijing.volces.com:4318/v1/traces`	TLS OTLP 接入点（HTTP）。
`region`	`OBSERVABILITY_OPENTELEMETRY_TLS_REGION`	`str`	`cn-beijing`	TLS 服务所在地域。
`topic_id`	`OBSERVABILITY_OPENTELEMETRY_TLS_SERVICE_NAME`	`str`	未设置时自动获取追踪主题 ID	TLS 追踪主题 ID，用于组织日志数据。
`access_key`	`VOLCENGINE_ACCESS_KEY` / `BYTEPLUS_ACCESS_KEY`	`str`	读取当前凭据配置	目标 TLS 服务接受的 Access Key；BytePlus 凭据兼容映射要求 `CLOUD_PROVIDER=byteplus`
`secret_key`	`VOLCENGINE_SECRET_KEY` / `BYTEPLUS_SECRET_KEY`	`str`	读取当前凭据配置	与 Access Key 配套的 Secret Key

topic_id 未通过 OBSERVABILITY_OPENTELEMETRY_TLS_SERVICE_NAME 提供时，导出器会调用 VeTLS 自动获取追踪主题 ID，因此需要配置有效的火山引擎凭证（VOLCENGINE_ACCESS_KEY 与 VOLCENGINE_SECRET_KEY）。

也可以让 Agent 依据环境变量自动挂载 TLS 导出器，无需显式构造：

export ENABLE_TLS=true

设置 ENABLE_TLS=true 后，即便智能体未显式提供 tracers，Agent 也会自动创建 OpentelemetryTracer 并挂载 TLSExporter。

验证与排查

运行后在目标平台按本次 Trace ID 查询。模型回复成功只说明智能体完成了调用，不代表链路上传成功；找不到数据时依次检查端点和地域、凭证权限、目标资源以及进程退出前是否调用 tracer.force_export()

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

何时使用

接入前准备

使用示例

参数

构造参数

TLS 连接配置

验证与排查

​何时使用

​接入前准备

​使用示例

​参数

​构造参数

​TLS 连接配置

​验证与排查

何时使用

接入前准备

使用示例

参数

构造参数

TLS 连接配置

验证与排查