本章节介绍日志服务应用市场提供的大模型观测日志应用 TLS LLM 可观测。

概述

TLS LLM 是一个以 OpenTelemetry 为核心的 Python 和 Node.js LLM 链路追踪（Tracing）SDK，旨在为大模型应用提供零侵入的全链路可观测性。

支持的 API 与调用方式如下：

类别	说明
API 类型	Chat Completions Completions Responses Embeddings Structured Outputs
调用模式	同步调用、异步调用、流式输出（Streaming）、工具调用（Function、Tool Calling）
客户端类型	OpenAI、AzureOpenAI AsyncOpenAI、AsyncAzureOpenAI

核心能力

一键接入 OpenAI 及 OpenAI 兼容生态

TLS LLM 提供对 OpenAI 官方 SDK 的 Drop-in 自动插桩，将 from openai import OpenAI 替换为 from tls_llm_observer.openai import OpenAI，无需修改任何业务调用代码，即可自动捕获 LLM 调用的完整语义信息。

由于采用 OpenAI 兼容协议，SDK 支持所有提供 OpenAI 兼容接口的大模型服务，只需通过base_url指向对应端点即可，包括但不限于如下模型：

服务提供方	支持的模型
火山引擎方舟（Ark）	Doubao 系列、DeepSeek、通义千问等托管模型。火山引擎方舟支持的模型详情请参考火山引擎方舟模型列表。示例：base_url="https://ark.cn-beijing.volces.com/api/v3"
DeepSeek	DeepSeek-V3、DeepSeek-R1模型。示例：base_url="https://api.deepseek.com/v1"
其他 OpenAI 兼容服务	通义千问、智谱 AI、月之暗面等第三方模型平台 One API、New API 等 API 网关 Ollama/vLLM/LM Studio 等本地推理框架

自动采集的 GenAI 语义信息

自动记录模型调用的输入消息、输出内容、Token 消耗（输入、输出、Cache Read、Reasoning）、模型名称、Finish reason、首 Token 延迟（TTFT）、工具调用参数与结果、错误类型与原因等，覆盖大模型应用的性能分析、错误追踪与成本优化全场景。

同时支持手动埋点和装饰器（@trace），满足自定义业务链路追踪需求。

适用场景

通过接入 TLS LLM 可观测日志应用，自动在日志服务创建 TLS LLM 专用 Trace 日志主题，生成可视化图表并展示会话、Trace、Token 与工具调用数据，实现链路追踪和可观测性。可用于如下场景：

可观测性	说明
性能分析	模型调用延迟分布 Tool 执行时间排行 Token 消耗趋势
错误追踪	查看完整的调用链路定位出错的环节分析错误原因
成本优化	识别高消耗的对话优化 Prompt 减少 Token 选择更经济的模型

前提条件

类别	说明
软件限制	部署 TLS LLM 的服务器需已安装 NPM、Node.js 22 及以后版本。
地域限制	部署 TLS LLM 的服务器与日志服务为同一地域（Region），确保网络连通。
鉴权方式	根据不同的鉴权方式，获取用户 Access Key ID、Secret Access Key 或 APIKey。 AK/SK：火山引擎账号的 AccessKey ID、AccessKey Secret。在火山引擎控制台密钥管理页面获取。推荐使用 IAM 用户密钥，请确认该用户具备相关的操作权限，详情可参考IAM 概述。支持自动创建日志服务资源（Project/App/Topic），并自动生成日志主题 ID。 API Key：请求火山日志服务的重要凭证，仅用于 Log、Metric、Trace 的数据上报。严格收敛权限、不支持自动创建日志服务资源。适合多机房与权限管控严格场景。说明 API Key 为邀测功能，若有相关业务需求，可联系客户经理开通白名单。

一接入 TLS LLM 日志应用

登录日志服务控制台。

在顶部导航栏中，选择日志服务所在的地域。

在左侧导航栏中，选择 AgentLoop > AI观测。

在 AI 观测页面，单击接入 AI 观测。

在接入 AI 观测页面，创建应用。

单击 TLS LLM 图标，选中 TLS LLM 应用。

配置接入应用参数，然后单击创建应用。

参数	说明
Region	接入日志应用数据存放的地域。
日志项目	选择存放日志应用数据的日志项目。说明日志应用创建成功后，将会在该日志项目中，自动创建携带TLSLLM标签的日志主题，用于存放 trace 数据。该日志主题相关信息如下：日志主题名称：应用名称_trace 分区数量：2 日志存储时长：标准存储 90 天索引：自动配置键值索引。
应用名称	输入 TLS LLM 日志应用的名称。长度为3-64个字符。只能包含中文、小写字母、数字、下划线_和连字符-。不能以连字符-和下划线_开头/结尾。不能tls_、tos_以及部分预留字段开头。
描述	日志应用描述信息。长度限制为0-128个字符。

创建应用后，执行下一步获取使用指引，并接入日志应用。

二接入 TLS LLM 应用数据

获取接入 TLS LLM 应用数据的使用指引。

进入接入配置页面。

接入日志应用时获取
接入日志应用后获取
在 AgentLoop 中创建 TLS LLM 日志应用时，可根据界面提示获取对应的使用指引。
参考一接入 TLS LLM 日志应用，接入 TLS LLM 日志应用。
在接入 AI 观测页面的接入配置中，配置如下信息，获取使用指引。
登录日志服务控制台。
在顶部导航栏中，选择日志服务所在的地域。
在左侧导航栏中，选择 AgentLoop > AI观测。
在 AI 观测页面，通过如下方式进入获取使用指引页面。
单击目标日志应用操作列的接入配置图标。
单击目标日志应用名称，单击接入管理。

在接入配置页面，选择鉴权方式，配置如下信息，获取使用指引。

AK/SK 接入
API Key 接入
接入方式选择 AK SK 接入。
连接方式根据实际情况，选择公网或火山引擎内网。
在使用指引中，复制自动生成的使用指引。
接入方式选择 API Key 接入。
连接方式根据实际情况，选择公网或火山引擎内网。
API Key 选择已创建的 API Key。
在使用指引中，复制自动生成的使用指引。

使用指引示例（以 AK/SK 接入方式）：

公网
火山引擎内网

### Python：TLS LLM Observer（AK/SK）

安装基础 SDK：

```bash
pip install tls-llm-observer
```

如需自动追踪 OpenAI 或 OpenAI-compatible 客户端：

```bash
pip install "tls-llm-observer[openai]"
```

配置 TLS OTLP/HTTP 上报：

```bash
export TLS_TRACE_ENABLED=true
export TLS_TRACE_CAPTURE_CONTENT=true
export OTEL_SERVICE_NAME=tls-llm-python

export TLS_TRACE_OTEL_ENDPOINT=https://系统自动填充当前endpoint:4318/v1/traces

export TLS_TRACE_OTEL_TRACE_TOPIC_ID=系统自动填充 trace-topic-id
export TLS_TRACE_OTEL_REGION=系统自动填充当前地域
export TLS_TRACE_OTEL_AK=<需手动替换实际 AccessKeyID>
export TLS_TRACE_OTEL_SK=<需手动替换实际 SecretAccessKey>
```

请通过部署平台 Secret 注入 AK/SK，不要写入源码或 Dockerfile。
OpenAI 接入示例：

```python
from tls_llm_observer import TraceClient
from tls_llm_observer.openai import OpenAI

trace_client = TraceClient()
client = OpenAI(
trace_client=trace_client,
api_key="<model-api-key>",
base_url="<openai-compatible-endpoint>",
)

try:
response = client.chat.completions.create(
model="<model-name>",
messages=[{"role": "user", "content": "Hello"}],
)
finally:
trace_client.flush()
trace_client.shutdown()
```

### TypeScript / Node.js：TLS LLM Observer（AK/SK）

适用于 Node.js 18 及以上版本。安装 TLS LLM Observer；如需追踪 OpenAI 或 OpenAI-compatible 客户端，同时安装 `openai`：

```bash
npm install @volcengine/tls-llm-observer openai
```

配置 TLS OTLP/HTTP 上报：

```bash
export TLS_TRACE_ENABLED=true
export TLS_TRACE_CAPTURE_CONTENT=true
export OTEL_SERVICE_NAME=tls-llm-node

# TLS OTLP/HTTP 公网接入点
export TLS_TRACE_OTEL_ENDPOINT=https://系统自动填充当前endpoint:4318/v1/traces

# TLS Trace Topic 与 AK/SK 鉴权
export TLS_TRACE_OTEL_TRACE_TOPIC_ID=系统自动填充 trace-topic-id
export TLS_TRACE_OTEL_REGION=系统自动填充当前地域
export TLS_TRACE_OTEL_AK=<需手动替换实际 AccessKeyID>
export TLS_TRACE_OTEL_SK=<需手动替换实际 SecretAccessKey>
```

请通过部署平台的 Secret 能力注入 AK/SK，不要将密钥写入源码、镜像或代码仓库。
SDK 会根据以上配置自动生成：

- `x-tls-otel-tracetopic`

- `x-tls-otel-region`

- `x-tls-otel-ak`

- `x-tls-otel-sk`

OpenAI 接入示例：

```typescript
import OpenAI from 'openai';
import { TraceClient } from '@volcengine/tls-llm-observer';
import { instrumentOpenAI } from '@volcengine/tls-llm-observer/openai';

const traceClient = new TraceClient();

try {
const openai = instrumentOpenAI(
new OpenAI({
apiKey: '<model-api-key>',
baseURL: '<openai-compatible-endpoint>',
}),
{ traceClient },
);

const response = await openai.chat.completions.create({
model: '<model-name>',
messages: [
{
role: 'user',
content: 'Hello',
},
],
});

console.log(response.choices[0]?.message.content);
} finally {
const result = await traceClient.shutdown();

if (!result.completed) {
console.error('TLS Trace 上报未完成：', result);
}
}
```

（仅AK/SK方式）修改使用指引中的鉴权信息。

将已获取的 Access Key ID、Secret Access Key 分别填入使用指引的 AK、SK 中。

将 TLS LLM 观测日志接入至日志应用。

登录部署 TLS LLM 的服务器。

执行使用指引中获取的信息，安装日志服务插件。

插件安装完成后，重启 TLS LLM 服务。

返回日志服务控制台，查看可观测图表数据。

监控图表详情

日志服务 TLS LLM 应用观测监控图表详情如下：

类型	图表
总览	请求总览：会话个数、对话个数、模型请求数、工具调用次数、请求趋势成本总览：总 Tokens、输入 Tokens、输出 Tokens、Cache Read Tokens、Reasoning Tokens、Token 消耗趋势、模型调用趋势工具总览调用成功次数、调用失败次数、工具调用耗时 P90、工具调用 Top10、工具调用失败 Top10、工具调用趋势模型性能总览模型调用分布 Top 10、模型调用耗时 P90、Provider 调用分布、Provider 调用耗时 P90
Trace 分析	总览总 Trace 数、总 Token 消耗、平均 Token、耗时 P90 Trace 调用链分析展示指定调用链的 Input、Output、Trace ID、总 Tokens、Input Tokens、Output Tokens、耗时（s）、开始时间、结束时间等。
会话分析	总览会话个数、总 Token 消耗、模型请求数、平均会话 Token 会话分析展示指定会话的 First Input、Last Output、Session ID、总 Tokens、总耗时 (ms)、调用链数量、耗时（s）、模型、开始时间、结束时间等。
Token 分析	总览总 Tokens、输入 Tokens、输出 Tokens、Cache Read Tokens、Reasoning Tokens、输入Tokens(除Cache)、会话Token消耗Top 10、模型Token消耗Top 10、Token分类占比
Topic 列表	展示当前日志应用产生的日志类型、日志项目和日志主题及描述信息等。

管理我的应用

日志应用接入成功后，支持对已接入的日志应用进行相关管理操作：

AgentLoop

应用市场

登录日志服务控制台。

在顶部导航栏中，选择日志服务所在的地域。

在左侧导航栏中，选择 AgentLoop > AI观测。

在 AI 观测页面，在对应日志应用的操作列，支持如下管理操作：

修改应用信息：单击编辑图标，可修改应用名称和描述信息。

获取使用指引：单击接入配置图标，进入接入配置弹窗，可获取使用指引示例信息。

删除我的应用：单击删除图标，可删除该日志应用。

应用名称_trace（日志主题）日志字段

字段	类型	说明
Attributes	json	Span 上挂载的自定义键值对，记录业务相关信息。
Duration	long	Span 持续时长（End - Start），衡量该操作的耗时。
End	long	Span 结束时间。
Events	text	Span 生命周期内发生的事件。
Host	text	运行服务的主机。
Kind	text	Span 的类型。
Links	text	关联其他 Span 的引用（用于跨 Trace 关联，比如异步任务场景）。
Name	text	Span 的名称，通常是操作描述。
OTLPName	text	通过 OTLP 协议上报时的原始名称（OTLP = OpenTelemetry Line Protocol）。
OTLPVersion	text	使用的 OTLP 协议版本号。
ParentSpanID	text	父 Span 的 ID，表示当前操作是被哪个操作触发的，根节点此字段为空。
Resource	json	一组描述服务本身的属性集合（比 ServiceName 更全），如服务名、版本、运行环境等。
ServiceName	text	产生这条 Span 的服务名称。
SpanID	text	当前 Span 的唯一 ID。
Start	long	Span 开始时间。
StatusCode	text	Span 的执行结果。
StatusDescription	text	Span 的执行结果的补充说明。
TracelD	text	整条调用链的 TracelD，同一次请求的所有 Span 共享同一个 TraceID。
TraceState	text	自定义的追踪上下文元数据。

Attributes

字段	类型	说明
error.type	text	本次调用发生的错误类别。
gen_ai.input.messages	text	发给模型的完整输入消息列表。
gen_ai.output.messages	text	模型输出的消息内容，即 LLM 返回的完整回复文本。
gen_ai.provider.name	text	模型服务商名称。
gen_ai.request.model	text	请求指定的模型名。
gen_ai.response.finish_reasons	text	生成结束原因，表示模型为什么停止输出。
gen_ai.response.first_output_time_unix_nano	long	首个 token 输出时间，Unix 纳秒时间戳。
gen_ai.response.model	text	实际响应使用的模型名称。
gen_ai.tool.name	text	本次调用涉及的工具名称。
gen_ai.tool.type	text	调用的外部工具时的工具类型。
gen_ai.usage.cache_read.input_tokens	long	命中 KV Cache 的输入 Token 数。
gen_ai.usage.input_tokens	long	本次请求消耗的输入 Token 数。
gen_ai.usage.output_tokens	long	本次请求消耗的输出 Token 数。
gen_ai.usage.reasoning.output_tokens	long	Reasoning 消耗的输出 Token 数。
gen_ai.usage.total_tokens	long	总 Token 数。
otel.status_code	text	OpenTelemetry 状态码，用于快速判断这个 Span 是否正常完成。
session.id	text	当前会话的 Session ID。
tls.openai.request.model_parameters	text	请求时传入的模型参数，记录调用 LLM 时携带的参数配置。
tls.span.type	text	TLS 自定义的 Span 类型。
user.id	text	用户 ID。