@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	Построитель для настройки агента 365 с помощью трассировки OpenTelemetry
ExecuteToolScope	Предоставляет область трассировки OpenTelemetry для операций выполнения средства ИИ.
InferenceScope	Предоставляет область трассировки OpenTelemetry для операций вывода с помощью искусственного интеллекта.
InvokeAgentScope	Предоставляет область трассировки OpenTelemetry для операций вызова агента ИИ.
ObservabilityConfiguration	Конфигурация пакета наблюдаемости. Наследует параметры среды выполнения и добавляет параметры, относящиеся к наблюдаемости.
ObservabilityManager	Основная точка входа для агента 365, обеспечивающая трассировку OpenTelemetry для агентов и средств ИИ
OpenTelemetryConstants	Константы OpenTelemetry для агента 365
OpenTelemetryScope	Базовый класс для областей трассировки OpenTelemetry
OutputScope	Предоставляет область трассировки OpenTelemetry для трассировки выходных сообщений с привязкой родительского диапазона.
PerRequestSpanProcessorConfiguration	Конфигурация perRequestSpanProcessor. Наследует параметры среды выполнения (clusterCategory, isNodeEnvDevelopment) и добавляет средства защиты процессора для каждого запроса. Это отличается от ObservabilityConfiguration, так как PerRequestSpanProcessor используется только в определенных сценариях, и эти параметры не должны предоставляться в common ObservabilityConfiguration.

Интерфейсы

AgentDetails	Сведения об агенте ИИ
BlobPart	Встроенные двоичные данные (в кодировке Base64).
BuilderOptions	Параметры конфигурации для построителя наблюдаемости агента 365
CallerDetails	Сведения о вызывающем объекте для создания области. Поддерживает вызывающих людей, вызывающих агентов или обоих (A2A с человеком в цепочке). Примечание по миграции: В версии 1 имя `CallerDetails` называется удостоверением вызывающего человека (теперь UserDetails). В версии 2 она была перепрофилирована как оболочка, которая группируют сведения о вызывающих пользователях и агентах. См. раздел UserDetails — удостоверение вызывающего человека (ранее `CallerDetails`) См. CHANGELOG.md — раздел о критических изменениях для руководства по миграции
Channel	Представляет канал для вызова
ChatMessage	Входное сообщение, отправленное модели (соглашения о семантике OTEL-gen-ai).
FilePart	Ссылка на предварительно отправленный файл.
GenericPart	Расширяемая часть для пользовательских или будущих типов.
GenericServerToolCall	Подробные сведения о вызове средства расширяемого сервера с дискриминационным типом.
GenericServerToolCallResponse	Ответ на вызов расширяемого сервера с дискриминационным типом.
ILogger	Пользовательский интерфейс средства ведения журнала для наблюдаемости агента 365 реализует этот интерфейс для поддержки внутренних серверных служб ведения журнала
InferenceDetails	Сведения о вызове вывода
InferenceResponse	Сведения о записи ответа из вызова вывода
InputMessages
InvokeAgentScopeDetails	Сведения о вызове области агента.
OutputMessage	Выходное сообщение, созданное моделью (соглашения о семантике OTEL gen-ai).
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 входящегоhttpHeaders и картой простых строк.
InputMessagesParam	Принятые входные данные для `recordInputMessages`. Поддерживает одну строку, массив строк (обратную compat) или версию оболочки.
MessagePart	Объединение всех типов частей сообщений на семантические соглашения OTEL gen-ai. Примечание. GenericPart выступает в качестве catch-all для обеспечения совместимости с пользовательскими или будущими типами частей. Так как он `type` является `string` (не литеральным), исчерпывающий`switch`/`case` не `part.type` будет создавать ошибки во время компиляции для необработанных случаев.
ObservabilityConfigurationOptions	Параметры конфигурации наблюдаемости — расширяет параметры среды выполнения. Все переопределения — это функции, вызываемые для каждого доступа к свойствам. Наследуется от RuntimeConfigurationOptions: clusterCategory isNodeEnvDevelopment Примечание. `isDevelopmentEnvironment` Является производным методом получения класса конфигурации (на основе clusterCategory), а не переопределения.
OutputMessagesParam	Принятые входные данные для `recordOutputMessages`. Поддерживает одну строку, массив строк (обратную compat) или версию оболочки.
ParentContext	Родительский контекст для создания диапазона. Принимает любую из них: ParentSpanRef: явная пара traceId/spanId (подход вручную) ParentContext: контекст OTel, обычно из extractContextFromHeaders или `propagation.extract()`
PerRequestSpanProcessorConfigurationOptions	Параметры конфигурации для PerRequestSpanProcessor — расширяют параметры среды выполнения. Все переопределения — это функции, вызываемые для каждого доступа к свойствам. Наследуется от RuntimeConfigurationOptions: clusterCategory, isNodeEnvDevelopment
ResponseMessagesParam	Принятые входные данные для `OutputResponse.messages`. Поддерживает обычные строки, структурированные outputMessagesages или необработанный дикт (обработанный как результат вызова средства для спецификации OTEL и сериализованный непосредственно через JSON.stringify).

Перечисления

ExporterEventNames	Имена событий, используемые агентом 365Exporter для ведения журнала и мониторинга. Это типы событий с низкой кратностью для обеспечения эффективного мониторинга и агрегирования.
FinishReason	Причина, по которой модель перестала создаваться на основе соглашений о семантике OTEL-го поколения.
InferenceOperationType	Представляет различные операции для типов вывода модели
InvocationRole	Представляет различные роли, которые могут вызывать агент
MessageRole	Роль участника сообщения на семантические соглашения OTEL gen-ai.
Modality	Модальность мультимедиа для частей BLOB-объектов, файлов и URI.

Функции

createContextWithParentSpanRef(Context, ParentSpanRef)	Создает новый контекст с явной ссылкой на родительский диапазон. Это позволяет правильно создавать дочерние диапазоны даже при разрыве асинхронного контекста.
extractContextFromHeaders(HeadersCarrier, Context)	Извлекает контекст трассировки из входящих заголовков HTTP с помощью глобально зарегистрированного распространителя W3C. Возвращает 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)	Внедряет текущий контекст трассировки (`traceparent`/`tracestate` заголовки) в предоставленный объект заголовков с помощью глобально зарегистрированного распространителя W3C. Пример `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 гарантирует, что запись телеметрии не вызывается, даже если части сообщения содержат несериализируемые значения (например, BigInt, циклические ссылки).
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 }); } });
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)

Извлекает контекст трассировки из входящих заголовков HTTP с помощью глобально зарегистрированного распространителя W3C. Возвращает 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

Входящие заголовки HTTP-запроса, traceparent/tracestateсодержащие .

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)

Внедряет текущий контекст трассировки (traceparent/tracestate заголовки) в предоставленный объект заголовков с помощью глобально зарегистрированного распространителя W3C.

Пример

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

Возвращаемое значение

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

Входящие заголовки HTTP-запроса, traceparent/tracestateсодержащие .

callback: () => T

Функция, выполняемая в извлеченном контексте.

Возвращаемое значение

Результат обратного вызова.

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

Выполняет функцию обратного вызова в контексте с явной ссылкой на родительский диапазон. Это полезно для создания дочерних диапазонов в асинхронных обратных вызовах, где распространение контекста нарушается.

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

Параметры

parent: ParentSpanRef

Ссылка на родительский диапазон

callback: () => 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 гарантирует, что запись телеметрии не вызывается, даже если части сообщения содержат несериализируемые значения (например, BigInt, циклические ссылки).

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

Реализация пользовательского средства ведения журнала

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