@cuylabs/agent-microsoft-opentelemetry 4.8.0

package/docs/distro-alignment.md

@@ -0,0 +1,123 @@
+# Microsoft Distro Alignment
+
+This package follows the Microsoft OpenTelemetry distro model while preserving
+`@cuylabs/agent-core` as the owner of agent execution.
+
+## Startup
+
+Microsoft recommends loading the OpenTelemetry ESM hook before application
+modules. Use this package's loader entry point for that path:
+
+```bash
+node --import @cuylabs/agent-microsoft-opentelemetry/loader dist/server.js
+```
+
+The loader imports `@microsoft/opentelemetry/loader` first, then runs
+`@cuylabs/agent-microsoft-opentelemetry/register`. This gives automatic
+instrumentations the earliest possible hook while keeping the application on the
+env-driven adapter.
+
+Apps that initialize observability in code can call
+`initMicrosoftOpenTelemetry()` directly at the beginning of their entry point.
+
+## Distro Options
+
+`initMicrosoftOpenTelemetry()` maps directly to `useMicrosoftOpenTelemetry()`.
+
+| Microsoft distro option | Adapter option |
+| --- | --- |
+| `resource` | `resource` with `serviceName`, `serviceVersion`, and custom attributes. |
+| `azureMonitor` | `azureMonitor`. |
+| `instrumentationOptions` | `instrumentationOptions`. |
+| `agent-core`-focused instrumentation defaults | `instrumentationProfile: "agent-core"`. |
+| `a365.enabled` | `a365.enabled`. |
+| `a365.enableObservabilityExporter` | `a365.enableObservabilityExporter`. |
+| `a365.tokenResolver` | `a365.tokenResolver`. |
+| `a365.useS2SEndpoint` | `a365.useS2SEndpoint`. |
+| Export queue, timeout, batch, cluster, domain, and scope options | Same A365 option names. |
+
+The adapter also accepts `a365.exporterEnabled` as a compatibility alias for
+`a365.enableObservabilityExporter`. New code should use Microsoft's official
+option name.
+
+OTLP export is intentionally environment-driven, matching the Microsoft distro.
+Set standard `OTEL_EXPORTER_OTLP_*` variables to enable OTLP exporters.
+
+## Token Resolution
+
+Microsoft's distro calls `tokenResolver(agentId, tenantId, authScopes)` when the
+Agent 365 exporter sends a batch. `createMicrosoftA365S2STokenResolverFromEnv()`
+implements the Agent 365 S2S flow created by the A365 CLI:
+
+1. Read tenant, agent identity, blueprint client ID, and client secret from
+   `A365_OBSERVABILITY_*` or `agent365Observability__*` variables.
+2. Exchange the blueprint credential for a federated managed identity assertion.
+3. Exchange that assertion as the Agent 365 agent identity for an Observability
+   API token.
+4. Cache the token until it approaches expiration.
+
+This is different from Microsoft's `AgenticTokenCacheInstance`, which is meant
+for Microsoft Agent Hosting and per-turn authorization flows.
+
+## Context Propagation
+
+Microsoft's distro uses `BaggageBuilder` and `A365SpanProcessor`. The adapter
+uses the same path:
+
+1. Build normalized `MicrosoftA365RequestContext` values from channel/runtime
+   data.
+2. Convert those values to Microsoft baggage keys with
+   `buildMicrosoftA365BaggagePairs()`.
+3. Run the agent turn inside `runWithMicrosoftA365Context()`.
+4. Let the Microsoft distro copy baggage onto spans during span start.
+
+For channel adapters, prefer `createMicrosoftA365ObservedTurnSource()`. It is
+the `agents-ts` equivalent of Microsoft Hosting's `BaggageMiddleware`: it wraps
+each `AgentTurnSource.chat()` call in a Microsoft baggage scope.
+
+For apps that do use Microsoft Agent Hosting compatible adapters, call
+`configureMicrosoftA365Hosting(adapter, options)`. This is a small pass-through
+to the official distro's `configureA365Hosting()` helper, with a fallback for
+older distro versions that expose `ObservabilityHostingManager` instead.
+
+## Agent-Core Tracing
+
+The adapter does not create a second agent runtime. It returns tracing settings
+for `createAgent({ tracing })`:
+
+```ts
+const microsoftOtel = await initMicrosoftOpenTelemetryFromEnv();
+
+const agent = createAgent({
+  name: "scout",
+  model,
+  tracing: microsoftOtel.tracing,
+});
+```
+
+`agent-core` emits the agent invocation span and passes AI SDK v7 GenAI telemetry
+into `streamText()`. The Microsoft distro owns the provider, span processors,
+and exporters. This keeps one OpenTelemetry pipeline while avoiding duplicate
+tool spans.
+
+## Optional Microsoft Framework Instrumentation
+
+The Microsoft distro's OpenAI Agents and LangChain integrations are optional
+framework auto-instrumentations. They listen to those frameworks when the
+corresponding packages are installed. They are different from `agent-core`
+tracing, which instruments `agents-ts` execution and AI SDK v7 `streamText()`.
+
+Use `instrumentationOptions.openaiAgents` or
+`instrumentationOptions.langchain` only when the process actually uses those
+frameworks. The adapter's default `agent-core` profile disables them because the
+normal `agents-ts` path does not execute through those frameworks.
+
+The adapter types expose Microsoft's `isContentRecordingEnabled` flags for
+those framework instrumentations. They are separate from `agent-core`
+`recordInputs` and `recordOutputs`, which control AI SDK v7 telemetry produced
+through `@cuylabs/agent-core`.
+
+The early pre-release profile name `agent365-genai` remains accepted as a
+compatibility alias for `microsoft-genai`, but new code should use
+`agent-core`, `microsoft-genai`, `full-stack`, `manual`, or
+`microsoft-default`.

package/docs/env.md

@@ -0,0 +1,76 @@
+# Environment Variables
+
+The package accepts both Microsoft OpenTelemetry resource settings and Agent 365
+CLI-generated observability settings.
+
+## Resource
+
+| Variable | Meaning |
+| --- | --- |
+| `MICROSOFT_OTEL_SERVICE_NAME` or `OTEL_SERVICE_NAME` | OpenTelemetry `service.name`. |
+| `MICROSOFT_OTEL_SERVICE_VERSION` or `OTEL_SERVICE_VERSION` | OpenTelemetry `service.version`. |
+| `MICROSOFT_OTEL_SERVICE_NAMESPACE` or `OTEL_SERVICE_NAMESPACE` | OpenTelemetry `service.namespace`. |
+| `MICROSOFT_OTEL_SERVICE_INSTANCE_ID` or `OTEL_SERVICE_INSTANCE_ID` | OpenTelemetry `service.instance.id`. |
+
+## Destinations
+
+| Variable | Meaning |
+| --- | --- |
+| `APPLICATIONINSIGHTS_CONNECTION_STRING` | Enables Azure Monitor export in the Microsoft distro. |
+| `MICROSOFT_OTEL_AZURE_MONITOR_ENABLED` | Explicit Azure Monitor enable flag used by the adapter helpers. |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Enables OTLP export for traces, metrics, and logs. |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Enables or overrides OTLP trace export. |
+| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Enables or overrides OTLP metric export. |
+| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Enables or overrides OTLP log export. |
+| `MICROSOFT_OTEL_ENABLE_CONSOLE_EXPORTERS` | Explicitly enables console exporters. |
+| `MICROSOFT_OTEL_INSTRUMENTATION_PROFILE` | `agent-core`, `microsoft-genai`, `full-stack`, `manual`, or `microsoft-default`. |
+
+## Agent 365
+
+| Variable | Meaning |
+| --- | --- |
+| `MICROSOFT_OTEL_A365_ENABLED` or `A365_OBSERVABILITY_ENABLED` | Enables the Agent 365 distro path. |
+| `ENABLE_A365_OBSERVABILITY_EXPORTER` | Enables HTTP export to Agent 365. |
+| `A365_OBSERVABILITY_TENANT_ID` | Tenant that owns the agent identity. |
+| `A365_OBSERVABILITY_AGENT_ID` | Agent 365 agent identity ID. |
+| `A365_OBSERVABILITY_CLIENT_ID` | Blueprint client ID used for the FMI token exchange. |
+| `A365_OBSERVABILITY_CLIENT_SECRET` | Blueprint client secret. Use Key Vault or managed identity in production. |
+| `A365_OBSERVABILITY_USE_MANAGED_IDENTITY` | Uses a managed-identity assertion provider when supplied by the host app. |
+| `A365_OBSERVABILITY_USE_S2S_ENDPOINT` | Uses the Agent 365 S2S ingestion endpoint. |
+| `A365_OBSERVABILITY_CLUSTER_CATEGORY` or `CLUSTER_CATEGORY` | Agent 365 endpoint cluster category, such as `prod`, `test`, or `gov`. |
+| `A365_OBSERVABILITY_AUTHENTICATION_SCOPES` | Space- or comma-separated auth scopes. |
+| `A365_OBSERVABILITY_SCOPES_OVERRIDE` | Official Microsoft distro auth-scope override. It is passed to the distro as A365 auth scopes. |
+| `A365_OBSERVABILITY_DOMAIN_OVERRIDE` | Agent 365 domain override for non-production clouds. |
+| `A365_OBSERVABILITY_LOG_LEVEL` | Microsoft distro A365 log level, for example `warn|error`. |
+| `A365_OBSERVABILITY_MAX_QUEUE_SIZE` | Agent 365 exporter queue size. |
+| `A365_OBSERVABILITY_SCHEDULED_DELAY_MS` | Agent 365 exporter batch delay in milliseconds. |
+| `A365_OBSERVABILITY_EXPORTER_TIMEOUT_MS` | Agent 365 export timeout in milliseconds. |
+| `A365_OBSERVABILITY_HTTP_REQUEST_TIMEOUT_MS` | Agent 365 per-request HTTP timeout in milliseconds. |
+| `A365_OBSERVABILITY_MAX_EXPORT_BATCH_SIZE` | Agent 365 maximum spans per export batch. |
+| `A365_OBSERVABILITY_MAX_PAYLOAD_BYTES` | Agent 365 maximum estimated payload size per HTTP chunk. |
+
+In code, prefer Microsoft's official `a365.enableObservabilityExporter` option.
+The package also accepts `a365.exporterEnabled` as a compatibility alias.
+
+The double-underscore CLI aliases are also accepted for the core S2S values,
+such as `agent365Observability__tenantId`, `agent365Observability__agentId`,
+`agent365Observability__clientId`, and
+`agent365Observability__clientSecret`.
+
+## Distro-Owned Pass-Through Variables
+
+The Microsoft distro also reads some variables directly from `process.env`.
+This adapter does not parse or duplicate those settings because the official
+package owns their behavior.
+
+| Variable | Meaning |
+| --- | --- |
+| `A365_PER_REQUEST_MAX_TRACES` | Max buffered traces for the distro's A365 per-request pipeline. |
+| `A365_PER_REQUEST_MAX_SPANS_PER_TRACE` | Max spans buffered per trace. |
+| `A365_PER_REQUEST_MAX_CONCURRENT_EXPORTS` | Max concurrent A365 exports. |
+| `A365_PER_REQUEST_FLUSH_GRACE_MS` | Grace period after a root span ends. |
+| `A365_PER_REQUEST_MAX_TRACE_AGE_MS` | Max trace age before forced flush. |
+
+Set those variables on the process exactly as the Microsoft distro documents
+them; `@cuylabs/agent-microsoft-opentelemetry` does not need adapter-specific
+aliases for them.

package/examples/01-agent365-s2s.ts

@@ -0,0 +1,40 @@
+import { createAgent } from "@cuylabs/agent-core";
+import { openai } from "@ai-sdk/openai";
+import {
+  createMicrosoftA365S2STokenResolverFromEnv,
+  initMicrosoftOpenTelemetry,
+} from "../src/index.js";
+
+const observability = await initMicrosoftOpenTelemetry({
+  resource: {
+    serviceName: process.env.OTEL_SERVICE_NAME ?? "agent-service",
+    serviceVersion: process.env.OTEL_SERVICE_VERSION ?? "0.0.0",
+  },
+  a365: {
+    enabled: true,
+    enableObservabilityExporter:
+      process.env.ENABLE_A365_OBSERVABILITY_EXPORTER === "true",
+    useS2SEndpoint: true,
+    tokenResolver: createMicrosoftA365S2STokenResolverFromEnv(),
+  },
+  azureMonitor: {
+    enabled: Boolean(process.env.APPLICATIONINSIGHTS_CONNECTION_STRING),
+  },
+  instrumentationProfile: "agent-core",
+  agent: {
+    agentId: process.env.A365_OBSERVABILITY_AGENT_ID,
+    agentDescription: "Example Agent 365 S2S agent",
+    recordInputs: true,
+    recordOutputs: true,
+  },
+});
+
+const agent = createAgent({
+  name: "example-agent",
+  model: openai(process.env.OPENAI_MODEL ?? "gpt-4o-mini"),
+  systemPrompt: "You are a concise assistant.",
+  tracing: observability.tracing,
+});
+
+void agent;
+await observability.shutdown();

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@cuylabs/agent-microsoft-opentelemetry",
+  "version": "4.8.0",
+  "description": "Microsoft OpenTelemetry distro adapter for @cuylabs/agent-core",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "import": "./dist/register.js",
+      "default": "./dist/register.js"
+    },
+    "./loader": {
+      "types": "./dist/loader.d.ts",
+      "import": "./dist/loader.js",
+      "default": "./dist/loader.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@ai-sdk/openai": "4.0.0-beta.38",
+    "@types/node": "^22.0.0",
+    "ai": "7.0.0-beta.111",
+    "dotenv": "^17.2.3",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18",
+    "zod": "^3.25.76 || ^4.1.8",
+    "@cuylabs/agent-core": "^4.8.0"
+  },
+  "peerDependencies": {
+    "@cuylabs/agent-core": "^4.0.0",
+    "@microsoft/opentelemetry": ">=1.0.1 <2.0.0",
+    "ai": "7.0.0-beta.111"
+  },
+  "keywords": [
+    "agent",
+    "microsoft",
+    "opentelemetry",
+    "agent365",
+    "a365",
+    "azure-monitor",
+    "observability"
+  ],
+  "author": "cuylabs",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cuylabs-ai/agents-ts.git",
+    "directory": "packages/agent-microsoft-opentelemetry"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/register.ts src/loader.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/register.ts src/loader.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}