> ## 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 的告警与分析能力进行观测。

## 使用示例

TLS 接入通常分两步：先用 `VeTLS` 客户端创建日志项目与追踪实例，再用 `TLSExporter` 上报数据。

```python lines theme={null}
import asyncio
from os import getenv

from veadk import Agent, Runner
from veadk.integrations.ve_tls.ve_tls import VeTLS
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.demo_tools import get_city_weather
from veadk.tracing.telemetry.exporters.tls_exporter import TLSExporter, TLSExporterConfig
from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer

# 创建日志项目与追踪实例
ve_tls_client = VeTLS()
log_project_id = ve_tls_client.create_log_project("veadk_demo")

trace_instance_name = getenv("OBSERVABILITY_OPENTELEMETRY_TLS_SERVICE_NAME")
trace_instance = ve_tls_client.create_tracing_instance(
    log_project_id, trace_instance_name
)

# 用 TLSExporter 上报 Tracing 数据
tls_exporter = TLSExporter(
    config=TLSExporterConfig(
        topic_id=trace_instance.get("TraceTopicId", trace_instance_name),
    )
)
tracer = OpentelemetryTracer(exporters=[tls_exporter])

agent = Agent(tools=[get_city_weather], tracers=[tracer])

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())

asyncio.run(runner.run(messages="北京天气怎么样？", session_id="session_id_demo"))
```

不显式传入 `config` 时，`topic_id` 会在缺省情况下自动获取追踪主题 ID：

```python lines theme={null}
from veadk.tracing.telemetry.exporters.tls_exporter import TLSExporter

exporter = TLSExporter()
```

## 参数

### 构造参数

`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` | `str` | 从火山引擎凭证读取 | 火山引擎访问密钥。 |
| `secret_key` | `VOLCENGINE_SECRET_KEY` | `str` | 从火山引擎凭证读取 | 火山引擎密钥。 |

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

## 环境变量配置

```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"
```

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

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

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