@microsoft/agents-a365-observability package

Maximale Anzahl von Spannen pro Exportbatch.

Gepäck-Generator pro Anforderung für die OpenTelemetry-Kontextverteilung.

Diese Klasse bietet eine Fluent-API zum Festlegen von Gepäckwerten, die im OpenTelemetry-Kontext weitergegeben werden.

Beispiel

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

Kontextmanager für Gepäckumfang.

Diese Klasse verwaltet den Lebenszyklus von Gepäckwerten, legt sie beim Betreten und Wiederherstellen des vorherigen Kontexts beim Verlassen fest.

Generator zum Konfigurieren von Agent 365 mit OpenTelemetry-Ablaufverfolgung

Stellt openTelemetry-Ablaufverfolgungsbereich für KI-Toolausführungsvorgänge bereit.

Stellt openTelemetry-Ablaufverfolgungsbereich für generative KI-Ableitungsvorgänge bereit.

Stellt den OpenTelemetry-Ablaufverfolgungsbereich für KI-Agent-Aufrufvorgänge bereit.

Konfiguration für Observability-Paket. Erbt Laufzeiteinstellungen und fügt Observability-spezifische Einstellungen hinzu.

Haupteinstiegspunkt für Agent 365, der die OpenTelemetry-Ablaufverfolgung für KI-Agents und -Tools bereitstellt

OpenTelemetry-Konstanten für Agent 365

Basisklasse für OpenTelemetry-Ablaufverfolgungsbereiche

Stellt den Bereich der OpenTelemetry-Ablaufverfolgung für die Ausgabenachrichtenablaufverfolgung mit übergeordneter Spanverknüpfung bereit.

Konfiguration für PerRequestSpanProcessor. Erbt Laufzeiteinstellungen (clusterCategory, isNodeEnvDevelopment) und fügt Prozessorschutzläufe pro Anforderung hinzu.

Dies ist von ObservabilityConfiguration getrennt, da PerRequestSpanProcessor nur in bestimmten Szenarien verwendet wird und diese Einstellungen nicht in der allgemeinen ObservabilityConfiguration verfügbar gemacht werden sollten.

Details zu einem KI-Agent

Inline-Binärdaten (base64-codiert).

Konfigurationsoptionen für Agent 365 Observability Builder

Anruferdetails für die Bereichserstellung. Unterstützt menschliche Anrufer, Agentanrufer oder beides (A2A mit einem Menschen in der Kette).

Migrationshinweis: In v1 wird der Name CallerDetails auf die identität des Anrufers (jetzt UserDetails) verwiesen. In v2 wurde sie als Wrapper umverwendet, der Informationen von Menschen- und Agentanrufern gruppiert.

Siehe UserDetails – Menschliche Anruferidentität (zuvor CallerDetails) Siehe CHANGELOG.md – Abschnitt "Änderungen unterbrechen" für Migrationsleitfaden

Stellt den Kanal für einen Aufruf dar.

Eine an ein Modell gesendete Eingabenachricht (OTEL gen-ai semantische Konventionen).

Verweisen auf eine vorab hochgeladene Datei.

Erweiterbarer Teil für benutzerdefinierte/ zukünftige Typen.

Extensible Server tool call details with a type diskriminator.

Extensible Server tool call response with a type diskriminator.

Benutzerdefinierte Loggerschnittstelle für Agent 365 Observability Implementieren Sie diese Schnittstelle zur Unterstützung von Protokollierungs-Back-Ends

Details für einen Rückschlussanruf

Details zum Aufzeichnen der Antwort von einem Rückschlussanruf

Details zum Aufrufen des Agentbereichs.

Eine Ausgabemeldung, die von einem Modell (OTEL gen-ai semantic conventions) erzeugt wird.

Stellt eine Antwort dar, die Ausgabemeldungen von einem Agent enthält. Wird zusammen mit OutputScope für die Ausgabenachrichtenablaufverfolgung verwendet. Akzeptiert einfache Zeichenfolgen, strukturierte OTEL OutputMessage-Objekte oder ein unformatiertes Diktat (behandelt als Toolaufrufergebnis pro OTEL-Spezifikation).

Verweis auf eine übergeordnete Spanne für explizite Verknüpfungen zwischen übergeordneten und untergeordneten Elementen über asynchrone Grenzen hinweg. Wird verwendet, wenn die automatische Kontextverteilung fehlschlägt (z. B. WebSocket-Rückrufe, externe Ereignishandler).

Modellieren von Begründungen /Gedankenketteninhalten.

Stellt eine Anforderung mit Telemetriekontext dar. Wird für alle Bereichstypen für die Kanal- und Unterhaltungsnachverfolgung verwendet.

Serverseitiger Toolaufruf.

Serverseitige Toolantwort.

Stellt einen Endpunkt für den Agentaufruf dar.

Umfassen Konfigurationsdetails für die Bereichserstellung. Gruppiert OpenTelemetry-Optionen in einem einzelnen Objekt, sodass die Bereichsmethodensignatur stabil bleibt, wenn neue Optionen hinzugefügt werden.

Nur-Text-Inhalt.

Details zu einem Toolaufruf, der von einem Agent getätigt wurde

Ein Vom Modell angeforderter Toolaufruf.

Ergebnis eines Toolaufrufs.

Externer URI-Verweis.

Details zum Anrufer des menschlichen Benutzers.

Trägertyp für HTTP-Header, die in der Ablaufverfolgungskontextverteilung verwendet werden. Kompatibel mit Node.js IncomingHttpHeaders und einfachen Zeichenfolgenzuordnungen.

Akzeptierte Eingabe für recordInputMessages. Unterstützt eine einzelne Zeichenfolge, ein Array von Zeichenfolgen (Abwärtskompat) oder den versionsbasierten Wrapper.

Union aller Nachrichtenteiltypen gemäß OTEL gen-ai semantischen Konventionen.

Hinweis: GenericPart fungiert als Catch-All für die Vorwärtskompatibilität mit benutzerdefinierten oder zukünftigen Teiltypen. Da es typestring sich (nicht um ein Literal) handelt, erzeugt erschöpfend switch/casepart.type keine Kompilierungszeitfehler für nicht behandelte Fälle.

Observability-Konfigurationsoptionen – erweitert Laufzeitoptionen. Alle Außerkraftsetzungen sind Funktionen, die für jeden Eigenschaftenzugriff aufgerufen werden.

Geerbt von RuntimeConfigurationOptions:

• clusterCategory
• isNodeEnvDevelopment

Hinweis: isDevelopmentEnvironment ist ein abgeleiteter Getter für die Konfigurationsklasse (basierend auf clusterCategory), keine überschreibbare Option.

Akzeptierte Eingabe für recordOutputMessages. Unterstützt eine einzelne Zeichenfolge, ein Array von Zeichenfolgen (Abwärtskompat) oder den versionsbasierten Wrapper.

Ein übergeordneter Kontext für die Span Creation. Akzeptiert entweder:

• ParentSpanRef: explizites traceId/spanId-Paar (manueller Ansatz)
• ParentContext: ein OTel-Kontext, in der Regel aus extractContextFromHeaders oder propagation.extract()

Konfigurationsoptionen für PerRequestSpanProcessor – erweitert Laufzeitoptionen. Alle Außerkraftsetzungen sind Funktionen, die für jeden Eigenschaftenzugriff aufgerufen werden.

Geerbt von RuntimeConfigurationOptions:

• clusterCategory, isNodeEnvDevelopment

Akzeptierte Eingabe für OutputResponse.messages. Unterstützt einfache Zeichenfolgen, strukturierte OutputMessages oder ein unformatiertes Diktat (behandelt als Toolaufrufergebnis pro OTEL-Spezifikation und serialisiert direkt über JSON.stringify).

Ereignisnamen, die von Agent365Exporter zur Protokollierung und Überwachung verwendet werden. Hierbei handelt es sich um Ereignistypen mit niedriger Kardinalität, um eine effiziente Überwachung und Aggregation zu gewährleisten.

Grund, warum ein Modell nicht mehr per OTEL gen-ai-Semantikkonventionen generiert wurde.

Stellt unterschiedliche Vorgänge für Typen für Modellinferenz dar.

Stellt unterschiedliche Rollen dar, die einen Agent aufrufen können

Rolle eines Nachrichtenteilnehmers gemäß OTEL gen-ai semantischen Konventionen.

Medienmodalitäten für Blob-, Datei- und URI-Teile.

Erstellt einen neuen Kontext mit einem expliziten übergeordneten Span-Bezug. Auf diese Weise können untergeordnete Abschnitte korrekt übergeordnet werden, auch wenn asynchroner Kontext unterbrochen wird.

Extrahiert den Ablaufverfolgungskontext aus eingehenden HTTP-Headern mithilfe des global registrierten W3C-Verteilungsmoduls. Gibt ein OTel ParentContext zurück, das als ParentContext an Bereichsklassen übergeben werden kann.

Beispiel

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

Formatieren des Fehlerobjekts für die Protokollierung mit Nachrichten- und Stapelablaufverfolgung

Abrufen des Exporttokens pro Anforderung aus einem bestimmten OTel-Kontext (oder dem aktiven).

Abrufen der aktuellen Loggerinstanz

Fügt den aktuellen Ablaufverfolgungskontext (traceparent/tracestate Header) mithilfe des global registrierten W3C-Verteilungsobjekts in das bereitgestellte Headerobjekt ein.

Beispiel

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

Überprüfen Sie, ob der Export pro Anforderung aktiviert ist. Rangfolge: Interne Außerkraftsetzungen der Umgebungsvariable des Konfigurationsanbieters >> . Wenn diese Option aktiviert ist, wird der PerRequestSpanProcessor anstelle von BatchSpanProcessor verwendet. Das Token wird zur Exportzeit über OTel Context (asynchroner lokaler Speicher) übergeben.

Normalisiert einen InputMessagesParam in einen versionsierten InputMessages Wrapper.

• string / string[] → in ChatMessage[] konvertiert und umschlossen
• InputMessages → as-is zurückgegeben

Normalisiert einen OutputMessagesParam in einen versionsierten OutputMessages Wrapper.

• string / string[] → in OutputMessage[] konvertiert und umschlossen
• OutputMessages → as-is zurückgegeben

Zurücksetzen auf den Standardkonsolenlogger (hauptsächlich für Tests)

Führen Sie eine Funktion innerhalb eines Kontexts aus, der das Exporttoken pro Anforderung enthält. Dadurch wird das Token nur in OTel Context (ALS) beibehalten, nie in einer Registrierung.

Das Token kann später aktualisiert updateExportToken() werden, bevor die Ablaufverfolgung geleert wird – nützlich, wenn der Rückruf lange ausgeführt wird und das ursprüngliche Token vor dem Export abläuft.

Extrahiert den Ablaufverfolgungskontext aus eingehenden HTTP-Headern und führt den Rückruf innerhalb dieses Kontexts aus. Alle innerhalb des Rückrufs erstellten Spans werden der extrahierten Ablaufverfolgung übergeordnet.

Beispiel

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

Führt eine Rückruffunktion in einem Kontext aus, der einen expliziten übergeordneten Span-Bezug aufweist. Dies ist nützlich, um untergeordnete Abschnitte in asynchronen Rückrufen zu erstellen, bei denen die Kontextverteilung unterbrochen ist.

Stellt sicher, dass der Wert immer eine JSON-parseable Zeichenfolge ist.

• Objekte werden über JSON.stringify serialisiert.
• Zeichenfolgen, die bereits gültige JSON-Objekte/Arrays sind, werden übergeben.
• Alle anderen Zeichenfolgen (einschließlich bare JSON-Grundtypen) werden umschlossen: { [key]: value }.

Serialisiert einen versionsierten Nachrichtenwrapper in JSON.

Die Ausgabe ist das vollständige Wrapperobjekt: {"version":"0.1.0","messages":[...]}.

Der Try/Catch stellt sicher, dass die Telemetrieaufzeichnung nicht ausgelöst wird, auch wenn Nachrichtenteile nicht-JSON-serialisierbare Werte enthalten (z. B. BigInt, Zirkelverweisen).

Festlegen einer benutzerdefinierten Loggerimplementierung für das Observability SDK

Beispiel mit 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 });
  }
});

Kürzen Sie einen Zeichenfolgenwert auf MAX_ATTRIBUTE_LENGTH Zeichen. Wenn der Wert den Grenzwert überschreitet, wird er gekürzt und ein Abkürzungssuffix angefügt, wobei die Gesamtlänge bei genau MAX_ATTRIBUTE_LENGTH begrenzt ist.

Aktualisieren Sie das Exporttoken im aktiven OTel-Kontext. Rufen Sie das Token auf, um das Token zu aktualisieren, bevor die Stammspanne beendet wird, wenn das ursprüngliche Token möglicherweise während einer langen Anforderung abgelaufen ist.

Muss innerhalb desselben asynchronen Kontexts aufgerufen werden, der von runWithExportToken.

Maximale Länge für Span-Attributwerte. Werte, die diesen Grenzwert überschreiten, werden mit einem Suffix abgeschnitten.

Freigegebener Standardanbieter für ObservabilityConfiguration.

Freigegebener Standardanbieter für PerRequestSpanProcessorConfiguration.

Standardprotokollierinstanz für Abwärtskompatibilität. Delegiert an den globalen Logger, der über setLogger() ersetzt werden kann.