@microsoft/agents-a365-observability package

Maksimalt antal span pr. eksportbatch.

Per anmodning bagage builder for OpenTelemetry kontekstoverførsel.

Denne klasse indeholder en flydende API til angivelse af bagageværdier, der overføres i OpenTelemetry-konteksten.

Eksempel

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

Kontekstadministrator for bagageomfang.

Denne klasse administrerer livscyklussen for bagageværdier, angiver dem ved indsejling og gendanner den tidligere kontekst ved afslutning.

Generator til konfiguration af Agent 365 med OpenTelemetry-sporing

Leverer sporingsområde for OpenTelemetry for handlinger til udførelse af AI-værktøjer.

Leverer OpenTelemetry-sporingsområde for generative AI-inferenshandlinger.

Leverer sporingsområdet for OpenTelemetry for aktiveringshandlinger for AI-agenten.

Konfiguration af observability-pakke. Arver kørselsindstillinger og tilføjer observability-specifikke indstillinger.

Hovedindtastningspunkt for Agent 365, der leverer OpenTelemetry-sporing for AI-agenter og -værktøjer

OpenTelemetry-konstanter for Agent 365

Basisklasse for OpenTelemetry-sporingsområder

Leverer sporingsområdet for OpenTelemetry for sporing af outputmeddelelser med overordnet span linking.

Konfiguration af PerRequestSpanProcessor. Nedarver kørselsindstillinger (clusterCategory, isNodeEnvDevelopment) og tilføjer processorgardelister pr. anmodning.

Dette er adskilt fra ObservabilityConfiguration, fordi PerRequestSpanProcessor kun bruges i bestemte scenarier, og disse indstillinger bør ikke vises i den almindelige ObservabilityConfiguration.

Oplysninger om en AI-agent

Indbyggede binære data (base64-kodet).

Konfigurationsindstillinger for Agent 365 Observability Builder

Oplysninger om opkald til oprettelse af område. Understøtter personopkald, agentopkald eller begge dele (A2A med et menneske i kæden).

Migreringsnote: I v1 refereres navnet CallerDetails til identiteten for den person, der ringer op (nu UserDetails). I v2 blev det genbrugt som en ombryder, der grupperer både oplysninger om person- og agentopkald.

Se UserDetails – identitet for den person, der ringer op (tidligere CallerDetails) Se afsnittet CHANGELOG.md – banebrydende ændringer for at få vejledning til migrering

Repræsenterer kanal for en aktivering

En inputmeddelelse, der er sendt til en model (OTEL gen-ai semantiske konventioner).

Reference til en fil, der allerede er uploadet.

Del, der kan udvides, for brugerdefinerede/fremtidige typer.

Oplysninger om viderestillede serverværktøjskald med en typediskriminator.

Svar på serverværktøjskald, der kan udvides, med en typediskriminator.

Brugerdefineret logføringsgrænseflade til Agent 365-observabilitet Implementer denne grænseflade for at understøtte logføring af backends

Oplysninger om et afledningskald

Oplysninger om optagelse af svaret fra et inferensopkald

Oplysninger om aktivering af agentomfang.

En outputmeddelelse, der er produceret af en model (OTEL gen-ai semantiske konventioner).

Repræsenterer et svar, der indeholder outputmeddelelser fra en agent. Bruges sammen med OutputScope til sporing af outputmeddelelser. Accepterer almindelige strenge, strukturerede OTEL OutputMessage-objekter eller et råt dikt (behandles som et værktøjskaldsresultat pr. OTEL-specifikation).

Reference til et overordnet interval for eksplicit overordnet/underordnet-sammenkædning på tværs af asynkrone grænser. Bruges, når automatisk kontekstoverførsel mislykkes (f.eks. WebSocket-tilbagekald, eksterne hændelseshandlere).

Model ræsonnering/kæde af tankeindhold.

Repræsenterer en anmodning med telemetrikontekst. Bruges på tværs af alle områdetyper til kanal- og samtalesporing.

Aktivering af værktøj på serversiden.

Svar på værktøj på serversiden.

Repræsenterer et slutpunkt for agentaktivering

Detaljer om konfiguration af omfang for oprettelse af område. Grupper OpenTelemetry spænder over indstillingerne i et enkelt objekt, så signaturen for områdemetoden forbliver stabil, efterhånden som der tilføjes nye indstillinger.

Indhold i almindelig tekst.

Oplysninger om et værktøjskald foretaget af en agent

Et værktøjskald, som modellen har anmodet om.

Resultatet af et værktøjskald.

Ekstern URI-reference.

Oplysninger om den person, der ringer op.

Bæretype for HTTP-headere, der bruges i overførsel af sporingskontekst. Kompatibel med Node.js IndgåendeHttpHeaders og almindelige strengkort.

Accepteret input for recordInputMessages. Understøtter en enkelt streng, en matrix af strenge (bagudkompat) eller den versionerede ombrydning.

Samling af alle meddelelsesdelstyper pr. OTEL gen-ai semantiske konventioner.

Bemærk! GenericPart fungerer som en catch-all for fremadrettet kompatibilitet med brugerdefinerede eller fremtidige deltyper. Da dens type er string (ikke en konstant), vil udtømmendeswitch/case på part.type ikke producere kompileringsfejl for ubehandlede sager.

Konfigurationsindstillinger for observabilitet – udvider kørselsindstillinger. Alle tilsidesættelser er funktioner, der kaldes for hver egenskabsadgang.

Nedarvet fra RuntimeConfigurationOptions:

• clusterCategory
• isNodeEnvDevelopment

Bemærk! isDevelopmentEnvironment er en afledt hentning for konfigurationsklassen (baseret på clusterCategory), ikke en indstilling, der kan tilsidesættes.

Accepteret input for recordOutputMessages. Understøtter en enkelt streng, en matrix af strenge (bagudkompat) eller den versionerede ombrydning.

En overordnet kontekst for oprettelse af et tidsrum. Accepterer enten:

• ParentSpanRef: eksplicit traceId/spanId-par (manuel tilgang)
• ParentContext: en OTel-kontekst, typisk fra extractContextFromHeaders eller propagation.extract()

Konfigurationsindstillinger for PerRequestSpanProcessor – udvider kørselsindstillinger. Alle tilsidesættelser er funktioner, der kaldes for hver egenskabsadgang.

Nedarvet fra RuntimeConfigurationOptions:

• clusterCategory, isNodeEnvDevelopment

Accepteret input for OutputResponse.messages. Understøtter almindelige strenge, strukturerede OutputMessages eller et råt dikt (behandles som et værktøjskaldsresultat pr. OTEL-specifikation og serialiseret direkte via JSON.stringify).

Hændelsesnavne, der bruges af Agent365Exporter til logføring og overvågning. Dette er hændelsestyper med lav kardinalitet for at sikre effektiv overvågning og aggregering.

Årsagen til, at en model stoppede med at generere pr. semantiske OTEL-gen-ai-konventioner.

Repræsenterer en anden handling for typer til modelindledning

Repræsenterer forskellige roller, der kan aktivere en agent

En meddelelsesdeltagers rolle pr. OTEL gen-ai semantiske konventioner.

Mediemodalitet for blob-, fil- og URI-dele.

Opretter en ny kontekst med en eksplicit overordnet reference. Dette gør det muligt for underordnede spans at være korrekt overordnet, selv når asynkron kontekst er brudt.

Udtrækker sporingskontekst fra indgående HTTP-headere ved hjælp af den globalt registrerede W3C-overførsel. Returnerer et OTel ParentContext , der kan overføres til områdeklasser som ParentContext.

Eksempel

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

Formatér fejlobjekt til logføring med meddelelses- og staksporing

Hent eksporttokenet pr. anmodning fra en given OTel-kontekst (eller den aktive).

Hent den aktuelle logføringsforekomst

Indsætter den aktuelle sporingskontekst (traceparent/tracestate headers) i det angivne headerobjekt ved hjælp af den globalt registrerede W3C-overførsel.

Eksempel

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

Kontrollér, om eksport pr. anmodning er aktiveret. Prioritet: Intern tilsidesætter > miljøvariablen for konfigurationsudbyderen > . Når indstillingen er aktiveret, bruges PerRequestSpanProcessor i stedet for BatchSpanProcessor. Tokenet overføres via OTel Context (asynkront lokalt lager) på eksporttidspunktet.

Normaliserer en InputMessagesParam til en versionindpakket InputMessages ombrydning.

• string / string[] → konverteret til ChatMessage[] og ombrudt
• InputMessages → returnerede as-is

Normaliserer en OutputMessagesParam til en versionindpakket OutputMessages ombrydning.

• string / string[] → konverteret til OutputMessage[] og ombrudt
• OutputMessages → returnerede as-is

Nulstil til standardkonsollogføring (primært til test)

Kør en funktion i en kontekst, der indeholder eksporttokenet pr. anmodning. Dette bevarer kun tokenet i ALS (OTel Context), aldrig i nogen registreringsdatabase.

Tokenet kan opdateres senere via updateExportToken() , før sporingen ryddes – nyttig, når tilbagekaldet er langvarigt, og det oprindelige token kan udløbe før eksporten.

Udtrækker sporingskontekst fra indgående HTTP-headere og kører tilbagekaldet i denne kontekst. Alle spans, der oprettes i tilbagekaldet, er overordnet til den udtrukne sporing.

Eksempel

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

Kører en tilbagekaldsfunktion i en kontekst, der har en eksplicit overordnet span reference. Dette er nyttigt til oprettelse af underordnede spændevidder i asynkrone tilbagekald, hvor kontekstoverførslen er brudt.

Sikrer, at værdien altid er en JSON-fortolkelig streng.

• Objekter serialiseres via JSON.stringify.
• Strenge, der allerede er gyldige JSON-objekter/matrixer, overføres.
• Alle andre strenge (herunder bare JSON-primitiver) er ombrudt: { [key]: value }.

Serialiserer en versioneret meddelelsesombrydning til JSON.

Outputtet er det fulde ombrydningsobjekt: {"version":"0.1.0","messages":[...]}.

Try/catch sikrer, at telemetrioptagelsen ikke aktiveres, selvom meddelelsesdele indeholder værdier, der ikke kan serialiseres af JSON (f.eks. BigInt, cirkulære refs).

Angiv en brugerdefineret logføringsimplementering for OBSERVABILITY SDK

Eksempel med 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 });
  }
});

Opdater eksporttokenet i den aktive OTel-kontekst. Kald dette for at opdatere tokenet, før du afslutter rodens rækkevidde, når det oprindelige token kan være udløbet under en anmodning, der har kørt i lang tid.

Skal kaldes inden for den samme asynkrone kontekst, der er oprettet af runWithExportToken.

Delt standardprovider for ObservabilityConfiguration.

Delt standardprovider for PerRequestSpanProcessorConfiguration.

Standardlogføringsforekomst for bagudkompatibilitet. Stedfortrædere til den globale logføring, som kan erstattes via setLogger().