@microsoft/agents-a365-observability package

Třídy

Agent365ExporterOptions

Maximální počet rozsahů na dávku exportu
BaggageBuilder

Podle požadavku tvůrce zavazadel pro šíření kontextu OpenTelemetry.

Tato třída poskytuje plynulé rozhraní API pro nastavení hodnot zavazadel, které se rozšíří v kontextu OpenTelemetry.

Příklad

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

Kontextový manažer pro rozsah zavazadel.

Tato třída spravuje životní cyklus hodnot zavazadel a nastavuje je při zadávání a obnovování předchozího kontextu při ukončení.
Builder

Tvůrce pro konfiguraci agenta 365 s trasováním OpenTelemetry
ExecuteToolScope

Poskytuje rozsah trasování OpenTelemetry pro operace provádění nástrojů AI.
InferenceScope

Poskytuje rozsah trasování OpenTelemetry pro operace odvozování generující AI.
InvokeAgentScope

Poskytuje rozsah trasování OpenTelemetry pro operace vyvolání agenta AI.
ObservabilityConfiguration

Konfigurace pro balíček pozorovatelnosti Dědí nastavení modulu runtime a přidává nastavení specifická pro pozorovatelnost.
ObservabilityManager

Hlavní vstupní bod pro agenta 365 poskytující trasování OpenTelemetry pro agenty a nástroje AI
OpenTelemetryConstants

Konstanty OpenTelemetry pro agenta 365
OpenTelemetryScope

Základní třída pro obory trasování OpenTelemetry
OutputScope

Poskytuje rozsah trasování OpenTelemetry pro trasování výstupních zpráv s propojením nadřazeného rozsahu.
PerRequestSpanProcessorConfiguration

Konfigurace pro PerRequestSpanProcessor Dědí nastavení modulu runtime (clusterCategory, isNodeEnvDevelopment) a přidá mantinely procesoru pro jednotlivé požadavky.

To je oddělené od ObservabilityConfiguration, protože PerRequestSpanProcessor se používá pouze v konkrétních scénářích a tato nastavení by neměla být vystavena v common ObservabilityConfiguration.

Rozhraní

AgentDetails

Podrobnosti o agentu AI
BlobPart

Vložená binární data (kódování base64)
BuilderOptions

Možnosti konfigurace pro Tvůrce pozorovatelnosti agenta 365
CallerDetails

Podrobnosti o volajícím pro vytvoření oboru Podporuje lidské volající, volající agenty nebo obojí (A2A s člověkem v řetězci).

Poznámka k migraci: V1 se název CallerDetails odkazuje na identitu člověka volajícího (nyní UserDetails). Ve verzi 2 byl znovu navrhován jako obálka, která seskupuje informace o volajícím člověka i agenta.

Pokyny k migraci najdete v části UserDetails – identita volajícího člověka (dříve CallerDetails) – viz část CHANGELOG.md – zásadní změny
Channel

Představuje kanál pro vyvolání.
ChatMessage

Vstupní zpráva odeslaná do modelu (sémantické konvence OTEL gen-ai).
FilePart

Odkaz na předem nahraný soubor
GenericPart

Rozšiřitelná část pro vlastní nebo budoucí typy.
GenericServerToolCall

Podrobnosti volání rozšiřitelného nástroje serveru s diskriminátorem typu.
GenericServerToolCallResponse

Rozšiřitelná odezva volání nástroje serveru s typem diskriminátoru.
ILogger

Vlastní protokolovací rozhraní pro pozorovatelnost agenta 365 Implementujte toto rozhraní pro podporu back-endů protokolování.
InferenceDetails

Podrobnosti volání odvozování
InferenceResponse

Podrobnosti o záznamu odpovědi z volání odvozování
InputMessages
InvokeAgentScopeDetails

Podrobnosti o vyvolání oboru agenta
OutputMessage

Výstupní zpráva vytvořená modelem (sémantické konvence OTEL Gen-ai).
OutputMessages
OutputResponse

Představuje odpověď obsahující výstupní zprávy z agenta. Používá se s OutputScope pro trasování výstupních zpráv. Přijímá prosté řetězce, strukturované objekty OTEL OutputMessage nebo nezpracovaný dikt (považuje se za výsledek volání nástroje podle specifikace OTEL).
ParentSpanRef

Odkaz na nadřazené rozpětí pro explicitní propojení nadřazeného-podřízeného propojení přes asynchronní hranice. Používá se při selhání automatického šíření kontextu (např. zpětné volání protokolu WebSocket, obslužné rutiny externích událostí).
ReasoningPart

Modelování / řetěz myšlenkový obsah
Request

Představuje požadavek s kontextem telemetrie. Používá se napříč všemi typy oborů pro sledování kanálů a konverzací.
ServerToolCallPart

Vyvolání nástroje na straně serveru
ServerToolCallResponsePart

Odezva nástroje na straně serveru
ServiceEndpoint

Představuje koncový bod pro vyvolání agenta.
SpanDetails

Podrobnosti konfigurace rozsahu pro vytvoření oboru. Seskupí možnosti rozsahu OpenTelemetry do jednoho objektu, takže podpis metody oboru zůstane stabilní při přidání nových možností.
TextPart

Obsah ve formátu prostého textu
ToolCallDetails

Podrobnosti o volání nástroje provedeného agentem
ToolCallRequestPart

Volání nástroje požadované modelem
ToolCallResponsePart

Výsledek volání nástroje
UriPart

Referenční informace k externímu identifikátoru URI
UserDetails

Podrobnosti o volajícím člověka

Aliasy typu

EnhancedAgentDetails
HeadersCarrier

Typ operátora pro hlavičky HTTP používané v šíření kontextu trasování. Kompatibilní s Node.js IncomingHttpHeaders a mapami prostých řetězců.
InputMessagesParam

Přijatý vstup pro recordInputMessages. Podporuje jeden řetězec, pole řetězců (zpětně kompat) nebo obálku s verzí.
MessagePart

Sjednocení všech typů částí zpráv na sémantické konvence OTEL gen-ai.

Poznámka: GenericPart funguje jako zachytávání pro zajištění kompatibility s vlastními nebo budoucími typy částí. Vzhledem k tomu, že se jedná typestring o literál ( nikoli literál), nevytváří vyčerpávající switch/casepart.type informace o chybách v době kompilace pro neošetřené případy.
ObservabilityConfigurationOptions

Možnosti konfigurace pozorovatelnosti – rozšiřuje možnosti modulu runtime. Všechny přepsání jsou funkce volané pro každý přístup k vlastnostem.

Zděděno z modulu RuntimeConfigurationOptions:

  • clusterCategory
  • isNodeEnvDevelopment

Poznámka: isDevelopmentEnvironment je odvozený getter třídy konfigurace (na základě clusterCategory), nikoli přepisovatelné možnosti.
OutputMessagesParam

Přijatý vstup pro recordOutputMessages. Podporuje jeden řetězec, pole řetězců (zpětně kompat) nebo obálku s verzí.
ParentContext

Nadřazený kontext pro vytvoření rozsahu Přijímá buď:
PerRequestSpanProcessorConfigurationOptions

Možnosti konfigurace pro PerRequestSpanProcessor – rozšiřuje možnosti modulu runtime. Všechny přepsání jsou funkce volané pro každý přístup k vlastnostem.

Zděděno z modulu RuntimeConfigurationOptions:

  • clusterCategory, isNodeEnvDevelopment
ResponseMessagesParam

Přijatý vstup pro OutputResponse.messages. Podporuje prosté řetězce, strukturované outputMessages nebo nezpracované diktování (považuje se za výsledek volání nástroje na specifikaci OTEL a serializován přímo prostřednictvím JSON.stringify).

Výčty

ExporterEventNames

Názvy událostí používané agentem Agent365Exporter pro protokolování a monitorování Jedná se o typy událostí s nízkou kardinalitou, které zajišťují efektivní monitorování a agregaci.
FinishReason

Důvod, proč se model přestal generovat podle sémantických konvencí OTEL Gen-ai
InferenceOperationType

Představuje různé operace pro typy odvození modelu.
InvocationRole

Představuje různé role, které můžou vyvolat agenta.
MessageRole

Role účastníka zprávy na sémantické konvence OTEL Gen-ai
Modality

Způsob média pro části objektu blob, souboru a identifikátoru URI

Funkce

createContextWithParentSpanRef(Context, ParentSpanRef)

Vytvoří nový kontext s explicitním odkazem na rozsah nadřazeného rozsahu. To umožňuje, aby podřízené rozsahy byly správně nadřazené i v případě, že je přerušen asynchronní kontext.
extractContextFromHeaders(HeadersCarrier, Context)

Extrahuje kontext trasování z příchozích hlaviček HTTP pomocí globálně registrovaného šíření W3C. Vrátí objekt OTel ParentContext , který lze předat do tříd oboru jako ParentContext.

Příklad

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

Formátování objektu chyby pro protokolování pomocí trasování zpráv a zásobníku
getExportToken(Context)

Načtěte token exportu pro jednotlivé požadavky z daného kontextu OTel (nebo aktivního tokenu).
getLogger()

Získání aktuální instance loggeru
injectContextToHeaders(Record<string, string>, Context)

Vloží aktuální kontext trasování (traceparent/tracestate hlavičky) do zadaného objektu záhlaví pomocí globálně registrovaného šíření W3C.

Příklad

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

Zkontrolujte, jestli je povolený export jednotlivých požadavků. Priorita: Vnitřní přepsání > proměnné prostředí zprostředkovatele > konfigurace. Pokud je tato možnost povolená, použije se místo BatchSpanProcessor PerRequestSpanProcessor. Token se předává prostřednictvím OTel Context (asynchronní místní úložiště) v době exportu.
normalizeInputMessages(InputMessagesParam)

Normalizuje obálku InputMessagesParam s verzí InputMessages .

  • string / string[] → převedeny na ChatMessage[] a zabalené
  • InputMessages → vrácená as-is
normalizeOutputMessages(OutputMessagesParam)

Normalizuje obálku OutputMessagesParam s verzí OutputMessages .

  • string / string[] → převedeny na OutputMessage[] a zabalené
  • OutputMessages → vrácená as-is
resetLogger()

Resetování výchozího protokolovacího nástroje konzoly (hlavně pro testování)
runWithExportToken<T>(string, () => T)

Spusťte funkci v kontextu, která nese token exportu pro jednotlivé požadavky. Tím se token zachová jenom v alS (OTel Context), nikdy v žádném registru.

Token lze později aktualizovat před updateExportToken() vyprázdněním trasování – užitečné, pokud je zpětné volání dlouhotrvající a původní token může před exportem vypršet.
runWithExtractedTraceContext<T>(HeadersCarrier, () => T)

Extrahuje kontext trasování z příchozích hlaviček HTTP a spustí zpětné volání v tomto kontextu. Všechny rozsahy vytvořené uvnitř zpětného volání budou nadřazené extrahovanému trasování.

Příklad

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

Spustí funkci zpětného volání v kontextu s explicitním odkazem na nadřazené rozsahy. To je užitečné při vytváření podřízených rozsahů v asynchronních zpětných voláních, kde je šíření kontextu přerušeno.
safeSerializeToJson(string | Record<string, unknown>, string)

Zajišťuje, že hodnota je vždy řetězec, který je možné analyzovat ve formátu JSON.

  • Objekty jsou serializovány prostřednictvím JSON.stringify.
  • Řetězce, které už jsou platné objekty a pole JSON, se předávají.
  • Všechny ostatní řetězce (včetně holých primitiv JSON) jsou zabalené: { [key]: value }.
serializeMessages(InputMessages | OutputMessages)

Serializuje obálku zpráv s verzí do formátu JSON.

Výstupem je celý objekt obálky: {"version":"0.1.0","messages":[...]}.

Try/catch zajišťuje, že se záznam telemetrie nevyvolá, i když části zprávy obsahují hodnoty, které se nedají serializovat (např. BigInt, kruhové odkazy).
setLogger(ILogger)

Nastavení vlastní implementace protokolovacího nástroje pro sadu SDK pozorovatelnosti

Příklad s Winstonem:

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)

Aktualizujte token exportu v aktivním kontextu OTel. Voláním tohoto příkazu aktualizujte token před ukončením kořenového rozsahu, když původní token mohl vypršen během dlouhotrvajícího požadavku.

Musí být volána ve stejném asynchronním kontextu vytvořeném uživatelem runWithExportToken.

Proměnné

A365_MESSAGE_SCHEMA_VERSION
defaultObservabilityConfigurationProvider

Sdílený výchozí zprostředkovatel pro ObservabilityConfiguration.
defaultPerRequestSpanProcessorConfigurationProvider

Sdílený výchozí zprostředkovatel pro PerRequestSpanProcessorConfiguration.
logger

Výchozí instance protokolovacího modulu pro zpětnou kompatibilitu Delegáti na globální protokolovací nástroj, který lze nahradit pomocí setLogger().

Podrobnosti funkce

createContextWithParentSpanRef(Context, ParentSpanRef)

Vytvoří nový kontext s explicitním odkazem na rozsah nadřazeného rozsahu. To umožňuje, aby podřízené rozsahy byly správně nadřazené i v případě, že je přerušen asynchronní kontext.

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

Parametry

base

Context

Základní kontext, který se má rozšířit (obvykle context.active())

parent
ParentSpanRef

Odkaz nadřazeného rozsahu obsahující traceId a spanId

Návraty

Context

Nový kontext se sadou nadřazeného rozsahu

extractContextFromHeaders(HeadersCarrier, Context)

Extrahuje kontext trasování z příchozích hlaviček HTTP pomocí globálně registrovaného šíření W3C. Vrátí objekt OTel ParentContext , který lze předat do tříd oboru jako ParentContext.

Příklad

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

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

Parametry

headers
HeadersCarrier

Hlavičky příchozího požadavku HTTP obsahující traceparent/tracestate.

baseCtx

Context

Volitelný základní kontext, který chcete rozšířit. Výchozí hodnota je aktivní kontext.

Návraty

Context

Kontext objektu OTel obsahující extrahované informace o trasování.

formatError(unknown)

Formátování objektu chyby pro protokolování pomocí trasování zpráv a zásobníku

function formatError(error: unknown): string

Parametry

error

unknown

Návraty

string

getExportToken(Context)

Načtěte token exportu pro jednotlivé požadavky z daného kontextu OTel (nebo aktivního tokenu).

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

Parametry

ctx

Context

Návraty

string | undefined

getLogger()

Získání aktuální instance loggeru

function getLogger(): ILogger

Návraty

ILogger

injectContextToHeaders(Record<string, string>, Context)

Vloží aktuální kontext trasování (traceparent/tracestate hlavičky) do zadaného objektu záhlaví pomocí globálně registrovaného šíření W3C.

Příklad

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>

Parametry

headers

Record<string, string>

Proměnlivý objekt, kde se zapíšou záhlaví kontextu trasování.

ctx

Context

Volitelný kontext objektu OTel, ze které se má vložit. Výchozí hodnota je aktivní kontext.

Návraty

Record<string, string>

Stejný headers objekt pro zřetězování.

isPerRequestExportEnabled(IConfigurationProvider<PerRequestSpanProcessorConfiguration>)

Zkontrolujte, jestli je povolený export jednotlivých požadavků. Priorita: Vnitřní přepsání > proměnné prostředí zprostředkovatele > konfigurace. Pokud je tato možnost povolená, použije se místo BatchSpanProcessor PerRequestSpanProcessor. Token se předává prostřednictvím OTel Context (asynchronní místní úložiště) v době exportu.

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

Parametry

configProvider

IConfigurationProvider<PerRequestSpanProcessorConfiguration>

Volitelný zprostředkovatel konfigurace Výchozí hodnota je defaultPerRequestSpanProcessorConfigurationProvider, pokud není zadána.

Návraty

boolean

normalizeInputMessages(InputMessagesParam)

Normalizuje obálku InputMessagesParam s verzí InputMessages .

  • string / string[] → převedeny na ChatMessage[] a zabalené
  • InputMessages → vrácená as-is
function normalizeInputMessages(param: InputMessagesParam): InputMessages

Parametry

param
InputMessagesParam

Návraty

InputMessages

normalizeOutputMessages(OutputMessagesParam)

Normalizuje obálku OutputMessagesParam s verzí OutputMessages .

  • string / string[] → převedeny na OutputMessage[] a zabalené
  • OutputMessages → vrácená as-is
function normalizeOutputMessages(param: OutputMessagesParam): OutputMessages

Parametry

param
OutputMessagesParam

Návraty

OutputMessages

resetLogger()

Resetování výchozího protokolovacího nástroje konzoly (hlavně pro testování)

function resetLogger()

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

Spusťte funkci v kontextu, která nese token exportu pro jednotlivé požadavky. Tím se token zachová jenom v alS (OTel Context), nikdy v žádném registru.

Token lze později aktualizovat před updateExportToken() vyprázdněním trasování – užitečné, pokud je zpětné volání dlouhotrvající a původní token může před exportem vypršet.

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

Parametry

token

string

fn

() => T

Návraty

T

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

Extrahuje kontext trasování z příchozích hlaviček HTTP a spustí zpětné volání v tomto kontextu. Všechny rozsahy vytvořené uvnitř zpětného volání budou nadřazené extrahovanému trasování.

Příklad

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

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

Parametry

headers
HeadersCarrier

Hlavičky příchozího požadavku HTTP obsahující traceparent/tracestate.

callback

() => T

Funkce, která se má provést v extrahovaném kontextu.

Návraty

T

Výsledek zpětného volání.

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

Spustí funkci zpětného volání v kontextu s explicitním odkazem na nadřazené rozsahy. To je užitečné při vytváření podřízených rozsahů v asynchronních zpětných voláních, kde je šíření kontextu přerušeno.

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

Parametry

parent
ParentSpanRef

Referenční dokumentace nadřazeného rozsahu

callback

() => T

Funkce, která se má provést s nadřazeným kontextem

Návraty

T

Výsledek zpětného volání

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

Zajišťuje, že hodnota je vždy řetězec, který je možné analyzovat ve formátu JSON.

  • Objekty jsou serializovány prostřednictvím JSON.stringify.
  • Řetězce, které už jsou platné objekty a pole JSON, se předávají.
  • Všechny ostatní řetězce (včetně holých primitiv JSON) jsou zabalené: { [key]: value }.
function safeSerializeToJson(value: string | Record<string, unknown>, key: string): string

Parametry

value

string | Record<string, unknown>

Hodnota k serializaci.

key

string

Klíč, který se má použít při zabalení prostého řetězce.

Návraty

string

serializeMessages(InputMessages | OutputMessages)

Serializuje obálku zpráv s verzí do formátu JSON.

Výstupem je celý objekt obálky: {"version":"0.1.0","messages":[...]}.

Try/catch zajišťuje, že se záznam telemetrie nevyvolá, i když části zprávy obsahují hodnoty, které se nedají serializovat (např. BigInt, kruhové odkazy).

function serializeMessages(wrapper: InputMessages | OutputMessages): string

Parametry

wrapper

InputMessages | OutputMessages

Návraty

string

setLogger(ILogger)

Nastavení vlastní implementace protokolovacího nástroje pro sadu SDK pozorovatelnosti

Příklad s Winstonem:

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)

Parametry

customLogger
ILogger

Implementace vlastního protokolovacího nástroje

updateExportToken(string)

Aktualizujte token exportu v aktivním kontextu OTel. Voláním tohoto příkazu aktualizujte token před ukončením kořenového rozsahu, když původní token mohl vypršen během dlouhotrvajícího požadavku.

Musí být volána ve stejném asynchronním kontextu vytvořeném uživatelem runWithExportToken.

function updateExportToken(token: string): boolean

Parametry

token

string

Nový token, který se má použít pro export.

Návraty

boolean

true Pokud byl token úspěšně aktualizován, nepravda, pokud nebyl nalezen žádný držitel tokenu.

Podrobnosti proměnné

A365_MESSAGE_SCHEMA_VERSION 

A365_MESSAGE_SCHEMA_VERSION: "0.1.0"

Typ

string

defaultObservabilityConfigurationProvider

Sdílený výchozí zprostředkovatel pro ObservabilityConfiguration.

defaultObservabilityConfigurationProvider: DefaultConfigurationProvider<ObservabilityConfiguration>

Typ

DefaultConfigurationProvider<ObservabilityConfiguration>

defaultPerRequestSpanProcessorConfigurationProvider

Sdílený výchozí zprostředkovatel pro PerRequestSpanProcessorConfiguration.

defaultPerRequestSpanProcessorConfigurationProvider: DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>

Typ

DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>

logger

Výchozí instance protokolovacího modulu pro zpětnou kompatibilitu Delegáti na globální protokolovací nástroj, který lze nahradit pomocí setLogger().

logger: ILogger

Typ

ILogger