AI 可觀測性

OpenSearch 中的 AI 可觀測性提供end-to-end工具，用於監控、偵錯和最佳化 AI 代理程式和大型語言模型 (LLM) 工作流程。以 GenAI 語意慣例為基礎，並與 OpenTelemetry (OTel) 原生整合，可讓您完全了解 AI 應用程式在生產中的行為。

AI 可觀測性包括下列功能：

• 代理程式追蹤 – 擷取跨代理程式協同運作步驟、LLM 呼叫、工具調用和擷取操作的階層式執行追蹤。

• GenAI 語意慣例 – 使用標準化 OTel 屬性，例如 gen_ai.system、 gen_ai.request.model和 gen_ai.usage.input_tokens來描述 AI 特定的遙測。

• 自動檢測 – 自動擷取來自熱門 AI 架構和提供者的追蹤，包括 OpenAI、Anthropic、Amazon Bedrock、LangChain 和其他 20 多個程式庫。

• PPL 查詢 – 直接從 OpenSearch UI 使用 Piped Processing Language (PPL) 查詢和彙總追蹤資料。

開始使用

本節會逐步引導您檢測 AI 代理器、將追蹤傳送至 Amazon OpenSearch Service，以及在 OpenSearch UI 中檢視它們。

安裝 SDK

安裝 OpenTelemetry GenAI 檢測套件：

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

檢測您的代理程式程式碼

下列範例示範如何註冊 OTel 開發套件、使用@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

注意

當您將追蹤傳送至 Amazon OpenSearch Service 時，請使用您的 OpenSearch Ingestion 管道端點搭配 SigV4 身分驗證，而非 localhost 端點。如需設定 OpenSearch Ingestion 管道的詳細資訊，請參閱 Amazon OpenSearch 擷取概觀。

在 OpenSearch UI 中檢視追蹤

經過檢測的應用程式傳送追蹤資料後，您可以在 OpenSearch UI 中探索它。在您的可觀測性工作區中，展開左側導覽中的探索，然後選擇客服人員追蹤。

客服人員追蹤 UI

OpenSearch UI 中的代理程式追蹤頁面提供專用界面，用於探索、偵錯和監控 LLM 代理程式執行追蹤。它為開發人員和平台運算子提供代理式 AI 應用程式的完整可觀測性，包括階層追蹤檢視、詳細資訊飛濺、流程視覺化和彙總指標。

Architecture

下圖顯示從檢測應用程式到客服人員追蹤 UI 的資料流程：

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

先決條件

使用客服人員追蹤之前，請確定您有下列項目：

• 具有以索引編製索引之追蹤資料的 OpenSearch otel-v1-apm-span-* 叢集。

• 在 LLM 應用程式中啟用 GenAI 語意慣例的 OpenTelemetry 檢測。

• 使用otel_trace_raw處理器設定的 OpenSearch Ingestion 會擷取到 OpenSearch。

• 在 OpenSearch UI 中啟用 PPL 查詢支援。

必要的跨度屬性

客服人員追蹤需要特定的跨屬性才能正確轉譯追蹤資料。下表說明核心欄位和 GenAI 特定的屬性。

核心跨度欄位

每個範圍必須包含下列核心欄位：

欄位	Type	Description
traceId	String	整個追蹤的唯一識別符。
spanId	String	此範圍的唯一識別符。
parentSpanId	String	父系範圍的識別符。根範圍為空白。
startTime	時間戳記	跨度開始的時間。
endTime	時間戳記	跨度結束的時間。
durationInNanos	Long	跨度的持續時間，以奈秒為單位。
status.code	Integer	跨度狀態碼 (0 = 未設定，1 = 確定，2 = 錯誤）。

GenAI 屬性

下列gen_ai.*屬性會在 Agent Traces UI 中啟用 AI 特定功能：

屬性	範例值	Description
gen_ai.operation.name	chat	GenAI 操作的類型。決定跨度類別。
gen_ai.system	openai	AI 系統或提供者。
gen_ai.request.model	gpt-4	用於請求的模型。
gen_ai.usage.input_tokens	150	使用的輸入字符數量。
gen_ai.usage.output_tokens	85	產生的輸出字符數量。
gen_ai.response.finish_reasons	["stop"]	模型停止產生的原因。

頁面配置和指標列

客服人員追蹤頁面會在頂端顯示指標列，摘要所有可見追蹤的關鍵統計資料。指標包括總追蹤計數、平均持續時間、錯誤率和字符用量。這些值會根據您的時間篩選條件和查詢動態更新。

追蹤索引標籤

追蹤索引標籤會列出所有符合您目前查詢和時間範圍的根代理程式追蹤。每一列代表單一客服人員叫用。

下表說明追蹤表格中的資料欄：

資料行	Description
追蹤 ID	追蹤的唯一識別符。選擇連結以開啟追蹤詳細資訊飛出。
客服人員名稱	啟動追蹤的代理程式名稱。
狀態	整體追蹤狀態 (OK 或 Error)。
持續時間	從第一個跨度到追蹤中最後一個跨度的總時間。
範圍	追蹤中的跨度總數。
輸入字符	追蹤中所有 LLM 呼叫所使用的輸入字符總數。
輸出字符	追蹤中所有 LLM 呼叫所產生的輸出字符總數。
開始時間	追蹤開始時的時間戳記。

跨度類別

範圍是根據 gen_ai.operation.name 屬性分類。每個類別都會在 UI 中顯示唯一的顏色和圖示。

操作名稱	類別	描述
invoke_agent, create_agent	客服人員	客服人員協同運作步驟。
chat	LLM	LLM 聊天完成呼叫。
text_completion, generate_content	內容	文字產生操作。
execute_tool	工具	工具調用。
embeddings	嵌入項目	內嵌產生。
retrieval	擷取	資料擷取操作。

跨度索引標籤

跨度索引標籤會顯示所有追蹤的個別跨度。您可以篩選和排序範圍，以尋找特定操作。

追蹤詳細資訊飛出

當您選擇追蹤 ID 時，展開面板會開啟兩個主要區域：

• 左側面板 – 顯示追蹤樹狀結構，其中顯示跨度之間的階層式父子關係。它還包含一個流程 DAG （定向非循環圖形），可視覺化代理程式的執行路徑。

• 右面板 – 包含兩個標籤。詳細資訊索引標籤會顯示跨度屬性、資源屬性和 GenAI 特定的中繼資料。時間軸索引標籤會顯示跨度持續時間及其時間關係的瀑布圖。

查詢追蹤

客服人員追蹤使用 PPL (Piped Processing Language) 進行所有資料擷取。您可以在頁面頂端的查詢面板中撰寫查詢。

列出根追蹤

下列查詢會傳回 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`