@microsoft/agents-a365-observability package

Maximum number of spans per export batch.

Per request baggage builder for OpenTelemetry context propagation.

This class provides a fluent API for setting baggage values that will be propagated in the OpenTelemetry context.

Example

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

Context manager for baggage scope.

This class manages the lifecycle of baggage values, setting them on enter and restoring the previous context on exit.

Builder for configuring Agent 365 with OpenTelemetry tracing

Provides OpenTelemetry tracing scope for AI tool execution operations.

Provides OpenTelemetry tracing scope for generative AI inference operations.

Provides OpenTelemetry tracing scope for AI agent invocation operations.

Configuration for observability package. Inherits runtime settings and adds observability-specific settings.

Main entry point for Agent 365 providing OpenTelemetry tracing for AI agents and tools

OpenTelemetry constants for Agent 365

Base class for OpenTelemetry tracing scopes

Provides OpenTelemetry tracing scope for output message tracing with parent span linking.

Configuration for PerRequestSpanProcessor. Inherits runtime settings (clusterCategory, isNodeEnvDevelopment) and adds per-request processor guardrails.

This is separated from ObservabilityConfiguration because PerRequestSpanProcessor is used only in specific scenarios and these settings should not be exposed in the common ObservabilityConfiguration.

Details about an AI agent

Inline binary data (base64-encoded).

Configuration options for Agent 365 Observability Builder

Caller details for scope creation. Supports human callers, agent callers, or both (A2A with a human in the chain).

Migration note: In v1 the name CallerDetails referred to human caller identity (now UserDetails). In v2 it was repurposed as a wrapper that groups both human and agent caller information.

See UserDetails — human caller identity (previously CallerDetails) See CHANGELOG.md — breaking changes section for migration guidance

Represents channel for an invocation

An input message sent to a model (OTEL gen-ai semantic conventions).

Reference to a pre-uploaded file.

Extensible part for custom / future types.

Extensible server tool call details with a type discriminator.

Extensible server tool call response with a type discriminator.

Custom logger interface for Agent 365 observability Implement this interface to support logging backends

Details for an inference call

Details for recording the response from an inference call

Details for invoking agent scope.

An output message produced by a model (OTEL gen-ai semantic conventions).

Represents a response containing output messages from an agent. Used with OutputScope for output message tracing. Accepts plain strings, structured OTEL OutputMessage objects, or a raw dict (treated as a tool call result per OTEL spec).

Reference to a parent span for explicit parent-child linking across async boundaries. Used when automatic context propagation fails (e.g., WebSocket callbacks, external event handlers).

Model reasoning / chain-of-thought content.

Represents a request with telemetry context. Used across all scope types for channel and conversation tracking.

Server-side tool invocation.

Server-side tool response.

Represents an endpoint for agent invocation

Span configuration details for scope creation. Groups OpenTelemetry span options into a single object so the scope method signature remains stable as new options are added.

Plain text content.

Details of a tool call made by an agent

A tool call requested by the model.

Result of a tool call.

External URI reference.

Details about the human user caller.

Carrier type for HTTP headers used in trace context propagation. Compatible with Node.js IncomingHttpHeaders and plain string maps.

Accepted input for recordInputMessages. Supports a single string, an array of strings (backward compat), or the versioned wrapper.

Union of all message part types per OTEL gen-ai semantic conventions.

Note: GenericPart acts as a catch-all for forward compatibility with custom or future part types. Because its type is string (not a literal), exhaustive switch/case on part.type will not produce compile-time errors for unhandled cases.

Observability configuration options - extends runtime options. All overrides are functions called on each property access.

Inherited from RuntimeConfigurationOptions:

• clusterCategory
• isNodeEnvDevelopment

Note: isDevelopmentEnvironment is a derived getter on the configuration class (based on clusterCategory), not an overridable option.

Accepted input for recordOutputMessages. Supports a single string, an array of strings (backward compat), or the versioned wrapper.

A parent context for span creation. Accepts either:

• ParentSpanRef: explicit traceId/spanId pair (manual approach)
• ParentContext: an OTel Context, typically from extractContextFromHeaders or propagation.extract()

Configuration options for PerRequestSpanProcessor - extends runtime options. All overrides are functions called on each property access.

Inherited from RuntimeConfigurationOptions:

• clusterCategory, isNodeEnvDevelopment

Accepted input for OutputResponse.messages. Supports plain strings, structured OutputMessages, or a raw dict (treated as a tool call result per OTEL spec and serialized directly via JSON.stringify).

Event names used by Agent365Exporter for logging and monitoring. These are low-cardinality event types to ensure efficient monitoring and aggregation.

Reason a model stopped generating per OTEL gen-ai semantic conventions.

Represents different operation for types for model inference

Represents different roles that can invoke an agent

Role of a message participant per OTEL gen-ai semantic conventions.

Media modality for blob, file, and URI parts.

Creates a new Context with an explicit parent span reference. This allows child spans to be correctly parented even when async context is broken.

Extracts trace context from incoming HTTP headers using the globally registered W3C propagator. Returns an OTel ParentContext that can be passed to scope classes as a ParentContext.

Example

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

Format error object for logging with message and stack trace

Retrieve the per-request export token from a given OTel Context (or the active one).

Get the current logger instance

Injects the current trace context (traceparent/tracestate headers) into the provided headers object using the globally registered W3C propagator.

Example

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

Check if per-request export is enabled. Precedence: internal overrides > configuration provider > environment variable. When enabled, the PerRequestSpanProcessor is used instead of BatchSpanProcessor. The token is passed via OTel Context (async local storage) at export time.

Normalizes an InputMessagesParam to a versioned InputMessages wrapper.

• string / string[] → converted to ChatMessage[] and wrapped
• InputMessages → returned as-is

Normalizes an OutputMessagesParam to a versioned OutputMessages wrapper.

• string / string[] → converted to OutputMessage[] and wrapped
• OutputMessages → returned as-is

Reset to the default console logger (mainly for testing)

Run a function within a Context that carries the per-request export token. This keeps the token only in OTel Context (ALS), never in any registry.

The token can be updated later via updateExportToken() before the trace is flushed — useful when the callback is long-running and the original token may expire before export.

Extracts trace context from incoming HTTP headers and runs the callback within that context. Any spans created inside the callback will be parented to the extracted trace.

Example

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

Runs a callback function within a context that has an explicit parent span reference. This is useful for creating child spans in async callbacks where context propagation is broken.

Ensures the value is always a JSON-parseable string.

• Objects are serialized via JSON.stringify.
• Strings that are already valid JSON objects/arrays are passed through.
• All other strings (including bare JSON primitives) are wrapped: { [key]: value }.

Serializes a versioned message wrapper to JSON.

The output is the full wrapper object: {"version":"0.1.0","messages":[...]}.

The try/catch ensures telemetry recording is non-throwing even when message parts contain non-JSON-serializable values (e.g. BigInt, circular refs).

Set a custom logger implementation for the observability SDK

Example with 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 });
  }
});

Truncate a string value to MAX_ATTRIBUTE_LENGTH characters. If the value exceeds the limit, it is trimmed and a truncation suffix is appended, with the total length capped at exactly MAX_ATTRIBUTE_LENGTH.

Update the export token in the active OTel Context. Call this to refresh the token before ending the root span when the original token may have expired during a long-running request.

Must be called within the same async context created by runWithExportToken.

Maximum length for span attribute values. Values exceeding this limit will be truncated with a suffix.

Shared default provider for ObservabilityConfiguration.

Shared default provider for PerRequestSpanProcessorConfiguration.

Default logger instance for backward compatibility. Delegates to the global logger which can be replaced via setLogger().