@microsoft/agents-telemetry 1.5.0-beta.23.g2277c6f0ab

package/README.md

@@ -0,0 +1,342 @@
+# @microsoft/agents-telemetry
+
+## Overview
+
+The `@microsoft/agents-telemetry` package provides OpenTelemetry instrumentation primitives used across the Microsoft Agents SDK. It enables distributed tracing, structured log emission, and stable metric naming so you can monitor agent interactions, connector calls, storage operations, authentication flows, and turn processing.
+
+The package exports:
+
+- `trace` — span creation with record tracking, custom actions, and lifecycle hooks
+- `debug` — loggers that bridge the `debug` module with OpenTelemetry log records
+- `metric` — histogram and counter creation via the OpenTelemetry Meter API
+- `SpanNames` / `MetricNames` — stable name constants for observability across the SDK
+
+This package supports both ESM and CommonJS consumers and requires Node.js 20 or later.
+
+---
+
+## For Agent Developers
+
+This section covers how to enable and configure telemetry in your agent application. The SDK automatically instruments its components — you only need to wire up OpenTelemetry exporters and, optionally, tune which span categories are active.
+
+### Peer Dependencies
+
+Install the OpenTelemetry API packages in your agent for full integration:
+
+```sh
+npm install @opentelemetry/api @opentelemetry/api-logs
+```
+
+Both are optional. If missing, the SDK falls back to noop implementations and logs a warning. Installing the official packages is recommended for full tracing, metrics, and log export.
+
+### Enabling Tracing
+
+For traces to be exported, configure the OpenTelemetry SDK with an exporter. Console exporter for development:
+
+```ts
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node'
+
+const sdk = new NodeSDK({
+  traceExporter: new ConsoleSpanExporter(),
+  serviceName: 'my-agent-service',
+})
+
+sdk.start()
+```
+
+Once configured, all SDK components that use `trace(...)` will emit spans through the global tracer provider.
+
+To export metrics referenced by `MetricNames`, configure a metric reader/exporter in your OpenTelemetry SDK as well.
+
+#### Production Setup with OTLP Exporter
+
+For production, use an OTLP exporter to send traces to your observability backend (Azure Monitor, Jaeger, Grafana, etc.):
+
+```ts
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
+
+const sdk = new NodeSDK({
+  traceExporter: new OTLPTraceExporter({
+    url: 'http://localhost:4318/v1/traces', // Your OTLP endpoint
+  }),
+  serviceName: 'my-agent-service',
+})
+
+sdk.start()
+```
+
+### Enabling Logs (OTLP)
+
+To export logs produced by `debug` loggers to an OTLP backend, add a logs processor during startup:
+
+```ts
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { resourceFromAttributes } from '@opentelemetry/resources'
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions'
+import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-grpc'
+import { BatchLogRecordProcessor } from '@opentelemetry/sdk-logs'
+
+const otlpEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317'
+
+const sdk = new NodeSDK({
+  resource: resourceFromAttributes({
+    [ATTR_SERVICE_NAME]: 'my-agent-service',
+    [ATTR_SERVICE_VERSION]: '1.0.0',
+  }),
+  logRecordProcessors: [
+    new BatchLogRecordProcessor(new OTLPLogExporter({ url: otlpEndpoint })),
+  ],
+})
+
+sdk.start()
+```
+
+### Disabling Span Categories
+
+All built-in span categories are enabled by default. To disable one or more categories without changing code, set `AGENTS_TELEMETRY_DISABLED_SPAN_CATEGORIES` in your environment:
+
+```env
+AGENTS_TELEMETRY_DISABLED_SPAN_CATEGORIES=STORAGE,AUTHORIZATION
+
+# or
+
+AGENTS_TELEMETRY_DISABLED_SPAN_CATEGORIES=STORAGE AUTHORIZATION
+```
+
+Valid category names are:
+
+- `STORAGE`
+- `AUTHENTICATION`
+- `AUTHORIZATION`
+- `DIALOGS`
+
+When a span category is disabled, instrumented code still runs normally with a noop context — no telemetry is emitted for those spans.
+
+### Span and Metric Names
+
+The SDK uses predefined constants for all span and metric names:
+
+```ts
+import { SpanNames, MetricNames } from '@microsoft/agents-telemetry'
+
+// Example span names:
+SpanNames.ADAPTER_PROCESS          // 'agents.adapter.process'
+SpanNames.AGENTS_APP_RUN           // 'agents.app.run'
+SpanNames.STORAGE_READ             // 'agents.storage.read'
+SpanNames.CONNECTOR_REPLY_TO_ACTIVITY // 'agents.connector.reply_to_activity'
+
+// Example metric names:
+MetricNames.ACTIVITIES_RECEIVED        // 'agents.activities.received'
+MetricNames.CONNECTOR_REQUEST_DURATION // 'agents.connector.request.duration'
+MetricNames.TURN_DURATION              // 'agents.turn.duration'
+MetricNames.AUTH_TOKEN_REQUEST_COUNT   // 'agents.auth.token.request.count'
+// ... and more
+```
+
+---
+
+## For SDK Contributors
+
+This section covers internal APIs used to instrument SDK components. If you are contributing to the Agents SDK packages, use `trace`, `debug`, and `metric` to add observability to your code.
+
+Although this package is published, it primarily serves as a shared telemetry layer for other Agents SDK packages. Some exported TypeScript types intentionally depend on OpenTelemetry packages even though runtime behavior still supports noop fallback when those optional peer dependencies are not installed.
+
+### Using trace
+
+Use `trace` to create validated spans. Every definition requires a `name` from `SpanNames`, a `record` object for tracking state, and an `end` hook called when the span finishes.
+
+#### Callback mode
+
+The span is started and ended automatically around the callback:
+
+```ts
+import { SpanNames, trace } from '@microsoft/agents-telemetry'
+
+const result = await trace(
+  {
+    name: SpanNames.AGENTS_APP_ROUTE_HANDLER,
+    record: { conversationId: '', messageCount: 0 },
+    actions: ({ span }) => ({
+      setAttribute: (key: string, value: string) => span.setAttribute(key, value),
+    }),
+    end: ({ span, record, duration, error }) => {
+      span.setAttribute('conversation.id', record.conversationId)
+      span.setAttribute('message.count', record.messageCount)
+    },
+  },
+  async ({ record, actions }) => {
+    record({ conversationId })
+    actions.setAttribute('code.function', 'handleMessage')
+    const result = await service.handleMessage(conversationId, text)
+    record({ messageCount: result.count })
+    return result
+  }
+)
+```
+
+#### Managed mode (no callback)
+
+For long-lived operations where you need manual control over the span lifecycle:
+
+```ts
+import { SpanNames, trace } from '@microsoft/agents-telemetry'
+
+const { record, actions, end, fail } = trace({
+  name: SpanNames.ADAPTER_PROCESS,
+  record: { status: 'pending' },
+  end: ({ span, record, duration }) => {
+    span.setAttribute('status', record.status)
+  },
+})
+
+try {
+  record({ status: 'processing' })
+  await doWork()
+  record({ status: 'done' })
+  end()
+} catch (error) {
+  fail(error)
+  end()
+  throw error
+}
+```
+
+#### Reusable definitions
+
+Use `trace.define` to declare a trace definition with full type inference, without starting a span:
+
+```ts
+const storageReadTrace = trace.define({
+  name: SpanNames.STORAGE_READ,
+  record: { keys: 0 },
+  end: ({ span, record }) => {
+    span.setAttribute('storage.keys', record.keys)
+  },
+})
+
+// Later:
+trace(storageReadTrace, ({ record }) => {
+  record({ keys: 5 })
+  return storage.read(keys)
+})
+```
+
+#### Behavior details
+
+- On success, the span status is set to `OK`.
+- On failure, the exception is recorded on the span, status is set to `ERROR`, and the error is rethrown.
+- Non-Error thrown values are recorded with their type name and string representation.
+- Unrecognized span names throw immediately.
+- Disabled span categories run the callback with a noop context — no telemetry is emitted.
+- The `end` hook receives `{ span, record, duration, error? }`.
+
+### Using debug
+
+Create loggers that emit to both the `debug` module and OpenTelemetry logs:
+
+```ts
+import { debug } from '@microsoft/agents-telemetry'
+
+const logger = debug('agents:mycomponent')
+logger.info('Processing request', { requestId })
+logger.error('Failed to connect', error)
+```
+
+When `@opentelemetry/api-logs` is available, log records are emitted with severity and namespace attributes. Otherwise, only the `debug` output is produced.
+
+### Using metric
+
+Create OpenTelemetry instruments for recording measurements:
+
+```ts
+import { metric, MetricNames } from '@microsoft/agents-telemetry'
+
+const duration = metric.histogram(MetricNames.TURN_DURATION)
+const counter = metric.counter(MetricNames.ACTIVITIES_RECEIVED)
+
+duration.record(elapsed, { 'activity.type': 'message' })
+counter.add(1, { 'activity.type': 'message' })
+```
+
+When `@opentelemetry/api` is not available, the instruments are safe noops.
+
+### Key Features
+
+- **Automatic span lifecycle**: Spans are started and ended automatically in callback mode
+- **Error recording**: Exceptions are recorded on the span with `ERROR` status
+- **Span name validation**: Unknown span names are rejected early
+- **Record tracking**: Accumulate structured data during a trace and access it in the `end` hook
+- **Custom actions**: Define span-scoped helper functions via the `actions` factory
+- **Category-based disabling**: Disable groups of spans via environment configuration
+- **Noop fallback**: All instrumentation calls are safe no-ops when OpenTelemetry APIs are not installed
+
+---
+
+## API Reference
+
+### `trace(definition)` — Managed mode
+
+Starts a span and returns a managed context with `record`, `actions`, `end`, and `fail` methods.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `definition` | `TraceDefinition` | Trace definition object (see below). |
+
+Returns: `{ record, actions, end, fail }`
+
+### `trace(definition, callback)` — Callback mode
+
+Runs `callback` inside an active span. The span is ended automatically when the callback returns or throws.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `definition` | `TraceDefinition` | Trace definition object (see below). |
+| `callback` | `(context) => TReturn` | Callback receiving `{ record, actions }`. Return value (including a `Promise`) is forwarded. |
+
+Returns: Whatever `callback` returns.
+
+### `TraceDefinition`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `SpanName` | Span name. Must be one of `SpanNames` values. |
+| `record` | `object` | Initial record state. Updated via `record()` during the trace. |
+| `actions` | `(ctx: { span }) => object` | *(Optional)* Factory that receives the span and returns action helpers. |
+| `end` | `(ctx: { span, record, duration, error? }) => void` | Hook called when the span ends. Use it to set final attributes or record metrics. |
+
+### `trace.define(definition)`
+
+Returns the `definition` object as-is. Useful for declaring reusable trace definitions with full type inference.
+
+### `debug(namespace)`
+
+Creates a logger for the given namespace. When `@opentelemetry/api-logs` is available, the logger bridges the `debug` module with OpenTelemetry log emission. Otherwise, it creates a `debug`-only logger.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `namespace` | `string` | Logger namespace (e.g. `'agents:hosting'`). |
+
+Returns: `{ info, warn, error, debug }` — each method accepts a message string and optional arguments.
+
+### `metric`
+
+Provides factory methods for creating OpenTelemetry instruments. When `@opentelemetry/api` is not available, returns noop instruments.
+
+| Method | Description |
+|--------|-------------|
+| `metric.histogram(name)` | Creates a histogram instrument. |
+| `metric.counter(name)` | Creates a counter instrument. |
+
+### `SpanNames`
+
+Provides stable span name constants used by Agents SDK components, including adapter, application, connector, storage, authentication, authorization, user token client, turn-processing, and Copilot Studio client operations.
+
+### `MetricNames`
+
+Provides stable metric name constants for counters and histograms used by Agents SDK components, including activity counts, request counts, turn counts, and duration metrics.
+
+## License
+
+MIT

package/dist/cjs/package.json

@@ -0,0 +1,73 @@
+{
+    "$schema": "https://json.schemastore.org/package.json",
+    "name": "@microsoft/agents-telemetry",
+    "version": "1.5.0-beta.23.g2277c6f0ab",
+    "homepage": "https://github.com/microsoft/Agents-for-js",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/microsoft/Agents-for-js.git"
+    },
+    "author": {
+        "name": "Microsoft",
+        "email": "agentssdk@microsoft.com",
+        "url": "https://aka.ms/Agents"
+    },
+    "description": "Telemetry instrumentation for Microsoft Agents SDK",
+    "keywords": [
+        "Agents",
+        "Telemetry",
+        "OpenTelemetry",
+        "OTel"
+    ],
+    "main": "./dist/cjs/src/index.cjs",
+    "module": "./dist/esm/src/index.mjs",
+    "types": "./dist/esm/src/index.d.mts",
+    "browser": "./dist/esm/src/index.mjs",
+    "scripts": {
+        "clean:esm": "node -e \"require('node:fs').rmSync('dist/esm', { recursive: true, force: true })\"",
+        "build:esm": "tsc --project tsconfig.esm.json && node scripts/esm.mjs"
+    },
+    "peerDependencies": {
+        "@opentelemetry/api": "1",
+        "@opentelemetry/api-logs": ">=0.214.0 <1"
+    },
+    "peerDependenciesMeta": {
+        "@opentelemetry/api": {
+            "optional": true
+        },
+        "@opentelemetry/api-logs": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@opentelemetry/api": "1",
+        "@opentelemetry/api-logs": "0.214.0"
+    },
+    "dependencies": {
+        "debug": "^4.4.3"
+    },
+    "license": "MIT",
+    "files": [
+        "README.md",
+        "dist",
+        "package.json"
+    ],
+    "exports": {
+        ".": {
+            "import": {
+                "types": "./dist/esm/src/index.d.mts",
+                "browser": "./dist/esm/src/index.mjs",
+                "default": "./dist/esm/src/index.mjs"
+            },
+            "require": {
+                "types": "./dist/cjs/src/index.d.cts",
+                "default": "./dist/cjs/src/index.cjs"
+            },
+            "default": "./dist/esm/src/index.mjs"
+        },
+        "./package.json": "./package.json"
+    },
+    "engines": {
+        "node": ">=20.0.0"
+    }
+}

package/dist/cjs/src/index.cjs

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.metric = exports.trace = exports.debug = exports.MetricNames = exports.SpanNames = void 0;
+const index_js_1 = require("./index.js");
+_a = (0, index_js_1.index)({
+    otel: () => require('@opentelemetry/api'),
+    logs: () => require('@opentelemetry/api-logs'),
+}), exports.SpanNames = _a.SpanNames, exports.MetricNames = _a.MetricNames, exports.debug = _a.debug, exports.trace = _a.trace, exports.metric = _a.metric;
+//# sourceMappingURL=index.cjs.map

package/dist/cjs/src/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../../../src/index.cts"],"names":[],"mappings":";AAAA;;;GAGG;;;;AASH,yCAAkC;AAIrB,KAMT,IAAA,gBAAK,EAAC;IACR,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,oBAAoB,CAAS;IACjD,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,yBAAyB,CAAa;CAC3D,CAAC,EARA,iBAAS,iBACT,mBAAW,mBACX,aAAK,aACL,aAAK,aACL,cAAM,aAIN"}

package/dist/cjs/src/index.d.cts

@@ -0,0 +1,93 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export type { TraceDefinition } from './types.js';
+export declare const SpanNames: {
+    readonly ADAPTER_PROCESS: "agents.adapter.process";
+    readonly ADAPTER_SEND_ACTIVITIES: "agents.adapter.send_activities";
+    readonly ADAPTER_UPDATE_ACTIVITY: "agents.adapter.update_activity";
+    readonly ADAPTER_DELETE_ACTIVITY: "agents.adapter.delete_activity";
+    readonly ADAPTER_CONTINUE_CONVERSATION: "agents.adapter.continue_conversation";
+    readonly ADAPTER_CREATE_CONNECTOR_CLIENT: "agents.adapter.create_connector_client";
+    readonly ADAPTER_CREATE_USER_TOKEN_CLIENT: "agents.adapter.create_user_token_client";
+    readonly AGENTS_APP_RUN: "agents.app.run";
+    readonly AGENTS_APP_ROUTE_HANDLER: "agents.app.route_handler";
+    readonly AGENTS_APP_BEFORE_TURN: "agents.app.before_turn";
+    readonly AGENTS_APP_AFTER_TURN: "agents.app.after_turn";
+    readonly AGENTS_APP_DOWNLOAD_FILES: "agents.app.download_files";
+    readonly CONNECTOR_SEND_TO_CONVERSATION: "agents.connector.send_to_conversation";
+    readonly CONNECTOR_REPLY_TO_ACTIVITY: "agents.connector.reply_to_activity";
+    readonly CONNECTOR_UPDATE_ACTIVITY: "agents.connector.update_activity";
+    readonly CONNECTOR_DELETE_ACTIVITY: "agents.connector.delete_activity";
+    readonly CONNECTOR_CREATE_CONVERSATION: "agents.connector.create_conversation";
+    readonly CONNECTOR_GET_CONVERSATIONS: "agents.connector.get_conversations";
+    readonly CONNECTOR_GET_CONVERSATION_MEMBER: "agents.connector.get_conversation_member";
+    readonly CONNECTOR_UPLOAD_ATTACHMENT: "agents.connector.upload_attachment";
+    readonly CONNECTOR_GET_ATTACHMENT: "agents.connector.get_attachment";
+    readonly CONNECTOR_GET_ATTACHMENT_INFO: "agents.connector.get_attachment_info";
+    readonly STORAGE_READ: "agents.storage.read";
+    readonly STORAGE_WRITE: "agents.storage.write";
+    readonly STORAGE_DELETE: "agents.storage.delete";
+    readonly AGENT_CLIENT_POST_ACTIVITY: "agents.agent_client.post_activity";
+    readonly AUTHENTICATION_GET_ACCESS_TOKEN: "agents.authentication.get_access_token";
+    readonly AUTHENTICATION_ACQUIRE_TOKEN_ON_BEHALF_OF: "agents.authentication.acquire_token_on_behalf_of";
+    readonly AUTHENTICATION_GET_AGENTIC_INSTANCE_TOKEN: "agents.authentication.get_agentic_instance_token";
+    readonly AUTHENTICATION_GET_AGENTIC_USER_TOKEN: "agents.authentication.get_agentic_user_token";
+    readonly AUTHORIZATION_AGENTIC_TOKEN: "agents.authorization.agentic_token";
+    readonly AUTHORIZATION_AZURE_BOT_TOKEN: "agents.authorization.azure_bot_token";
+    readonly AUTHORIZATION_AZURE_BOT_SIGNIN: "agents.authorization.azure_bot_signin";
+    readonly AUTHORIZATION_AZURE_BOT_SIGNOUT: "agents.authorization.azure_bot_signout";
+    readonly USER_TOKEN_CLIENT_GET_USER_TOKEN: "agents.user_token_client.get_user_token";
+    readonly USER_TOKEN_CLIENT_SIGN_OUT: "agents.user_token_client.sign_out";
+    readonly USER_TOKEN_CLIENT_GET_SIGN_IN_RESOURCE: "agents.user_token_client.get_sign_in_resource";
+    readonly USER_TOKEN_CLIENT_EXCHANGE_TOKEN: "agents.user_token_client.exchange_token";
+    readonly USER_TOKEN_CLIENT_GET_TOKEN_OR_SIGN_IN_RESOURCE: "agents.user_token_client.get_token_or_sign_in_resource";
+    readonly USER_TOKEN_CLIENT_GET_TOKEN_STATUS: "agents.user_token_client.get_token_status";
+    readonly USER_TOKEN_CLIENT_GET_AAD_TOKENS: "agents.user_token_client.get_aad_tokens";
+    readonly PROACTIVE_STORE_CONVERSATION: "agents.proactive.store_conversation";
+    readonly PROACTIVE_GET_CONVERSATION: "agents.proactive.get_conversation";
+    readonly PROACTIVE_GET_CONVERSATION_OR_THROW: "agents.proactive.get_conversation_or_throw";
+    readonly PROACTIVE_DELETE_CONVERSATION: "agents.proactive.delete_conversation";
+    readonly PROACTIVE_SEND_ACTIVITY: "agents.proactive.send_activity";
+    readonly PROACTIVE_CONTINUE_CONVERSATION: "agents.proactive.continue_conversation";
+    readonly PROACTIVE_CREATE_CONVERSATION: "agents.proactive.create_conversation";
+    readonly TURN_SEND_ACTIVITIES: "agents.turn.send_activities";
+    readonly COPILOT_START_CONVERSATION: "agents.copilot_client.start_conversation";
+    readonly COPILOT_SEND_ACTIVITY: "agents.copilot_client.send_activity";
+    readonly COPILOT_POST_REQUEST: "agents.copilot_client.post_request";
+    readonly COPILOT_CREATE_CONNECTION: "agents.copilot_client.webchat.create_connection";
+    readonly COPILOT_EXECUTE_STREAMING: "agents.copilot_client.execute_streaming";
+    readonly COPILOT_SUBSCRIBE_ASYNC: "agents.copilot_client.subscribe_async";
+}, MetricNames: {
+    readonly ADAPTER_PROCESS_DURATION: "agents.adapter.process.duration";
+    readonly ACTIVITIES_RECEIVED: "agents.activities.received";
+    readonly ACTIVITIES_SENT: "agents.activities.sent";
+    readonly ACTIVITIES_UPDATED: "agents.activities.updated";
+    readonly ACTIVITIES_DELETED: "agents.activities.deleted";
+    readonly CONNECTOR_REQUESTS: "agents.connector.request.count";
+    readonly CONNECTOR_REQUEST_DURATION: "agents.connector.request.duration";
+    readonly AGENT_CLIENT_REQUESTS: "agents.agent_client.request.count";
+    readonly AGENT_CLIENT_REQUEST_DURATION: "agents.agent_client.request.duration";
+    readonly TURNS_COUNT: "agents.turn.count";
+    readonly TURNS_ERRORS: "agents.turn.error.count";
+    readonly TURN_DURATION: "agents.turn.duration";
+    readonly STORAGE_OPERATION_DURATION: "agents.storage.operation.duration";
+    readonly AUTH_TOKEN_REQUEST_COUNT: "agents.auth.token.request.count";
+    readonly AUTH_TOKEN_DURATION: "agents.auth.token.duration";
+    readonly USER_TOKEN_CLIENT_REQUESTS: "agents.user_token_client.request.count";
+    readonly USER_TOKEN_CLIENT_REQUEST_DURATION: "agents.user_token_client.request.duration";
+    readonly PROACTIVE_OPERATION_COUNT: "agents.proactive.operation.count";
+    readonly PROACTIVE_OPERATION_DURATION: "agents.proactive.operation.duration";
+    readonly CSC_ACTIVITIES_RECEIVED: "agents.copilot_client.activities.received";
+    readonly CSC_ACTIVITIES_SENT: "agents.copilot_client.activities.sent";
+    readonly CSC_CONVERSATIONS_STARTED: "agents.copilot_client.conversations.started";
+    readonly CSC_WEBCHAT_CONNECTIONS: "agents.copilot_client.webchat.connection.count";
+    readonly CSC_REQUEST_COUNT: "agents.copilot_client.request.count";
+    readonly CSC_REQUEST_ERRORS: "agents.copilot_client.request.error.count";
+    readonly CSC_STREAM_DURATION: "agents.copilot_client.stream.duration";
+    readonly CSC_REQUEST_DURATION: "agents.copilot_client.request.duration";
+    readonly CSC_EXECUTE_STREAMING: "agents.copilot_client.execute_streaming.count";
+    readonly CSC_SUBSCRIBE_ASYNC: "agents.copilot_client.subscribe_async.count";
+    readonly CSC_SUBSCRIBE_EVENT: "agents.copilot_client.subscribe_event.count";
+}, debug: (namespace: string) => import("./loggers/base.js").Logger, trace: import("./types.js").TraceFunction, metric: import("./types.js").Metric;

package/dist/cjs/src/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { Loader, LoaderReturn } from './types.js';
+/**
+ * Loads the optional OpenTelemetry dependencies and returns the telemetry factory used by the package entrypoints.
+ *
+ * @remarks
+ * - The loader can be synchronous or asynchronous.
+ * - Missing optional dependencies only disable the related feature and emit a warning.
+ */
+export declare function index<TLoader extends Loader>(loader: TLoader): LoaderReturn<TLoader>;

package/dist/cjs/src/index.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.index = index;
+const trace_js_1 = require("./observability/trace.js");
+const metric_js_1 = require("./observability/metric.js");
+const debug_js_1 = require("./loggers/debug.js");
+const otel_js_1 = require("./loggers/otel.js");
+const attempt_js_1 = require("./utils/attempt.js");
+const constants_js_1 = require("./observability/constants.js");
+const noop_js_1 = require("./utils/noop.js");
+const logger = (0, debug_js_1.createDebugLogger)('agents:telemetry');
+/**
+ * Loads the optional OpenTelemetry dependencies and returns the telemetry factory used by the package entrypoints.
+ *
+ * @remarks
+ * - The loader can be synchronous or asynchronous.
+ * - Missing optional dependencies only disable the related feature and emit a warning.
+ */
+function index(loader) {
+    const otel = (0, attempt_js_1.attempt)({
+        try: () => loader.otel(),
+        catch: () => logger.warn('OpenTelemetry API not found. Install @opentelemetry/api as a dependency to enable tracing and metrics.')
+    });
+    const logs = (0, attempt_js_1.attempt)({
+        try: () => loader.logs(),
+        catch: () => logger.warn('OpenTelemetry API Logs not found. Install @opentelemetry/api-logs as a dependency to enable OTel logging.')
+    });
+    if ((0, attempt_js_1.isPromise)(otel) || (0, attempt_js_1.isPromise)(logs)) {
+        return Promise.all([otel, logs])
+            .then(([otel, logs]) => factory(otel, logs));
+    }
+    return factory(otel, logs);
+}
+/**
+ * Creates the runtime telemetry surface exposed by the package.
+ *
+ * @remarks
+ * - Logging combines debug output with OpenTelemetry logs when log support is available.
+ * - Trace and metric helpers fall back to no-op implementations when the OTel API is not installed.
+ */
+function factory(otel, logs) {
+    return {
+        SpanNames: constants_js_1.SpanNames,
+        MetricNames: constants_js_1.MetricNames,
+        debug: logs ? ns => (0, debug_js_1.link)((0, debug_js_1.createDebugLogger)(ns), (0, otel_js_1.createOTelLogger)(logs, ns)) : debug_js_1.createDebugLogger,
+        trace: otel ? (0, trace_js_1.traceFactory)(otel) : noop_js_1.noopTrace,
+        metric: otel ? (0, metric_js_1.metricFactory)(otel) : (0, noop_js_1.noopMetric)(),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/cjs/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAqBH,sBAiBC;AAnCD,uDAAuD;AACvD,yDAAyD;AACzD,iDAA4D;AAC5D,+CAAoD;AACpD,mDAAuD;AAEvD,+DAAqE;AACrE,6CAAuD;AAEvD,MAAM,MAAM,GAAG,IAAA,4BAAiB,EAAC,kBAAkB,CAAC,CAAA;AAEpD;;;;;;GAMG;AACH,SAAgB,KAAK,CAA0B,MAAe;IAC5D,MAAM,IAAI,GAAG,IAAA,oBAAO,EAAC;QACnB,GAAG,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAAU;QAChC,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,wGAAwG,CAAC;KACnI,CAAC,CAAA;IAEF,MAAM,IAAI,GAAG,IAAA,oBAAO,EAAC;QACnB,GAAG,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAAc;QACpC,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,2GAA2G,CAAC;KACtI,CAAC,CAAA;IAEF,IAAI,IAAA,sBAAS,EAAC,IAAI,CAAC,IAAI,IAAA,sBAAS,EAAC,IAAI,CAAC,EAAE,CAAC;QACvC,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;aAC7B,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAA0B,CAAA;IACzE,CAAC;IAED,OAAO,OAAO,CAAC,IAAI,EAAE,IAAI,CAA0B,CAAA;AACrD,CAAC;AAED;;;;;;GAMG;AACH,SAAS,OAAO,CAAE,IAAW,EAAE,IAAe;IAC5C,OAAO;QACL,SAAS,EAAT,wBAAS;QACT,WAAW,EAAX,0BAAW;QACX,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,IAAA,eAAI,EAAC,IAAA,4BAAiB,EAAC,EAAE,CAAC,EAAE,IAAA,0BAAgB,EAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,4BAAiB;QAC/F,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,IAAA,uBAAY,EAAC,IAAI,CAAC,CAAC,CAAC,CAAC,mBAAS;QAC5C,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,IAAA,yBAAa,EAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAA,oBAAU,GAAE;KAClD,CAAA;AACH,CAAC"}

package/dist/cjs/src/loggers/base.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Logger interface used by the Agents SDK telemetry surface.
+ */
+export interface Logger {
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+    debug(message: string, ...args: any[]): void;
+}
+/**
+ * Supported logger method names.
+ */
+export type LoggerLevel = keyof Logger;
+/**
+ * Ordered list of logger levels used when composing logger implementations.
+ */
+export declare const levels: LoggerLevel[];

package/dist/cjs/src/loggers/base.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.levels = void 0;
+/**
+ * Ordered list of logger levels used when composing logger implementations.
+ */
+exports.levels = ['info', 'warn', 'error', 'debug'];
+//# sourceMappingURL=base.js.map

package/dist/cjs/src/loggers/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../../src/loggers/base.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAiBH;;GAEG;AACU,QAAA,MAAM,GAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAU,CAAA"}

package/dist/cjs/src/loggers/debug.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import createDebug from 'debug';
+import type { LoggerLevel, Logger as BaseLogger } from './base.js';
+type Logger = Record<LoggerLevel, createDebug.Debugger>;
+/**
+ * Creates a debug logger with the specified namespace and log levels. The logger will use different colors for each log level and will work in both Node.js and browser environments.
+ */
+export declare function createDebugLogger(namespace: string): Logger;
+/**
+ * Links the debug logger with additional logger implementations.
+ *
+ * @remarks
+ * - Linked loggers only receive messages when the corresponding debug namespace is enabled.
+ */
+export declare function link(debugLogger: Logger, ...loggers: BaseLogger[]): BaseLogger;
+export {};