AI 可观察性

中的 AI 可观察性 OpenSearch 提供了用于监控、调试和优化 AI 代理和大型语言模型 (LLM) 工作流程的 end-to-end工具。它基于 GenAI 语义约定构建，并与 OpenTelemetry (OTel) 原生集成，可让您全面了解 AI 应用程序在生产中的表现。

AI 可观察性包括以下功能：

• 代理跟踪-跨代理编排步骤、LLM 调用、工具调用和检索操作捕获分层执行跟踪。

• GenAI 语义约定 — 使用标准化 OTel 属性（例如gen_ai.systemgen_ai.request.model、和）gen_ai.usage.input_tokens来描述特定于 AI 的遥测。

• 自动仪器 — 自动捕获来自流行的人工智能框架和提供商的痕迹，包括 OpenAI、Anthropic、Amazon B LangChain edrock 和 20 多个其他 20 多个库。

• PPL 查询 — 使用管道处理语言 (PPL) 直接从 UI 查询和聚合跟踪数据。 OpenSearch

开始使用

本节将引导您完成对 AI 代理进行检测、向 Amazon S OpenSearch ervice 发送跟踪以及在 OpenSearch UI 中查看跟踪的过程。

要安装 SDK

安装 OpenTelemetry GenAI 工具包：

pip install opentelemetry-instrumentation-openai-v2 opentelemetry-sdk opentelemetry-exporter-otlp

检测您的代理代码

以下示例说明如何注册 OTel SDK、使用@observe装饰器注释代理函数，以及如何使用 GenAI 属性丰富跨度。

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

# Register the tracer provider
provider = TracerProvider()
processor = BatchSpanProcessor(
    OTLPSpanExporter(endpoint="<your-osis-endpoint>")  # Use your OpenSearch Ingestion endpoint with SigV4
)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

tracer = trace.get_tracer(__name__)

# Decorate your agent function
@observe
def run_agent(prompt: str):
    with tracer.start_as_current_span("invoke_agent") as span:
        span.set_attribute("gen_ai.operation.name", "invoke_agent")
        span.set_attribute("gen_ai.system", "openai")
        span.set_attribute("gen_ai.request.model", "gpt-4")

        # Enrich with token usage after the LLM call
        response = call_llm(prompt)
        span.set_attribute("gen_ai.usage.input_tokens", response.input_tokens)
        span.set_attribute("gen_ai.usage.output_tokens", response.output_tokens)
        return response

注意

向亚马逊 OpenSearch 服务发送跟踪时，请使用带有 Sigv4 身份验证的 OpenSearch Ingestion 管道终端节点，而不是本地主机终端节点。有关配置 OpenSearch 摄取管道的更多信息，请参阅。Amazon OpenSearch Ingestion 概述

在 OpenSearch UI 中查看跟踪

在您的仪器化应用程序发送跟踪数据后，您可以在 OpenSearch UI 中对其进行探索。在您的可观测性工作区中，展开左侧导航栏中的 “发现”，然后选择 Agent Traces。

代理追踪用户界面

OpenSearch 用户界面中的 “代理跟踪” 页面提供了专门构建的界面，用于探索、调试和监控 LLM 代理执行跟踪。它为开发人员和平台操作员提供了对代理人工智能应用程序的完全可观察性，包括分层跟踪视图、详细信息弹出窗口、流量可视化和聚合指标。

架构

下图显示了从装有工具的应用程序到 Agent Traces 用户界面的数据流：

LLM Application (with OTel SDK + GenAI instrumentation)
    |
    |  OTLP (gRPC/HTTP)
    v
OTel Collector (batch, transform)
    |
    +---- OTLP ----> OpenSearch Ingestion --> OpenSearch (otel-v1-apm-span-*)
    |
    +---- Prometheus Remote Write --> Prometheus (metrics)
                                          |
                                          v
                              OpenSearch UI
                              +-- Agent Traces Plugin

先决条件

在使用 Agent Traces 之前，请确保具备以下条件：

• 一个以索引为索引的跟踪数据的 OpenSearch 集群。otel-v1-apm-span-*

• OpenTelemetry 在 LLM 应用程序中启用 GenAI 语义约定进行检测。

• OpenSearch 使用otel_trace_raw处理器配置的摄取跨度。 OpenSearch

• OpenSearch 用户界面中启用了 PPL 查询支持。

必需的跨度属性

Agent Traces 需要特定的跨度属性才能正确呈现跟踪数据。下表描述了核心字段和特定于 Genai 的属性。

核心跨度字段

每个跨度必须包括以下核心字段：

字段	Type	说明
traceId	字符串	整个跟踪的唯一标识符。
spanId	字符串	此跨度的唯一标识符。
parentSpanId	字符串	父跨度的标识符。根跨度为空。
startTime	Timestamp	跨度开始的时间。
endTime	Timestamp	跨度结束的时间。
durationInNanos	长整型	跨度的持续时间（以纳秒为单位）。
status.code	整数	Span 状态码（0 = 未设置，1 = 正常，2 = 错误）。

GenAI 属性

以下gen_ai.*属性在 Agent Traces 用户界面中启用特定于 AI 的功能：

属性	示例值	说明
gen_ai.operation.name	chat	GenAI 操作的类型。确定跨度类别。
gen_ai.system	openai	人工智能系统或提供商。
gen_ai.request.model	gpt-4	用于请求的模型。
gen_ai.usage.input_tokens	150	消耗的输入令牌数量。
gen_ai.usage.output_tokens	85	生成的输出令牌数量。
gen_ai.response.finish_reasons	["stop"]	模型停止生成的原因。

页面布局和指标栏

“代理跟踪” 页面在顶部显示一个指标栏，其中汇总了所有可见跟踪的关键统计信息。指标包括跟踪总数、平均持续时间、错误率和令牌使用量。这些值会根据您的时间筛选和查询动态更新。

追踪选项卡

“跟踪” 选项卡列出了与您当前查询和时间范围匹配的所有根代理跟踪。每行代表一次代理调用。

下表描述了 traces 表中的各列：

列	说明
追踪编号	跟踪的唯一标识符。选择链接以打开追踪详情弹出窗口。
座席姓名	启动跟踪的代理的名称。
Status	总体跟踪状态（“正常” 或 “错误”）。
Duration	从轨迹中第一个跨度到最后一个跨度的总时间。
跨度	轨迹中的跨度总数。
输入令牌数	在跟踪中所有 LLM 调用中消耗的输入令牌总数。
输出令牌数	在跟踪中所有 LLM 调用中生成的输出令牌总数。
开始时间	跟踪开始的时间戳。

跨度类别

跨度是根据gen_ai.operation.name属性进行分类的。每个类别在用户界面中都以独特的颜色和图标显示。

操作名称	类别	说明
invoke_agent, create_agent	座席	代理编排步骤。
chat	LLM	LLM 聊天完成通话。
text_completion, generate_content	内容	文本生成操作。
execute_tool	工具	工具调用。
embeddings	嵌入	嵌入生成。
retrieval	检索	数据检索操作。

“跨度” 选项卡

跨度选项卡显示所有轨迹上的单个跨度。您可以对跨度进行筛选和排序以查找特定的操作。

“追踪详情” 弹出窗口

当您选择跟踪 ID 时，会打开一个包含两个主要区域的弹出式面板：

• 左侧面板-显示跟踪树，其中显示跨度之间的分层父子关系。它还包括一个可视化代理执行路径的流 DAG（有向无环图）。

• 右侧面板-包含两个选项卡。详细信息选项卡显示跨度属性、资源属性和特定于 Genai 的元数据。时间轴选项卡显示跨度持续时间及其时间关系的瀑布图。

查询轨迹

Agent Traces 使用 PPL（管道处理语言）进行所有数据获取。您可以在页面顶部的查询面板中编写查询。

列出根轨迹

以下查询返回最近的 100 条根代理跟踪：

source = otel-v1-apm-span-*
| where parentSpanId = "" AND isnotnull(`attributes.gen_ai.operation.name`)
| sort - startTime
| head 100

获取所有跨度以进行跟踪

以下查询返回特定跟踪的完整跨度树：

source = otel-v1-apm-span-*
| where traceId = "trace-id"
| head 1000

计算聚合指标

以下查询计算按模型分组的平均持续时间和代币总使用量：

source = otel-v1-apm-span-*
| where isnotnull(`attributes.gen_ai.request.model`)
| stats avg(durationInNanos) as avg_duration,
        sum(`attributes.gen_ai.usage.input_tokens`) as total_input_tokens,
        sum(`attributes.gen_ai.usage.output_tokens`) as total_output_tokens
    by `attributes.gen_ai.request.model`