> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# TLS 日志服务

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

## 何时使用

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

## 接入前准备

先完成[安装](/productions/veadk/preview/zh/get-started/installation)和[模型配置](/productions/veadk/preview/zh/components/agent/model)，再设置以下环境变量。占位符需要替换为有权限访问的实际资源和凭证；在启动 Python 前完成配置

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

```bash lines theme={null}
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`。示例复用已有资源，完成一次模型调用后刷新待导出的链路数据

```python title="app.py" lines theme={null}
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 |

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

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

```bash lines theme={null}
export ENABLE_TLS=true
```

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

## 验证与排查

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