@microsoft/agents-a365-observability package

類別

Agent365ExporterOptions

每批出口最大跨數。
BaggageBuilder

根據請求提供 OpenTelemetry 上下文傳播的行李建構器。

此類別提供流暢的 API 來設定行李值，這些值將在 OpenTelemetry 情境中傳播。

範例

const scope = new BaggageBuilder()
  .tenantId("tenant-123")
  .agentId("agent-456")
  .build();

scope.enter();
// Baggage is set in this context
// ... do work ...
scope.exit();
// Baggage is restored after exiting the context
BaggageScope

行李範圍的上下文管理器。

此類別管理行李值的生命週期，將它們設為進入，並在退出時恢復先前的上下文。
Builder

用於配置 Agent 365 與 OpenTelemetry 追蹤的建構器
ExecuteToolScope

提供 OpenTelemetry 追蹤範圍，用於 AI 工具執行操作。
InferenceScope

提供 OpenTelemetry 追蹤空間，用於生成式 AI 推論操作。
InvokeAgentScope

提供 AI 代理呼叫操作的 OpenTelemettry 追蹤範圍。
ObservabilityConfiguration

可觀測性套件的設定。 繼承執行時設定並新增針對可觀察性的設定。
ObservabilityManager

Agent 365 的主要入口，提供 AI 代理與工具的 OpenTelemetry 追蹤
OpenTelemetryConstants

Agent 365 的 OpenTelemetry 常數
OpenTelemetryScope

OpenTelemetry 追蹤示波器的基礎類別
OutputScope

提供 OpenTelemetry 追蹤範圍，用於輸出訊息追蹤並結合父跨連結。
PerRequestSpanProcessorConfiguration

PerRequestSpanProcessor 的設定。 繼承執行時設定（clusterCategory、isNodeEnvDevelopment），並新增每個請求的處理器防護。

此設定與 ObservabilityConfiguration 分開，因為 PerRequestSpanProcessor 僅用於特定情境，且這些設定不應暴露於共用的 ObservabilityConfiguration。

介面

AgentDetails

關於 AI 代理的細節
BlobPart

內嵌二進位資料（base64編碼）。
BuilderOptions

Agent 365 Observability Builder 的設定選項
CallerDetails

來電者資料以建立範圍。 支援真人來電者、代理來電者，或兩者兼具（A2A 與人連線）。

遷移說明： 在 v1 中，名稱 CallerDetails 指的是人類呼叫者身份（現為 UserDetails）。 在 v2 中，它被重新定位為包裝器，將人類與代理呼叫者的資訊分組。

請參閱 UserDetails — 人類來電者身份（先前 CallerDetails） 請參閱 CHANGELOG.md — 變更變更區段以獲取遷移指引
Channel

代表呼叫通道
ChatMessage

發送給模型的輸入訊息（OTEL 生成-人工智慧語意慣例）。
FilePart

參考預先上傳的檔案。
GenericPart

可擴充零件，適用於客製化或未來類型。
GenericServerToolCall

可擴充伺服器工具呼叫細節，並附有類型判別器。
GenericServerToolCallResponse

可擴充伺服器工具呼叫回應，並帶有型別判別器。
ILogger

Agent 365 可觀察性自訂記錄器介面實作此介面以支援日誌後端
InferenceDetails

推論呼叫的詳細說明
InferenceResponse

關於錄製推論呼叫回應的細節
InputMessages
InvokeAgentScopeDetails

關於調用代理人範圍的細節。
OutputMessage

由模型產生的輸出訊息（OTEL 生成-人工智慧語意慣例）。
OutputMessages
OutputResponse

代表包含代理輸出訊息的回應。 搭配 OutputScope 進行輸出訊息追蹤。 接受純字串、結構化 OTEL OutputMessage 物件，或原始字典（依 OTEL 規範視為工具呼叫結果）。
ParentSpanRef

在非同步邊界的明確父子連結時，參考父區間。 當自動上下文傳播失敗時（例如，WebSocket 回調、外部事件處理程序）時會使用。
ReasoningPart

模型推理/思緒鏈內容。
Request

代表帶有遙測上下文的請求。 適用於所有類型的頻道與對話追蹤。
ServerToolCallPart

伺服器端工具調用。
ServerToolCallResponsePart

伺服器端工具回應。
ServiceEndpoint

代表代理呼叫的端點
SpanDetails

範圍設定細節以建立範圍。 OpenTelemetry 群組將選項跨成單一物件，確保範圍方法簽名在新增選項時保持穩定。
TextPart

純文字內容。
ToolCallDetails

代理人所作工具呼叫的細節
ToolCallRequestPart

模型請求的工具呼叫。
ToolCallResponsePart

工具呼叫的結果。
UriPart

外部 URI 參考資料。
UserDetails

關於人類用戶呼叫者的詳細資訊。

類型別名

EnhancedAgentDetails
HeadersCarrier

用於追蹤上下文傳播的 HTTP 標頭載波類型。 相容於 Node.js IncomingHttpHeaders 及純字串映射。
InputMessagesParam

接受的輸入。recordInputMessages 支援單一字串、一組字串陣列（向下相容）或版本化包裝器。
MessagePart

根據 OTEL 生成 AI 語意慣例，所有訊息部分類型的合併。

注意： GenericPart 作為與自訂或未來零件類型的前向相容性包羅萬用。 由於 是typestring （非字面值），窮盡化switch/casepart.type不會在未處理的情況中產生編譯時錯誤。
ObservabilityConfigurationOptions

可觀察性設定選項——擴充執行時選項。 所有覆蓋都是在每個屬性存取時呼叫的函式。

繼承自 RuntimeConfigurationOptions：

  • clusterCategory
  • isNodeEnvDevelopment

注意： isDevelopmentEnvironment 是基於 clusterCategory 的配置類別上的導出 getter，不是可覆寫的選項。
OutputMessagesParam

接受的輸入。recordOutputMessages 支援單一字串、一組字串陣列（向下相容）或版本化包裝器。
ParentContext

一個用於建立跨度的父上下文。 接受以下任一：
PerRequestSpanProcessorConfigurationOptions

PerRequestSpanProcessor 的設定選項 - 擴充執行時選項。 所有覆蓋都是在每個屬性存取時呼叫的函式。

繼承自 RuntimeConfigurationOptions：

  • clusterCategory， isNodeEnvDevelopment
ResponseMessagesParam

接受的輸入。OutputResponse.messages 支援純字串、結構化 OutputMessages，或原始字典（依 OTEL 規範視為工具呼叫結果，並直接透過 JSON.stringify 序列化）。

列舉

ExporterEventNames

Agent365Exporter 用於日誌與監控的事件名稱。 這些事件類型屬於低基數，以確保監控與彙整的效率。
FinishReason

為什麼模型會依照 OTEL 生成式 AI 語意慣例停止產生。
InferenceOperationType

代表模型推論類型的不同操作
InvocationRole

代表可呼叫代理的不同角色
MessageRole

根據 OTEL 生成人工智慧語意慣例，訊息參與者的角色。
Modality

Blob、檔案及 URI 部分的媒體模式。

函式

createContextWithParentSpanRef(Context, ParentSpanRef)

建立一個帶有明確父區間參考的新上下文。 這使得即使非同步上下文被破壞，子區間也能被正確地父化。
extractContextFromHeaders(HeadersCarrier, Context)

利用全球註冊的 W3C 傳播器，從輸入的 HTTP 標頭中擷取追蹤上下文。 回傳一個可傳給作用域類別的 OTel ParentContext ，作為 ParentContext。

範例

const parentCtx = extractContextFromHeaders(req.headers);
const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, undefined, { parentContext: parentCtx });
formatError(unknown)

用於與訊息及堆疊追蹤的日誌格式錯誤物件
getExportToken(Context)

從特定 OTel 上下文（或主動上下文）取得每個請求的匯出令牌。
getLogger()

取得目前的 Logger 實例
injectContextToHeaders(Record<string, string>, Context)

利用全域註冊的 W3C 傳播器，將目前的追蹤上下文（traceparent/tracestate 標頭）注入所提供的標頭物件中。

範例

const headers: Record<string, string> = {};
injectContextToHeaders(headers);
await fetch('http://service-b/process', { headers });
isPerRequestExportEnabled(IConfigurationProvider<PerRequestSpanProcessorConfiguration>)

檢查是否有啟用每個請求匯出。 優先順序：內部覆蓋 > 配置提供者 > 環境變數。 啟用時，會使用 PerRequestSpanProcessor 取代 BatchSpanProcessor。 該令牌在匯出時透過 OTel Context（非同步本地儲存）傳遞。
normalizeInputMessages(InputMessagesParam)

將 標準化 到 InputMessagesParam 版本化 InputMessages 包裝器。

  • string / string[] →轉換成 ChatMessage[] 並包裹
  • InputMessages →回來 as-is
normalizeOutputMessages(OutputMessagesParam)

將 標準化 到 OutputMessagesParam 版本化 OutputMessages 包裝器。

  • string / string[] →轉換成 OutputMessage[] 並包裹
  • OutputMessages →回來 as-is
resetLogger()

重置回預設的控制台記錄器（主要是為了測試）
runWithExportToken<T>(string, () => T)

在帶有每個請求匯出權杖的 Context 中執行一個函式。 這會讓代幣只保留在 OTel 上下文（ALS）中，不會在任何登錄檔中。

標記可以在追蹤清除前更新 updateExportToken() ——當回調持續很久且原始標記可能在匯出前過期時，這很有用。
runWithExtractedTraceContext<T>(HeadersCarrier, () => T)

從收到的 HTTP 標頭中擷取追蹤上下文，並在該上下文中執行回調。 回調中產生的任何區間都會被子帶到被抽取的痕跡。

範例

runWithExtractedTraceContext(req.headers, () => {
  const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  scope.dispose();
});
runWithParentSpanRef<T>(ParentSpanRef, () => T)

在有明確父區間參考的上下文中執行回調函式。 這對於在上下文傳播中斷的非同步回調中建立子區間非常有用。
safeSerializeToJson(string | Record<string, unknown>, string)

確保值永遠是 JSON 解析的字串。

  • 物件透過 JSON.stringify 序列化。
  • 已經是有效的 JSON 物件/陣列的字串會被傳遞。
  • 所有其他字串（包括裸 JSON 原語）都被 wrap 過 { [key]: value }：
serializeMessages(InputMessages | OutputMessages)

將版本限制的訊息包裝器序列化為 JSON。

輸出為完整包裝物件： {"version":"0.1.0","messages":[...]}。

嘗試/捕捉確保即使訊息部分包含不可序列化的值（例如 BigInt、循環參考），遙測記錄仍不會拋出。
setLogger(ILogger)

為可觀察性SDK設定自訂logger實作

以溫斯頓為例：

import * as winston from 'winston';
import { setLogger } from '@microsoft/agents-a365-observability';

const winstonLogger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' })
  ]
});

setLogger({
  info: (msg, ...args) => winstonLogger.info(msg, ...args),
  warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
  error: (msg, ...args) => winstonLogger.error(msg, ...args),
  event: (eventType, isSuccess, durationMs, message, details) => {
    // eventType is ExporterEventNames enum value
    winstonLogger.log({ level: isSuccess ? 'info' : 'error', eventType, isSuccess, durationMs, message, ...details });
  }
});
updateExportToken(string)

在啟用的 OTel 上下文中更新匯出令牌。 呼叫此命令以在結束根區間前刷新權杖，當原始權杖可能在長時間執行的請求中已過期時結束。

必須在由 runWithExportToken創建的相同非同步上下文中呼叫。

變數

A365_MESSAGE_SCHEMA_VERSION
defaultObservabilityConfigurationProvider

ObservabilityConfiguration 的共享預設提供者。
defaultPerRequestSpanProcessorConfigurationProvider

PerRequestSpanProcessorConfiguration 的共用預設提供者。
logger

預設的日誌實例以實現向下相容。 代表式到全域記錄器，可透過 setLogger（） 替換。

函式詳細資料

createContextWithParentSpanRef(Context, ParentSpanRef)

建立一個帶有明確父區間參考的新上下文。 這使得即使非同步上下文被破壞，子區間也能被正確地父化。

function createContextWithParentSpanRef(base: Context, parent: ParentSpanRef): Context

參數

base

Context

要擴充的基礎上下文（通常是 context.active（））

parent
ParentSpanRef

包含 traceId 和 spanID 的父區間參考

傳回

Context

一個帶有父張成集合的新上下文

extractContextFromHeaders(HeadersCarrier, Context)

利用全球註冊的 W3C 傳播器，從輸入的 HTTP 標頭中擷取追蹤上下文。 回傳一個可傳給作用域類別的 OTel ParentContext ，作為 ParentContext。

範例

const parentCtx = extractContextFromHeaders(req.headers);
const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, undefined, { parentContext: parentCtx });

function extractContextFromHeaders(headers: HeadersCarrier, baseCtx?: Context): Context

參數

headers
HeadersCarrier

包含 traceparent/tracestate的 HTTP 請求標頭包含 。

baseCtx

Context

可選擇性基礎背景以擴充。 預設為主動上下文。

傳回

Context

包含擷取出的追蹤資訊的 OTel 上下文。

formatError(unknown)

用於與訊息及堆疊追蹤的日誌格式錯誤物件

function formatError(error: unknown): string

參數

error

unknown

傳回

string

getExportToken(Context)

從特定 OTel 上下文（或主動上下文）取得每個請求的匯出令牌。

function getExportToken(ctx?: Context): string | undefined

參數

ctx

Context

傳回

string | undefined

getLogger()

取得目前的 Logger 實例

function getLogger(): ILogger

傳回

ILogger

injectContextToHeaders(Record<string, string>, Context)

利用全域註冊的 W3C 傳播器，將目前的追蹤上下文（traceparent/tracestate 標頭）注入所提供的標頭物件中。

範例

const headers: Record<string, string> = {};
injectContextToHeaders(headers);
await fetch('http://service-b/process', { headers });

function injectContextToHeaders(headers: Record<string, string>, ctx?: Context): Record<string, string>

參數

headers

Record<string, string>

可變物件，將寫入追蹤上下文標頭。

ctx

Context

可選的 OTel Context 注入。 預設為主動上下文。

傳回

Record<string, string>

同 headers 一件物品，為了方便連鎖。

isPerRequestExportEnabled(IConfigurationProvider<PerRequestSpanProcessorConfiguration>)

檢查是否有啟用每個請求匯出。 優先順序：內部覆蓋 > 配置提供者 > 環境變數。 啟用時，會使用 PerRequestSpanProcessor 取代 BatchSpanProcessor。 該令牌在匯出時透過 OTel Context（非同步本地儲存）傳遞。

function isPerRequestExportEnabled(configProvider?: IConfigurationProvider<PerRequestSpanProcessorConfiguration>): boolean

參數

configProvider

IConfigurationProvider<PerRequestSpanProcessorConfiguration>

可選的設定提供者。 若未指定，預設為 defaultPerRequestSpanProcessorConfigurationProvider。

傳回

boolean

normalizeInputMessages(InputMessagesParam)

將 標準化 到 InputMessagesParam 版本化 InputMessages 包裝器。

  • string / string[] →轉換成 ChatMessage[] 並包裹
  • InputMessages →回來 as-is
function normalizeInputMessages(param: InputMessagesParam): InputMessages

參數

param
InputMessagesParam

傳回

InputMessages

normalizeOutputMessages(OutputMessagesParam)

將 標準化 到 OutputMessagesParam 版本化 OutputMessages 包裝器。

  • string / string[] →轉換成 OutputMessage[] 並包裹
  • OutputMessages →回來 as-is
function normalizeOutputMessages(param: OutputMessagesParam): OutputMessages

參數

param
OutputMessagesParam

傳回

OutputMessages

resetLogger()

重置回預設的控制台記錄器（主要是為了測試）

function resetLogger()

runWithExportToken<T>(string, () => T)

在帶有每個請求匯出權杖的 Context 中執行一個函式。 這會讓代幣只保留在 OTel 上下文（ALS）中，不會在任何登錄檔中。

標記可以在追蹤清除前更新 updateExportToken() ——當回調持續很久且原始標記可能在匯出前過期時，這很有用。

function runWithExportToken<T>(token: string, fn: () => T): T

參數

token

string

fn

() => T

傳回

T

runWithExtractedTraceContext<T>(HeadersCarrier, () => T)

從收到的 HTTP 標頭中擷取追蹤上下文，並在該上下文中執行回調。 回調中產生的任何區間都會被子帶到被抽取的痕跡。

範例

runWithExtractedTraceContext(req.headers, () => {
  const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  scope.dispose();
});

function runWithExtractedTraceContext<T>(headers: HeadersCarrier, callback: () => T): T

參數

headers
HeadersCarrier

包含 traceparent/tracestate的 HTTP 請求標頭包含 。

callback

() => T

在擷取的上下文中執行函式。

傳回

T

這是回調的結果。

runWithParentSpanRef<T>(ParentSpanRef, () => T)

在有明確父區間參考的上下文中執行回調函式。 這對於在上下文傳播中斷的非同步回調中建立子區間非常有用。

function runWithParentSpanRef<T>(parent: ParentSpanRef, callback: () => T): T

參數

parent
ParentSpanRef

父跨度參考

callback

() => T

與父上下文一起執行的函式

傳回

T

回調的結果

safeSerializeToJson(string | Record<string, unknown>, string)

確保值永遠是 JSON 解析的字串。

  • 物件透過 JSON.stringify 序列化。
  • 已經是有效的 JSON 物件/陣列的字串會被傳遞。
  • 所有其他字串（包括裸 JSON 原語）都被 wrap 過 { [key]: value }：
function safeSerializeToJson(value: string | Record<string, unknown>, key: string): string

參數

value

string | Record<string, unknown>

序列化的價值。

key

string

纏繞普通弦時該用的鑰匙。

傳回

string

serializeMessages(InputMessages | OutputMessages)

將版本限制的訊息包裝器序列化為 JSON。

輸出為完整包裝物件： {"version":"0.1.0","messages":[...]}。

嘗試/捕捉確保即使訊息部分包含不可序列化的值（例如 BigInt、循環參考），遙測記錄仍不會拋出。

function serializeMessages(wrapper: InputMessages | OutputMessages): string

參數

wrapper

InputMessages | OutputMessages

傳回

string

setLogger(ILogger)

為可觀察性SDK設定自訂logger實作

以溫斯頓為例：

import * as winston from 'winston';
import { setLogger } from '@microsoft/agents-a365-observability';

const winstonLogger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' })
  ]
});

setLogger({
  info: (msg, ...args) => winstonLogger.info(msg, ...args),
  warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
  error: (msg, ...args) => winstonLogger.error(msg, ...args),
  event: (eventType, isSuccess, durationMs, message, details) => {
    // eventType is ExporterEventNames enum value
    winstonLogger.log({ level: isSuccess ? 'info' : 'error', eventType, isSuccess, durationMs, message, ...details });
  }
});

function setLogger(customLogger: ILogger)

參數

customLogger
ILogger

自訂記錄器實作

updateExportToken(string)

在啟用的 OTel 上下文中更新匯出令牌。 呼叫此命令以在結束根區間前刷新權杖，當原始權杖可能在長時間執行的請求中已過期時結束。

必須在由 runWithExportToken創建的相同非同步上下文中呼叫。

function updateExportToken(token: string): boolean

參數

token

string

新鮮代幣用於出口。

傳回

boolean

若令牌成功更新，則為 true;若未找到令牌持有者，則為 false。

變數詳細資料

A365_MESSAGE_SCHEMA_VERSION 

A365_MESSAGE_SCHEMA_VERSION: "0.1.0"

類型

string

defaultObservabilityConfigurationProvider

ObservabilityConfiguration 的共享預設提供者。

defaultObservabilityConfigurationProvider: DefaultConfigurationProvider<ObservabilityConfiguration>

類型

DefaultConfigurationProvider<ObservabilityConfiguration>

defaultPerRequestSpanProcessorConfigurationProvider

PerRequestSpanProcessorConfiguration 的共用預設提供者。

defaultPerRequestSpanProcessorConfigurationProvider: DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>

類型

DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>

logger

預設的日誌實例以實現向下相容。 代表式到全域記錄器，可透過 setLogger（） 替換。

logger: ILogger

類型

ILogger