@cuylabs/agent-microsoft-opentelemetry 4.8.0

package/dist/index.js

@@ -0,0 +1,363 @@
+import {
+  MICROSOFT_A365_ATTRIBUTES,
+  MICROSOFT_A365_FMI_SCOPE,
+  MICROSOFT_A365_OBSERVABILITY_SCOPE,
+  MicrosoftOpenTelemetryModuleLoadError,
+  MicrosoftOpenTelemetryResourceModuleLoadError,
+  buildMicrosoftA365BaggagePairs,
+  callOptionalBooleanMethod,
+  callOptionalStringMethod,
+  createEnvReader,
+  createMicrosoftA365S2STokenResolver,
+  createMicrosoftA365S2STokenResolverFromEnv,
+  createMicrosoftOpenTelemetryInstrumentationOptions,
+  createMicrosoftOpenTelemetryTracingConfig,
+  firstNonEmpty,
+  initMicrosoftOpenTelemetry,
+  initMicrosoftOpenTelemetryFromEnv,
+  loadMicrosoftOpenTelemetryModule,
+  loadOpenTelemetryResourceModule,
+  mergeInstrumentationOptions,
+  normalizeInstrumentationProfile,
+  parseServiceEndpoint,
+  readPath,
+  resolveMicrosoftOpenTelemetryBooleanEnv,
+  resolveMicrosoftOpenTelemetryEnvironment,
+  resolveMicrosoftOpenTelemetryNumberEnv,
+  runWithMicrosoftA365Context,
+  updateMicrosoftA365ExportToken
+} from "./chunk-S7XVXBY3.js";
+
+// src/a365/hosting.ts
+async function configureMicrosoftA365Hosting(adapter, options = {}) {
+  const module = await loadMicrosoftOpenTelemetryModule(options.runtime);
+  const hostingOptions = resolveHostingOptions(options);
+  if (module.configureA365Hosting) {
+    return module.configureA365Hosting(adapter, hostingOptions);
+  }
+  if (module.ObservabilityHostingManager) {
+    const manager = new module.ObservabilityHostingManager();
+    manager.configure(adapter, hostingOptions);
+    return manager;
+  }
+  throw new MicrosoftOpenTelemetryModuleLoadError(
+    "The installed @microsoft/opentelemetry package does not expose A365 hosting middleware helpers."
+  );
+}
+function resolveHostingOptions(options) {
+  return {
+    enableBaggage: options.enableBaggage ?? true,
+    enableOutputLogging: options.enableOutputLogging ?? true
+  };
+}
+
+// src/a365/turn-context.ts
+function createMicrosoftA365ContextFromTurnContext(turnContext, options = {}) {
+  const { serviceUrl, useRecipientIdAsAgentId, ...requestOptions } = options;
+  const activity = turnContext.activity ?? {};
+  const channelData = activity.channelData;
+  const endpoint = parseServiceEndpoint(serviceUrl ?? activity.serviceUrl);
+  const isAgenticRequest = callOptionalBooleanMethod(activity.isAgenticRequest);
+  const agentId = firstNonEmpty(
+    requestOptions.agentId,
+    isAgenticRequest ? callOptionalStringMethod(activity.getAgenticInstanceId) : void 0,
+    activity.recipient?.agenticAppId,
+    useRecipientIdAsAgentId ? activity.recipient?.id : void 0
+  );
+  const tenantId = firstNonEmpty(
+    requestOptions.tenantId,
+    callOptionalStringMethod(activity.getAgenticTenantId),
+    activity.recipient?.tenantId,
+    activity.conversation?.tenantId,
+    readPath(channelData, ["tenant", "id"]),
+    readPath(channelData, ["tenantId"])
+  );
+  const context = { ...requestOptions };
+  setIfDefined(context, "tenantId", tenantId);
+  setIfDefined(context, "agentId", agentId);
+  setIfDefined(
+    context,
+    "agentName",
+    firstNonEmpty(requestOptions.agentName, activity.recipient?.name)
+  );
+  setIfDefined(
+    context,
+    "agentDescription",
+    firstNonEmpty(requestOptions.agentDescription, activity.recipient?.role)
+  );
+  setIfDefined(
+    context,
+    "agentAuid",
+    firstNonEmpty(requestOptions.agentAuid, activity.recipient?.aadObjectId)
+  );
+  setIfDefined(
+    context,
+    "agentBlueprintId",
+    firstNonEmpty(
+      requestOptions.agentBlueprintId,
+      activity.recipient?.agenticAppBlueprintId
+    )
+  );
+  setIfDefined(
+    context,
+    "conversationId",
+    firstNonEmpty(requestOptions.conversationId, activity.conversation?.id)
+  );
+  setIfDefined(
+    context,
+    "conversationItemLink",
+    firstNonEmpty(requestOptions.conversationItemLink, activity.serviceUrl)
+  );
+  setIfDefined(
+    context,
+    "sessionId",
+    firstNonEmpty(
+      requestOptions.sessionId,
+      requestOptions.conversationId,
+      activity.conversation?.id
+    )
+  );
+  setIfDefined(
+    context,
+    "channelName",
+    firstNonEmpty(requestOptions.channelName, activity.channelId)
+  );
+  setIfDefined(
+    context,
+    "channelLink",
+    firstNonEmpty(requestOptions.channelLink, activity.channelIdSubChannel)
+  );
+  setIfDefined(
+    context,
+    "userId",
+    firstNonEmpty(
+      requestOptions.userId,
+      activity.from?.aadObjectId,
+      activity.from?.id,
+      readPath(turnContext.identity, ["oid"]),
+      readPath(turnContext.identity, ["sub"])
+    )
+  );
+  setIfDefined(
+    context,
+    "userName",
+    firstNonEmpty(requestOptions.userName, activity.from?.name)
+  );
+  setIfDefined(
+    context,
+    "userEmail",
+    firstNonEmpty(
+      requestOptions.userEmail,
+      activity.from?.email,
+      activity.from?.userPrincipalName,
+      activity.from?.agenticUserId,
+      readPath(channelData, ["from", "userPrincipalName"]),
+      readPath(turnContext.identity, ["preferred_username"]),
+      readPath(turnContext.identity, ["upn"])
+    )
+  );
+  setIfDefined(
+    context,
+    "callerAgentBlueprintId",
+    firstNonEmpty(
+      requestOptions.callerAgentBlueprintId,
+      activity.from?.agenticAppBlueprintId
+    )
+  );
+  setIfDefined(
+    context,
+    "serverAddress",
+    firstNonEmpty(requestOptions.serverAddress, endpoint?.serverAddress)
+  );
+  setIfDefined(
+    context,
+    "serverPort",
+    requestOptions.serverPort ?? endpoint?.serverPort
+  );
+  return context;
+}
+function setIfDefined(context, key, value) {
+  if (value !== void 0) {
+    context[key] = value;
+  }
+}
+
+// src/internal/async-queue.ts
+var AsyncQueue = class {
+  values = [];
+  waiters = [];
+  closed = false;
+  push(value) {
+    if (this.closed) {
+      return;
+    }
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter({ value, done: false });
+      return;
+    }
+    this.values.push(value);
+  }
+  close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    for (const waiter of this.waiters.splice(0)) {
+      waiter({ value: void 0, done: true });
+    }
+  }
+  [Symbol.asyncIterator]() {
+    return {
+      next: () => {
+        const value = this.values.shift();
+        if (value !== void 0) {
+          return Promise.resolve({ value, done: false });
+        }
+        if (this.closed) {
+          return Promise.resolve({ value: void 0, done: true });
+        }
+        return new Promise((resolve) => {
+          this.waiters.push(resolve);
+        });
+      }
+    };
+  }
+};
+
+// src/a365/turn-source.ts
+function createMicrosoftA365ObservedTurnSource({
+  context,
+  runtimeOptions,
+  source
+}) {
+  const resolveContext = typeof context === "function" ? context : () => context;
+  return {
+    async *chat(sessionId, message, options) {
+      const requestContext = await resolveContext({
+        sessionId,
+        message,
+        options
+      });
+      const queue = new AsyncQueue();
+      let failure;
+      void runWithMicrosoftA365Context(
+        requestContext,
+        async () => {
+          try {
+            for await (const event of source.chat(
+              sessionId,
+              message,
+              options
+            )) {
+              queue.push(event);
+            }
+          } catch (error) {
+            failure = error;
+          } finally {
+            queue.close();
+          }
+        },
+        runtimeOptions
+      ).catch((error) => {
+        failure = error;
+        queue.close();
+      });
+      for await (const event of queue) {
+        yield event;
+      }
+      if (failure) {
+        throw failure;
+      }
+    }
+  };
+}
+
+// src/runtime/destinations.ts
+var TRUE_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
+function isMicrosoftOtlpEnvironmentEnabled(env = process.env) {
+  return Boolean(
+    readFirst(
+      env,
+      "OTEL_EXPORTER_OTLP_ENDPOINT",
+      "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
+      "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT",
+      "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT"
+    )
+  );
+}
+function isAzureMonitorEnvironmentEnabled(env = process.env) {
+  if (isTruthy(readFirst(env, "MICROSOFT_OTEL_AZURE_MONITOR_ENABLED"))) {
+    return true;
+  }
+  return Boolean(readFirst(env, "APPLICATIONINSIGHTS_CONNECTION_STRING"));
+}
+function createAzureMonitorOptionsFromEnv(env = process.env) {
+  const enabled = isAzureMonitorEnvironmentEnabled(env);
+  const connectionString = readFirst(
+    env,
+    "APPLICATIONINSIGHTS_CONNECTION_STRING"
+  );
+  if (!enabled && !connectionString) {
+    return void 0;
+  }
+  return {
+    enabled,
+    ...connectionString ? { azureMonitorExporterOptions: { connectionString } } : {}
+  };
+}
+function summarizeMicrosoftOpenTelemetryDestinations(options = {}) {
+  const env = options.env ?? process.env;
+  const azureMonitor = options.azureMonitor === false ? false : options.azureMonitor?.enabled ?? isAzureMonitorEnvironmentEnabled(env);
+  const agent365 = options.a365?.enabled === true && options.a365.enableObservabilityExporter === true;
+  const otlp = isMicrosoftOtlpEnvironmentEnabled(env);
+  return {
+    agent365,
+    azureMonitor,
+    otlp,
+    console: options.enableConsoleExporters ?? (!agent365 && !azureMonitor && !otlp)
+  };
+}
+function readFirst(env, ...names) {
+  for (const name of names) {
+    const value = env[name]?.trim();
+    if (value) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function isTruthy(value) {
+  return TRUE_VALUES.has((value ?? "").trim().toLowerCase());
+}
+export {
+  MICROSOFT_A365_ATTRIBUTES,
+  MICROSOFT_A365_FMI_SCOPE,
+  MICROSOFT_A365_OBSERVABILITY_SCOPE,
+  MicrosoftOpenTelemetryModuleLoadError,
+  MicrosoftOpenTelemetryResourceModuleLoadError,
+  buildMicrosoftA365BaggagePairs,
+  configureMicrosoftA365Hosting,
+  createAzureMonitorOptionsFromEnv,
+  createEnvReader,
+  createMicrosoftA365ContextFromTurnContext,
+  createMicrosoftA365ObservedTurnSource,
+  createMicrosoftA365S2STokenResolver,
+  createMicrosoftA365S2STokenResolverFromEnv,
+  createMicrosoftOpenTelemetryInstrumentationOptions,
+  createMicrosoftOpenTelemetryTracingConfig,
+  initMicrosoftOpenTelemetry,
+  initMicrosoftOpenTelemetryFromEnv,
+  isAzureMonitorEnvironmentEnabled,
+  isMicrosoftOtlpEnvironmentEnabled,
+  loadMicrosoftOpenTelemetryModule,
+  loadOpenTelemetryResourceModule,
+  mergeInstrumentationOptions,
+  normalizeInstrumentationProfile,
+  resolveMicrosoftOpenTelemetryBooleanEnv,
+  resolveMicrosoftOpenTelemetryEnvironment,
+  resolveMicrosoftOpenTelemetryNumberEnv,
+  runWithMicrosoftA365Context,
+  summarizeMicrosoftOpenTelemetryDestinations,
+  updateMicrosoftA365ExportToken
+};

package/dist/loader.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/loader.js

@@ -0,0 +1,3 @@
+// src/loader.ts
+import "@microsoft/opentelemetry/loader";
+await import("./register.js");

package/dist/register.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/register.js

@@ -0,0 +1,17 @@
+import {
+  initMicrosoftOpenTelemetryFromEnv
+} from "./chunk-S7XVXBY3.js";
+
+// src/register.ts
+var DISABLED_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
+var GLOBAL_HANDLE_KEY = /* @__PURE__ */ Symbol.for(
+  "@cuylabs/agent-microsoft-opentelemetry/register"
+);
+var disabled = DISABLED_VALUES.has(
+  (process.env.CUYLABS_MICROSOFT_OPENTELEMETRY_DISABLED ?? "").toLowerCase()
+);
+if (!disabled) {
+  const globalState = globalThis;
+  globalState[GLOBAL_HANDLE_KEY] ??= initMicrosoftOpenTelemetryFromEnv();
+  await globalState[GLOBAL_HANDLE_KEY];
+}

package/docs/architecture.md

@@ -0,0 +1,110 @@
+# Architecture
+
+`@cuylabs/agent-microsoft-opentelemetry` is the Microsoft OpenTelemetry distro
+adapter for `agents-ts`.
+
+## Layers
+
+The package keeps three boundaries separate.
+
+First, `@cuylabs/agent-core` remains the owner of agent execution telemetry. It
+configures AI SDK v7 GenAI telemetry for model calls and tool execution and
+provides `createAgent({ tracing })` as the app-facing integration point.
+
+Second, `@microsoft/opentelemetry` owns the Microsoft OpenTelemetry provider,
+span processors, exporters, Azure Monitor integration, Agent 365 exporter, OTLP
+export, and Microsoft-supported framework instrumentation.
+
+Third, this package bridges the two. It starts the Microsoft distro, creates
+Agent 365 S2S token resolvers, applies Agent 365 baggage around turns, and
+returns `agent-core` tracing defaults that align with Microsoft Agent 365
+schemas.
+
+The adapter default instrumentation profile is `agent-core`. It disables
+Microsoft's optional framework auto-instrumentations for OpenAI Agents SDK and
+LangChain because those are not part of the normal `agents-ts` execution path.
+Applications can opt into those official Microsoft framework integrations with
+`microsoft-genai` or explicit `instrumentationOptions`.
+
+## Source Layout
+
+The Microsoft distro source is organized by owned implementation subsystems:
+A365 processors/exporters/scopes, Azure Monitor, OTLP, GenAI instrumentation,
+and shared distro setup. This package does not copy those internals. It keeps
+only the adapter responsibilities:
+
+| Folder | Responsibility |
+| --- | --- |
+| `src/a365` | Normalize channel/runtime data into Microsoft A365 baggage. |
+| `src/auth` | Resolve Agent 365 S2S tokens from CLI-generated configuration or host-provided managed identity assertions. |
+| `src/runtime` | Call `useMicrosoftOpenTelemetry()`, map adapter options to distro options, expose destination helpers, expose instrumentation profiles, and load Microsoft modules lazily. |
+| `src/tracing` | Produce `agent-core` tracing config that avoids duplicate tool spans and carries Microsoft attributes. |
+| `src/common` | Public cross-cutting type aliases. |
+| `src/internal` | Small helpers that are not part of the package API. |
+
+## Agent 365 Flow
+
+An application starts the Microsoft distro with `initMicrosoftOpenTelemetry()`.
+For ESM services that rely on automatic instrumentation, start the process with
+`--import @cuylabs/agent-microsoft-opentelemetry/loader`. That loader imports
+Microsoft's OpenTelemetry hook first and then runs this package's env-driven
+registration. This follows the distro's requirement that instrumentation hooks
+are registered before app modules load.
+
+When `a365.enabled` is true, the distro registers the Agent 365 span processor.
+When `a365.enableObservabilityExporter` is true, it also registers the Agent
+365 HTTP exporter. The adapter still accepts `exporterEnabled` as a
+compatibility alias, but new code should use Microsoft's option name.
+
+Each channel turn should run inside `runWithMicrosoftA365Context()` or an
+observed turn source. That scope creates Microsoft baggage values such as
+`microsoft.tenant.id`, `gen_ai.agent.id`, `user.email`,
+`microsoft.channel.name`, and `gen_ai.conversation.id`. The Microsoft distro
+copies those baggage values onto spans before export.
+
+For Microsoft Agent Hosting compatible adapters, the package can also delegate
+to the official distro's hosting middleware with
+`configureMicrosoftA365Hosting()`. This keeps Microsoft TurnContext middleware
+on Microsoft's implementation while still exposing one `agents-ts` integration
+surface.
+
+The Agent 365 exporter groups spans by tenant and agent identity, then calls the
+token resolver. For S2S agents, `createMicrosoftA365S2STokenResolver()` performs
+the Agent 365 FMI flow and caches the resulting Observability API token.
+
+## Tool Spans
+
+The default tracing helper returns `emitToolSpans: false`. This is intentional.
+AI SDK v7 GenAI telemetry already emits standard tool spans for normal
+`streamText()` tool execution. Enabling both AI SDK tool spans and agent-core
+custom tool spans creates duplicate `execute_tool` telemetry for one tool call.
+
+If an application has a custom execution path that does not emit AI SDK tool
+spans, it can opt in with:
+
+```ts
+createMicrosoftOpenTelemetryTracingConfig({
+  emitToolSpans: true,
+});
+```
+
+## Content Capture
+
+The package does not force a privacy policy. `recordInputs` and `recordOutputs`
+are explicit `agent-core` tracing settings. Set them to `true` when Agent 365
+validation or audit scenarios require prompt, response, tool argument, and tool
+result attributes. Set them to `false` when an application needs metadata-only
+telemetry.
+
+## Distro Migration
+
+The older `@cuylabs/agent-a365-observability` package wraps
+`@microsoft/agents-a365-observability`. This package wraps the newer
+`@microsoft/opentelemetry` distro. New Microsoft integrations should prefer this
+package unless they need to remain on the older Microsoft package family for
+compatibility.
+
+For an option-by-option mapping to the Microsoft distro, see
+[distro-alignment.md](./distro-alignment.md).
+For destination and instrumentation strategy, see
+[destinations-and-instrumentation.md](./destinations-and-instrumentation.md).

package/docs/destinations-and-instrumentation.md

@@ -0,0 +1,116 @@
+# Destinations and Instrumentation
+
+The Microsoft OpenTelemetry distro separates where telemetry is sent from how
+telemetry is created.
+
+## Destinations
+
+Destinations are exporters attached to the same OpenTelemetry pipeline.
+
+| Destination | Purpose | How to enable |
+| --- | --- | --- |
+| Agent 365 | Microsoft 365 admin, Defender, and Purview agent activity. | `a365.enabled: true` plus `a365.enableObservabilityExporter: true`. |
+| Azure Monitor | Application operations, traces, dependencies, logs, metrics, dashboards, and alerts. | `azureMonitor: { enabled: true }` or `APPLICATIONINSIGHTS_CONNECTION_STRING`. |
+| OTLP | Vendor-neutral export to collectors or backends such as Grafana, Datadog, or New Relic. | Standard `OTEL_EXPORTER_OTLP_*` environment variables. |
+| Console | Local validation when no remote exporter is active, or explicit debugging. | `enableConsoleExporters: true`. |
+
+The same spans can flow to multiple destinations. Agent 365 enrichment still
+helps Azure Monitor and OTLP when `a365.enabled` is true because the Microsoft
+distro's `A365SpanProcessor` copies baggage onto spans before export.
+
+## Instrumentation
+
+Instrumentation controls which libraries create spans.
+
+| Instrumentation | Purpose |
+| --- | --- |
+| `http`, `azureSdk`, databases, Redis, Bunyan, Winston | Infrastructure and application telemetry. |
+| `openaiAgents` | Optional Microsoft auto-instrumentation for the OpenAI Agents SDK when `@openai/agents` is installed. |
+| `langchain` | Optional Microsoft auto-instrumentation for LangChain when `@langchain/core` is installed. |
+| `agent-core` tracing | Emits `agents-ts` agent invocation spans and passes AI SDK v7 GenAI telemetry into `streamText()`. |
+
+`@cuylabs/agent-core` does not use OpenAI Agents SDK or LangChain internally.
+Those Microsoft framework instrumentations are useful only when an application
+also runs those frameworks in the same process.
+
+## Profiles
+
+Use `instrumentationProfile` to make the intent explicit.
+
+```ts
+await initMicrosoftOpenTelemetry({
+  instrumentationProfile: "agent-core",
+});
+```
+
+| Profile | Behavior |
+| --- | --- |
+| `agent-core` | Disables Microsoft infra and framework auto-instrumentation. Best default for `agents-ts`, where `agent-core` emits the agent/model/tool telemetry. |
+| `microsoft-genai` | Disables infrastructure auto-instrumentation and enables Microsoft's OpenAI Agents SDK and LangChain auto-instrumentations. |
+| `full-stack` | Enables infrastructure and Microsoft framework auto-instrumentation. Best when sending to Azure Monitor or a general OTLP backend too. |
+| `manual` | Disables built-in auto-instrumentation. Best when the app supplies its own processors/instrumentation. |
+| `microsoft-default` | Leaves `instrumentationOptions` unset so the official distro applies its native defaults. |
+
+Explicit `instrumentationOptions` always override the selected profile.
+The old pre-release name `agent365-genai` is still accepted as an alias for
+`microsoft-genai`, but new code should not use it.
+
+## Content Recording
+
+There are two content-recording surfaces only if the application uses both
+`agent-core` and Microsoft's optional framework auto-instrumentations.
+
+`agent-core` uses `agent.recordInputs` and `agent.recordOutputs` in this
+adapter's tracing config. Those settings control AI SDK v7 GenAI telemetry
+created by `@cuylabs/agent-core`.
+
+Microsoft's optional OpenAI Agents and LangChain auto-instrumentations use their
+own official flags:
+
+```ts
+await initMicrosoftOpenTelemetry({
+  instrumentationOptions: {
+    openaiAgents: {
+      enabled: true,
+      isContentRecordingEnabled: true,
+    },
+    langchain: {
+      enabled: true,
+      isContentRecordingEnabled: true,
+    },
+  },
+});
+```
+
+Set these only when the process actually uses those frameworks. They do not
+control `agent-core`'s AI SDK spans.
+
+## Example: Agent 365 and Azure Monitor
+
+```ts
+const observability = await initMicrosoftOpenTelemetry({
+  resource: {
+    serviceName: "cdo-ai-companion",
+    serviceVersion: "1.0.0",
+  },
+  a365: {
+    enabled: true,
+    enableObservabilityExporter: true,
+    useS2SEndpoint: true,
+    tokenResolver: createMicrosoftA365S2STokenResolverFromEnv(),
+  },
+  azureMonitor: {
+    enabled: Boolean(process.env.APPLICATIONINSIGHTS_CONNECTION_STRING),
+  },
+  instrumentationProfile: "full-stack",
+});
+```
+
+This sends the same enriched spans to Agent 365 and Azure Monitor. Set standard
+`OTEL_EXPORTER_OTLP_ENDPOINT` variables to add OTLP export without changing code.
+
+Azure Monitor options are passed through to the Microsoft distro. Use official
+properties such as `enableLiveMetrics`, `enableStandardMetrics`,
+`enableTraceBasedSamplingForLogs`, `enablePerformanceCounters`, and
+`browserSdkLoaderOptions` when the application needs those Azure Monitor
+features.