@microsoft/agents-a365-observability package
类
| Agent365ExporterOptions |
控制 Agent365 OpenTelemetry 范围导出程序行为的选项。 这些值优化批处理、超时、令牌获取和终结点形状。 所有属性都具有合理的默认值,因此调用方通常可以在没有参数的情况下构造并选择性地重写。 |
| ApplyGuardrailScope |
为安全防护措施评估操作提供 OpenTelemetry 跟踪范围。 描述安全保护者评估。 如果多个监护人被链接,则多个监护人跨度可能存在于单个操作范围下。 监护人范围应该是他们保护的操作范围的孩子(例如推理或execute_tool跨度)。 |
| BaggageBuilder |
OpenTelemetry 上下文传播的每个请求行李生成器。 此类提供了一个 Fluent API,用于设置将在 OpenTelemetry 上下文中传播的行李值。 示例
|
| 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 中,该名称 请参阅 UserDetails — 人工调用方标识(以前 |
| Channel |
表示调用的通道 |
| ChatMessage |
发送到模型的输入消息(GEN-gen-ai 语义约定)。 |
| FilePart |
对预上传文件的引用。 |
| GenericPart |
自定义/将来类型的可扩展部件。 |
| GenericServerToolCall |
可扩展服务器工具调用详细信息和类型鉴别器。 |
| GenericServerToolCallResponse |
可扩展服务器工具使用类型鉴别器调用响应。 |
| GuardrailDetails |
安全操作跟踪的防护栏评估的详细信息。 |
| GuardrailFinding |
表示在监护人评估期间检测到的单个安全发现。 单个护栏跨度可能会发出多个发现。 |
| 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 |
接受的输入 。 |
| MessagePart |
每个 GEN gen-ai 语义约定的所有消息部件类型的联合。 注意: GenericPart 充当一个 catch-all,以便与自定义或将来的部件类型向前兼容。 由于它是 |
| ObservabilityConfigurationOptions |
可观测性配置选项 - 扩展运行时选项。 所有替代都是在每个属性访问上调用的函数。 继承自 RuntimeConfigurationOptions:
注意: |
| OutputMessagesParam |
接受的输入 。 |
| ParentContext |
用于跨度创建的父上下文。 接受以下任一:
|
| PerRequestSpanProcessorConfigurationOptions |
PerRequestSpanProcessor 的配置选项 - 扩展运行时选项。 所有替代都是在每个属性访问上调用的函数。 继承自 RuntimeConfigurationOptions:
|
| ResponseMessagesParam |
接受的输入 。 |
| TokenResolver |
解析给定代理和租户的仅限应用的 OBS 令牌的函数。 S2S 服务不接受委派的 (scp) 令牌。 实现可以执行同步查找(例如内存中缓存)或异步网络调用。 在批处理和按请求模式下使用,独立于工作负荷令牌上下文。 如果无法提供令牌,则返回 null;导出失败,但不发送 HTTP 请求。 |
枚举
| ExporterEventNames |
Agent365Exporter 用于日志记录和监视的事件名称。 这些是低基数事件类型,可确保高效监视和聚合。 |
| FinishReason |
模型停止为每个 一代 AI 语义约定生成的原因。 |
| GuardrailDecisionType |
安全监护人在护栏评估期间做出的决定。 |
| InferenceOperationType |
表示模型推理类型的不同作 |
| InvocationRole |
表示可以调用代理的不同角色 |
| MessageRole |
每个 GEN gen-ai 语义约定的消息参与者的角色。 |
| Modality |
Blob、文件和 URI 部件的媒体形式。 |
函数
| create |
使用显式父范围引用创建新的上下文。 这样,即使异步上下文断开,子范围也能正确进行父级。 |
| extract |
使用全局注册的 W3C 传播器从传入的 HTTP 标头中提取跟踪上下文。 返回一个 OTel,该 OTel ParentContext 可以作为 ParentContext 传递给范围类。 示例
|
| format |
使用消息和堆栈跟踪记录的格式错误对象 |
| get |
从给定的 OTel 上下文(或活动令牌)检索每个请求导出令牌。 |
| get |
获取当前记录器实例 |
| inject |
使用全局注册的 W3C 传播器将当前跟踪上下文( 示例
|
| is |
检查是否启用了每个请求导出。 优先级:内部重写 > 配置提供程序 > 环境变量。 启用后,将使用 PerRequestSpanProcessor 而不是 BatchSpanProcessor。 凭据选择保持不变:Agent365Exporter 使用其仅限应用的令牌解析程序。 |
| normalize |
规范化
|
| normalize |
规范化
|
| reset |
重置为默认控制台记录器(主要用于测试) |
| run |
在包含每个请求导出令牌的上下文中运行函数。 这仅在 OTel Context (ALS)中保留令牌,从不在任何注册表中。 这些帮助程序仍可用于自定义导出集成。 Agent365Exporter 不使用此令牌;在每个模式下配置其仅限应用的 tokenResolver。 稍后可以通过刷新跟踪之前更新 |
| run |
从传入的 HTTP 标头中提取跟踪上下文,并在该上下文中运行回调。 回调中创建的任何范围都将父级到提取的跟踪。 示例
|
| run |
在具有显式父范围引用的上下文中运行回调函数。 这对于在上下文传播中断的异步回调中创建子范围非常有用。 |
| safe |
确保该值始终是 JSON 分析的字符串。
|
| serialize |
将消息包装器序列化为 JSON。 输出是每个 OTel gen-ai 语义约定的纯 JSON 数组: try/catch 可确保即使消息部分包含非 JSON 可序列化值(例如 BigInt、循环 refs)时,遥测记录也不会引发。 |
| set |
为可观测性 SDK 设置自定义记录器实现 Winston 的示例:
|
| update |
更新活动 OTel 上下文中的导出令牌。 调用此项以在结束根范围之前刷新令牌,当原始令牌在长时间运行的请求期间可能已过期。 必须在创建 |
变量
| DEFAULT_FINISH_REASON | 如果未提供任何内容(按 OTel 规范),则应用默认完成原因。 |
| Guardrail |
防护措施检测到的安全风险的已知严重性级别。 |
| Guardrail |
应用于护栏的内容类型或操作的已知值。 也接受自定义字符串。 |
| default |
ObservabilityConfiguration 的共享默认提供程序。 |
| default |
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()
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。 凭据选择保持不变:Agent365Exporter 使用其仅限应用的令牌解析程序。
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
返回
normalizeOutputMessages(OutputMessagesParam)
规范化 OutputMessagesParam 实例 OutputMessages 。
-
string/string[]→转换为OutputMessage[]和包装 -
OutputMessages返回 as-is→
function normalizeOutputMessages(param: OutputMessagesParam): OutputMessages
参数
- param
- OutputMessagesParam
返回
resetLogger()
重置为默认控制台记录器(主要用于测试)
function resetLogger()
runWithExportToken<T>(string, () => T)
在包含每个请求导出令牌的上下文中运行函数。 这仅在 OTel Context (ALS)中保留令牌,从不在任何注册表中。 这些帮助程序仍可用于自定义导出集成。 Agent365Exporter 不使用此令牌;在每个模式下配置其仅限应用的 tokenResolver。
稍后可以通过刷新跟踪之前更新 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。
输出是每个 OTel gen-ai 语义约定的纯 JSON 数组: [{...}, ...]。
try/catch 可确保即使消息部分包含非 JSON 可序列化值(例如 BigInt、循环 refs)时,遥测记录也不会引发。
function serializeMessages(wrapper: InputMessages | OutputMessages): string
参数
- wrapper
返回
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
自定义记录器实现
updateExportToken(string)
更新活动 OTel 上下文中的导出令牌。 调用此项以在结束根范围之前刷新令牌,当原始令牌在长时间运行的请求期间可能已过期。
必须在创建 runWithExportToken相同的异步上下文中调用。
function updateExportToken(token: string): boolean
参数
- token
-
string
要用于导出的全新令牌。
返回
boolean
如果令牌已成功更新,则为 true;如果未找到令牌持有者,则为 false。
变量详细信息
DEFAULT_FINISH_REASON
如果未提供任何内容(按 OTel 规范),则应用默认完成原因。
DEFAULT_FINISH_REASON: "stop"
类型
"stop"
GuardrailRiskSeverity
防护措施检测到的安全风险的已知严重性级别。
GuardrailRiskSeverity: { Critical: "critical", High: "high", Low: "low", Medium: "medium", None: "none" }
类型
{ Critical: "critical", High: "high", Low: "low", Medium: "medium", None: "none" }
GuardrailTargetType
应用于护栏的内容类型或操作的已知值。 也接受自定义字符串。
GuardrailTargetType: { KnowledgeQuery: "knowledge_query", KnowledgeResult: "knowledge_result", LlmInput: "llm_input", LlmOutput: "llm_output", MemoryRetrieve: "memory_retrieve", MemoryStore: "memory_store", Message: "message", ToolCall: "tool_call", ToolDefinition: "tool_definition" }
类型
{ KnowledgeQuery: "knowledge_query", KnowledgeResult: "knowledge_result", LlmInput: "llm_input", LlmOutput: "llm_output", MemoryRetrieve: "memory_retrieve", MemoryStore: "memory_store", Message: "message", ToolCall: "tool_call", ToolDefinition: "tool_definition" }
defaultObservabilityConfigurationProvider
ObservabilityConfiguration 的共享默认提供程序。
defaultObservabilityConfigurationProvider: DefaultConfigurationProvider<ObservabilityConfiguration>
类型
defaultPerRequestSpanProcessorConfigurationProvider
PerRequestSpanProcessorConfiguration 的共享默认提供程序。
defaultPerRequestSpanProcessorConfigurationProvider: DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>