通过

@microsoft/agents-a365-observability package

类

Agent365ExporterOptions

每个导出批处理的最大跨度数。
BaggageBuilder

OpenTelemetry 上下文传播的每个请求行李生成器。

此类提供了一个 Fluent 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

使用 OpenTelemetry 跟踪配置 Agent 365 的生成器
ExecuteToolScope

为 AI 工具执行作提供 OpenTelemetry 跟踪范围。
InferenceScope

为生成 AI 推理作提供 OpenTelemetry 跟踪范围。
InvokeAgentScope

为 AI 代理调用作提供 OpenTelemetry 跟踪范围。
ObservabilityConfiguration

可观测性包的配置。 继承运行时设置并添加特定于可观测性的设置。
ObservabilityManager

代理 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 可观测性生成器的配置选项
CallerDetails

用于创建作用域的调用方详细信息。 支持人工呼叫者、代理呼叫者或两者（A2A 与链中的人类）。

迁移说明： 在 v1 中，该名称 CallerDetails 引用了人类调用方标识（现在 为 UserDetails）。 在 v2 中，它被重新调整为将人类和代理调用方信息组合在一起的包装器。

请参阅 UserDetails — 人工调用方标识（以前 CallerDetails） 请参阅 CHANGELOG.md - 迁移指南的中断性变更部分
Channel

表示调用的通道
ChatMessage

发送到模型的输入消息（GEN-gen-ai 语义约定）。
FilePart

对预上传文件的引用。
GenericPart

自定义/将来类型的可扩展部件。
GenericServerToolCall

可扩展服务器工具调用详细信息和类型鉴别器。
GenericServerToolCallResponse

可扩展服务器工具使用类型鉴别器调用响应。
ILogger

代理 365 可观测性的自定义记录器接口实现此接口以支持日志记录后端
InferenceDetails

推理调用的详细信息
InferenceResponse

记录来自推理调用的响应的详细信息
InputMessages
InvokeAgentScopeDetails

调用代理范围的详细信息。
OutputMessage

模型生成的输出消息（GEN-gen-ai 语义约定）。
OutputMessages
OutputResponse

表示包含来自代理的输出消息的响应。 与 OutputScope 一起使用，用于输出消息跟踪。 接受纯字符串、结构化 TAB OutputMessage 对象或原始听写（按 一个 一个 TAB 规范视为工具调用结果）。
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

每个 GEN gen-ai 语义约定的所有消息部件类型的联合。

注意： GenericPart 充当一个 catch-all，以便与自定义或将来的部件类型向前兼容。 由于它是typestring （不是文字），因此详尽switch/casepart.type介绍不会为未经处理的事例生成编译时错误。
ObservabilityConfigurationOptions

可观测性配置选项 - 扩展运行时选项。 所有替代都是在每个属性访问上调用的函数。

继承自 RuntimeConfigurationOptions：

  • clusterCategory
  • isNodeEnvDevelopment

注意： isDevelopmentEnvironment 是配置类（基于 clusterCategory）的派生 getter，而不是可重写的选项。
OutputMessagesParam

接受的输入 。recordOutputMessages 支持单个字符串、字符串数组（向后组合）或版本控制包装器。
ParentContext

用于跨度创建的父上下文。 接受以下任一：
PerRequestSpanProcessorConfigurationOptions

PerRequestSpanProcessor 的配置选项 - 扩展运行时选项。 所有替代都是在每个属性访问上调用的函数。

继承自 RuntimeConfigurationOptions：

  • clusterCategory，isNodeEnvDevelopment
ResponseMessagesParam

接受的输入 。OutputResponse.messages 支持纯字符串、结构化 OutputMessages 或原始听写（被视为每个 SPEC 规范的工具调用结果，并通过 JSON.stringify 直接序列化）。

枚举

ExporterEventNames

Agent365Exporter 用于日志记录和监视的事件名称。 这些是低基数事件类型，可确保高效监视和聚合。
FinishReason

模型停止为每个 一代 AI 语义约定生成的原因。
InferenceOperationType

表示模型推理类型的不同作
InvocationRole

表示可以调用代理的不同角色
MessageRole

每个 GEN gen-ai 语义约定的消息参与者的角色。
Modality

Blob、文件和 URI 部件的媒体形式。

函数

createContextWithParentSpanRef(Context, ParentSpanRef)

使用显式父范围引用创建新的上下文。 这样，即使异步上下文断开，子范围也能正确进行父级。
extractContextFromHeaders(HeadersCarrier, Context)

使用全局注册的 W3C 传播器从传入的 HTTP 标头中提取跟踪上下文。 返回一个 OTel，该 OTel ParentContext 可以作为 ParentContext 传递给范围类。

示例

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

使用消息和堆栈跟踪记录的格式错误对象
getExportToken(Context)

从给定的 OTel 上下文（或活动令牌）检索每个请求导出令牌。
getLogger()

获取当前记录器实例
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)

在包含每个请求导出令牌的上下文中运行函数。 这仅在 OTel Context （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 基元）都包装： { [key]: value }。
serializeMessages(InputMessages | OutputMessages)

将版本控制的消息包装器序列化为 JSON。

输出是完整的包装对象： {"version":"0.1.0","messages":[...]}。

try/catch 可确保即使消息部分包含非 JSON 可序列化值（例如 BigInt、循环 refs）时，遥测记录也不会引发。
setLogger(ILogger)

为可观测性 SDK 设置自定义记录器实现

Winston 的示例：

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 });
  }
});
truncateValue(string)

截断字符串值以 MAX_ATTRIBUTE_LENGTH 字符。 如果该值超出限制，将剪裁并追加截断后缀，总长度限制在完全 MAX_ATTRIBUTE_LENGTH。
updateExportToken(string)

更新活动 OTel 上下文中的导出令牌。 调用此项以在结束根范围之前刷新令牌，当原始令牌在长时间运行的请求期间可能已过期。

必须在创建 runWithExportToken相同的异步上下文中调用。

变量

A365_MESSAGE_SCHEMA_VERSION
MAX_ATTRIBUTE_LENGTH

跨度属性值的最大长度。 超出此限制的值将用后缀截断。
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，该 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()

获取当前记录器实例

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 上下文。 默认为活动上下文。

返回

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)

在包含每个请求导出令牌的上下文中运行函数。 这仅在 OTel Context （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 基元）都包装： { [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":[...]}。

try/catch 可确保即使消息部分包含非 JSON 可序列化值（例如 BigInt、循环 refs）时，遥测记录也不会引发。

function serializeMessages(wrapper: InputMessages | OutputMessages): string

参数

wrapper

InputMessages | OutputMessages

返回

string

setLogger(ILogger)

为可观测性 SDK 设置自定义记录器实现

Winston 的示例：

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

自定义记录器实现

truncateValue(string)

截断字符串值以 MAX_ATTRIBUTE_LENGTH 字符。 如果该值超出限制，将剪裁并追加截断后缀，总长度限制在完全 MAX_ATTRIBUTE_LENGTH。

function truncateValue(value: string): string

参数

value

string

要截断的字符串

返回

string

如果超出限制，则为原始字符串，否则截断字符串

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

MAX_ATTRIBUTE_LENGTH

跨度属性值的最大长度。 超出此限制的值将用后缀截断。

MAX_ATTRIBUTE_LENGTH: 8192

类型

8192

defaultObservabilityConfigurationProvider

ObservabilityConfiguration 的共享默认提供程序。

defaultObservabilityConfigurationProvider: DefaultConfigurationProvider<ObservabilityConfiguration>

类型

DefaultConfigurationProvider<ObservabilityConfiguration>

defaultPerRequestSpanProcessorConfigurationProvider

PerRequestSpanProcessorConfiguration 的共享默认提供程序。

defaultPerRequestSpanProcessorConfigurationProvider: DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>

类型

DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>

logger

用于向后兼容性的默认记录器实例。 委托给可通过 setLogger（）替换的全局记录器。

logger: ILogger

类型

ILogger