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

package/dist/esm/src/observability/category.js

@@ -0,0 +1,64 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { AGENTS_TELEMETRY_DISABLED_SPAN_CATEGORIES, SpanCategories, SpanNames } from './constants.js';
+import { createDebugLogger } from '../loggers/debug.js';
+import { getSetting } from '../utils/setting.js';
+const logger = createDebugLogger('agents:telemetry');
+/**
+ * Resolves disabled spans once at module load time.
+ *
+ * @remarks
+ * - Unknown categories are ignored and logged as warnings.
+ * - Duplicate categories are de-duplicated by prefix before span names are expanded.
+ */
+const disabledSpans = (() => {
+    const rawValue = getSetting(AGENTS_TELEMETRY_DISABLED_SPAN_CATEGORIES).trim().toUpperCase();
+    if (!rawValue) {
+        return [];
+    }
+    const envCategories = rawValue
+        .split(/[\s,]+/)
+        .map((category) => category.trim())
+        .filter(Boolean);
+    const spanNames = Object.entries(SpanNames);
+    const processed = new Set();
+    const result = [];
+    for (const category of envCategories) {
+        const prefixes = SpanCategories[category];
+        if (!prefixes) {
+            logger.warn(`Invalid span category "${category}" in ${AGENTS_TELEMETRY_DISABLED_SPAN_CATEGORIES}. Valid categories are: ${Object.keys(SpanCategories).join(', ')}`);
+            continue;
+        }
+        for (const prefix of prefixes) {
+            if (processed.has(prefix)) {
+                continue;
+            }
+            processed.add(prefix);
+            for (const [key, name] of spanNames) {
+                if (key.startsWith(prefix)) {
+                    result.push(name);
+                }
+            }
+        }
+    }
+    if (result.length > 0) {
+        logger.debug('Disabled Span names:', result);
+    }
+    return result;
+})();
+/**
+ * Determines if a span is disabled based on its name and the `AGENTS_TELEMETRY_DISABLED_SPAN_CATEGORIES` environment variable or configuration setting.
+ * @param name The name of the span to check.
+ * @returns A boolean indicating whether the span is disabled.
+ */
+export function isSpanDisabled(name) {
+    if (disabledSpans.length === 0) {
+        return false;
+    }
+    const result = disabledSpans.includes(name);
+    logger.debug(`Span "${name}" disabled:`, result);
+    return result;
+}
+//# sourceMappingURL=category.js.map

package/dist/esm/src/observability/category.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"category.js","sourceRoot":"","sources":["../../../../src/observability/category.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,yCAAyC,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AACrG,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAEvD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAEhD,MAAM,MAAM,GAAG,iBAAiB,CAAC,kBAAkB,CAAC,CAAA;AAEpD;;;;;;GAMG;AACH,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE;IAC1B,MAAM,QAAQ,GAAG,UAAU,CAAC,yCAAyC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IAC3F,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,EAAE,CAAA;IACX,CAAC;IAED,MAAM,aAAa,GAAG,QAAQ;SAC3B,KAAK,CAAC,QAAQ,CAAC;SACf,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;SAClC,MAAM,CAAC,OAAO,CAAC,CAAA;IAElB,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IAE3C,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAA;IACnC,MAAM,MAAM,GAAe,EAAE,CAAA;IAC7B,KAAK,MAAM,QAAQ,IAAI,aAAa,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,cAAc,CAAC,QAAuC,CAAC,CAAA;QACxE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,CAAC,IAAI,CAAC,0BAA0B,QAAQ,QAAQ,yCAAyC,2BAA2B,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;YACnK,SAAQ;QACV,CAAC;QACD,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;YAC9B,IAAI,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC1B,SAAQ;YACV,CAAC;YACD,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YAErB,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,SAAS,EAAE,CAAC;gBACpC,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC3B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBACnB,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,CAAC,KAAK,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAA;IAC9C,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC,CAAC,EAAE,CAAA;AAEJ;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAE,IAAc;IAC5C,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IAC3C,MAAM,CAAC,KAAK,CAAC,SAAS,IAAI,aAAa,EAAE,MAAM,CAAC,CAAA;IAChD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/esm/src/observability/constants.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Environment variable or configuration setting name for disabling spans by category in the Agents SDK telemetry. The value should be comma-separated or whitespace-separated list of span categories to disable. See `SpanCategories` for available categories.
+ */
+export declare const AGENTS_TELEMETRY_DISABLED_SPAN_CATEGORIES = "AGENTS_TELEMETRY_DISABLED_SPAN_CATEGORIES";
+/**
+ * Categories of spans used for telemetry in the Agents SDK. Spans can be disabled by category using the `AGENTS_TELEMETRY_DISABLED_SPAN_CATEGORIES` environment variable or configuration setting.
+ */
+export declare const SpanCategories: {
+    readonly STORAGE: readonly ["STORAGE_"];
+    readonly AUTHORIZATION: readonly ["AUTHORIZATION_", "USER_TOKEN_CLIENT_"];
+    readonly AUTHENTICATION: readonly ["AUTHENTICATION_"];
+};
+/**
+ * Span names used for telemetry in the Agents SDK.
+ */
+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";
+};
+/**
+ * Metric names used for telemetry in the Agents SDK.
+ */
+export declare const 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";
+};

package/dist/esm/src/observability/constants.js

@@ -0,0 +1,133 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Environment variable or configuration setting name for disabling spans by category in the Agents SDK telemetry. The value should be comma-separated or whitespace-separated list of span categories to disable. See `SpanCategories` for available categories.
+ */
+export const AGENTS_TELEMETRY_DISABLED_SPAN_CATEGORIES = 'AGENTS_TELEMETRY_DISABLED_SPAN_CATEGORIES';
+/**
+ * Categories of spans used for telemetry in the Agents SDK. Spans can be disabled by category using the `AGENTS_TELEMETRY_DISABLED_SPAN_CATEGORIES` environment variable or configuration setting.
+ */
+export const SpanCategories = {
+    STORAGE: ['STORAGE_'],
+    AUTHORIZATION: ['AUTHORIZATION_', 'USER_TOKEN_CLIENT_'],
+    AUTHENTICATION: ['AUTHENTICATION_'],
+};
+/**
+ * Span names used for telemetry in the Agents SDK.
+ */
+export const SpanNames = {
+    // CloudAdapter / BaseAdapter
+    ADAPTER_PROCESS: 'agents.adapter.process',
+    ADAPTER_SEND_ACTIVITIES: 'agents.adapter.send_activities',
+    ADAPTER_UPDATE_ACTIVITY: 'agents.adapter.update_activity',
+    ADAPTER_DELETE_ACTIVITY: 'agents.adapter.delete_activity',
+    ADAPTER_CONTINUE_CONVERSATION: 'agents.adapter.continue_conversation',
+    ADAPTER_CREATE_CONNECTOR_CLIENT: 'agents.adapter.create_connector_client',
+    ADAPTER_CREATE_USER_TOKEN_CLIENT: 'agents.adapter.create_user_token_client',
+    // AgentApplication
+    AGENTS_APP_RUN: 'agents.app.run',
+    AGENTS_APP_ROUTE_HANDLER: 'agents.app.route_handler',
+    AGENTS_APP_BEFORE_TURN: 'agents.app.before_turn',
+    AGENTS_APP_AFTER_TURN: 'agents.app.after_turn',
+    AGENTS_APP_DOWNLOAD_FILES: 'agents.app.download_files',
+    // ConnectorClient
+    CONNECTOR_SEND_TO_CONVERSATION: 'agents.connector.send_to_conversation',
+    CONNECTOR_REPLY_TO_ACTIVITY: 'agents.connector.reply_to_activity',
+    CONNECTOR_UPDATE_ACTIVITY: 'agents.connector.update_activity',
+    CONNECTOR_DELETE_ACTIVITY: 'agents.connector.delete_activity',
+    CONNECTOR_CREATE_CONVERSATION: 'agents.connector.create_conversation',
+    CONNECTOR_GET_CONVERSATIONS: 'agents.connector.get_conversations',
+    CONNECTOR_GET_CONVERSATION_MEMBER: 'agents.connector.get_conversation_member',
+    CONNECTOR_UPLOAD_ATTACHMENT: 'agents.connector.upload_attachment',
+    CONNECTOR_GET_ATTACHMENT: 'agents.connector.get_attachment',
+    CONNECTOR_GET_ATTACHMENT_INFO: 'agents.connector.get_attachment_info',
+    // Storage
+    STORAGE_READ: 'agents.storage.read',
+    STORAGE_WRITE: 'agents.storage.write',
+    STORAGE_DELETE: 'agents.storage.delete',
+    // AgentClient
+    AGENT_CLIENT_POST_ACTIVITY: 'agents.agent_client.post_activity',
+    // Authentication
+    AUTHENTICATION_GET_ACCESS_TOKEN: 'agents.authentication.get_access_token',
+    AUTHENTICATION_ACQUIRE_TOKEN_ON_BEHALF_OF: 'agents.authentication.acquire_token_on_behalf_of',
+    AUTHENTICATION_GET_AGENTIC_INSTANCE_TOKEN: 'agents.authentication.get_agentic_instance_token',
+    AUTHENTICATION_GET_AGENTIC_USER_TOKEN: 'agents.authentication.get_agentic_user_token',
+    // Authorization
+    AUTHORIZATION_AGENTIC_TOKEN: 'agents.authorization.agentic_token',
+    AUTHORIZATION_AZURE_BOT_TOKEN: 'agents.authorization.azure_bot_token',
+    AUTHORIZATION_AZURE_BOT_SIGNIN: 'agents.authorization.azure_bot_signin',
+    AUTHORIZATION_AZURE_BOT_SIGNOUT: 'agents.authorization.azure_bot_signout',
+    // UserTokenClient
+    USER_TOKEN_CLIENT_GET_USER_TOKEN: 'agents.user_token_client.get_user_token',
+    USER_TOKEN_CLIENT_SIGN_OUT: 'agents.user_token_client.sign_out',
+    USER_TOKEN_CLIENT_GET_SIGN_IN_RESOURCE: 'agents.user_token_client.get_sign_in_resource',
+    USER_TOKEN_CLIENT_EXCHANGE_TOKEN: 'agents.user_token_client.exchange_token',
+    USER_TOKEN_CLIENT_GET_TOKEN_OR_SIGN_IN_RESOURCE: 'agents.user_token_client.get_token_or_sign_in_resource',
+    USER_TOKEN_CLIENT_GET_TOKEN_STATUS: 'agents.user_token_client.get_token_status',
+    USER_TOKEN_CLIENT_GET_AAD_TOKENS: 'agents.user_token_client.get_aad_tokens',
+    // Proactive
+    PROACTIVE_STORE_CONVERSATION: 'agents.proactive.store_conversation',
+    PROACTIVE_GET_CONVERSATION: 'agents.proactive.get_conversation',
+    PROACTIVE_GET_CONVERSATION_OR_THROW: 'agents.proactive.get_conversation_or_throw',
+    PROACTIVE_DELETE_CONVERSATION: 'agents.proactive.delete_conversation',
+    PROACTIVE_SEND_ACTIVITY: 'agents.proactive.send_activity',
+    PROACTIVE_CONTINUE_CONVERSATION: 'agents.proactive.continue_conversation',
+    PROACTIVE_CREATE_CONVERSATION: 'agents.proactive.create_conversation',
+    // TurnContext
+    TURN_SEND_ACTIVITIES: 'agents.turn.send_activities',
+    // Copilot Studio Client
+    COPILOT_START_CONVERSATION: 'agents.copilot_client.start_conversation',
+    COPILOT_SEND_ACTIVITY: 'agents.copilot_client.send_activity',
+    COPILOT_POST_REQUEST: 'agents.copilot_client.post_request',
+    COPILOT_CREATE_CONNECTION: 'agents.copilot_client.webchat.create_connection',
+    COPILOT_EXECUTE_STREAMING: 'agents.copilot_client.execute_streaming',
+    COPILOT_SUBSCRIBE_ASYNC: 'agents.copilot_client.subscribe_async',
+};
+/**
+ * Metric names used for telemetry in the Agents SDK.
+ */
+export const MetricNames = {
+    // CloudAdapter
+    ADAPTER_PROCESS_DURATION: 'agents.adapter.process.duration',
+    // Hosting activity counters
+    ACTIVITIES_RECEIVED: 'agents.activities.received',
+    ACTIVITIES_SENT: 'agents.activities.sent',
+    ACTIVITIES_UPDATED: 'agents.activities.updated',
+    ACTIVITIES_DELETED: 'agents.activities.deleted',
+    // Connector metrics
+    CONNECTOR_REQUESTS: 'agents.connector.request.count',
+    CONNECTOR_REQUEST_DURATION: 'agents.connector.request.duration',
+    // AgentClient metrics
+    AGENT_CLIENT_REQUESTS: 'agents.agent_client.request.count',
+    AGENT_CLIENT_REQUEST_DURATION: 'agents.agent_client.request.duration',
+    // Turn metrics
+    TURNS_COUNT: 'agents.turn.count',
+    TURNS_ERRORS: 'agents.turn.error.count',
+    TURN_DURATION: 'agents.turn.duration',
+    // Storage metrics
+    STORAGE_OPERATION_DURATION: 'agents.storage.operation.duration',
+    // Authentication metrics
+    AUTH_TOKEN_REQUEST_COUNT: 'agents.auth.token.request.count',
+    AUTH_TOKEN_DURATION: 'agents.auth.token.duration',
+    // UserTokenClient metrics
+    USER_TOKEN_CLIENT_REQUESTS: 'agents.user_token_client.request.count',
+    USER_TOKEN_CLIENT_REQUEST_DURATION: 'agents.user_token_client.request.duration',
+    // Proactive
+    PROACTIVE_OPERATION_COUNT: 'agents.proactive.operation.count',
+    PROACTIVE_OPERATION_DURATION: 'agents.proactive.operation.duration',
+    // Copilot Studio Client
+    CSC_ACTIVITIES_RECEIVED: 'agents.copilot_client.activities.received',
+    CSC_ACTIVITIES_SENT: 'agents.copilot_client.activities.sent',
+    CSC_CONVERSATIONS_STARTED: 'agents.copilot_client.conversations.started',
+    CSC_WEBCHAT_CONNECTIONS: 'agents.copilot_client.webchat.connection.count',
+    CSC_REQUEST_COUNT: 'agents.copilot_client.request.count',
+    CSC_REQUEST_ERRORS: 'agents.copilot_client.request.error.count',
+    CSC_STREAM_DURATION: 'agents.copilot_client.stream.duration',
+    CSC_REQUEST_DURATION: 'agents.copilot_client.request.duration',
+    CSC_EXECUTE_STREAMING: 'agents.copilot_client.execute_streaming.count',
+    CSC_SUBSCRIBE_ASYNC: 'agents.copilot_client.subscribe_async.count',
+    CSC_SUBSCRIBE_EVENT: 'agents.copilot_client.subscribe_event.count',
+};
+//# sourceMappingURL=constants.js.map

package/dist/esm/src/observability/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../src/observability/constants.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/observability/metric.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { Metric, OTel } from '../types.js';
+/**
+ * Creates metric helpers backed by the package meter.
+ */
+export declare function metricFactory(otel: OTel): Metric;

package/dist/esm/src/observability/metric.js

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Creates metric helpers backed by the package meter.
+ */
+export function metricFactory(otel) {
+    const meter = otel.metrics.getMeter('@microsoft/agents-telemetry');
+    return {
+        histogram: meter.createHistogram.bind(meter),
+        counter: meter.createCounter.bind(meter),
+    };
+}
+//# sourceMappingURL=metric.js.map

package/dist/esm/src/observability/metric.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric.js","sourceRoot":"","sources":["../../../../src/observability/metric.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;GAEG;AACH,MAAM,UAAU,aAAa,CAAE,IAAU;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,6BAA6B,CAAC,CAAA;IAClE,OAAO;QACL,SAAS,EAAE,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC;QAC5C,OAAO,EAAE,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC;KACzC,CAAA;AACH,CAAC"}

package/dist/esm/src/observability/trace.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { OTel, TraceFunction } from '../types.js';
+/**
+ * Creates the trace helper bound to the package tracer.
+ *
+ * @remarks
+ * - Only span names declared in `SpanNames` are accepted.
+ * - Disabled span categories return a no-op context instead of creating a real span.
+ */
+export declare function traceFactory(otel: OTel): TraceFunction;

package/dist/esm/src/observability/trace.js

@@ -0,0 +1,132 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { attempt } from '../utils/attempt.js';
+import { isSpanDisabled } from './category.js';
+import { SpanNames } from './constants.js';
+import { noopContext } from '../utils/noop.js';
+/**
+ * Creates the trace helper bound to the package tracer.
+ *
+ * @remarks
+ * - Only span names declared in `SpanNames` are accepted.
+ * - Disabled span categories return a no-op context instead of creating a real span.
+ */
+export function traceFactory(otel) {
+    const validSpanNames = new Set(Object.values(SpanNames));
+    const tracer = otel.trace.getTracer('@microsoft/agents-telemetry');
+    const trace = function trace(target, callback) {
+        if (!target) {
+            throw new Error('Trace definition is required');
+        }
+        if (!validSpanNames.has(target.name)) {
+            throw new Error(`Unrecognized span name "${target.name}". See SpanNames constants.`);
+        }
+        if (isSpanDisabled(target.name)) {
+            return noopContext(callback);
+        }
+        const record = createRecord(target);
+        if (!callback) {
+            // TODO: if parent/child span connections are needed, we could expose a 'child' function that internally connects them.
+            const span = tracer.startSpan(target.name);
+            const flow = start(otel, target, span, record);
+            return {
+                record: flow.record,
+                actions: flow.actions,
+                fail: flow.fail,
+                end: flow.end
+            };
+        }
+        return tracer.startActiveSpan(target.name, span => {
+            const flow = start(otel, target, span, record);
+            return attempt({
+                try: () => callback({ record: flow.record, actions: flow.actions }),
+                catch: (error) => { throw flow.fail(error); },
+                finally: flow.end
+            });
+        });
+    };
+    trace.define = definition => definition;
+    return trace;
+}
+/**
+ * Creates the mutable record stored for a trace execution.
+ *
+ * @remarks
+ * - Updates use `Object.assign`, so nested objects are replaced rather than deeply merged.
+ */
+function createRecord(target) {
+    const state = target.record ? { ...target.record } : {};
+    return {
+        set(values) {
+            // TODO: use deep-merge strategy for Object and Array
+            Object.assign(state, values);
+        },
+        get() {
+            return state;
+        }
+    };
+}
+/**
+ * Initializes a trace execution and returns the action helpers plus end/fail controls.
+ */
+function start(otel, target, span, record) {
+    var _a, _b;
+    const start = performance.now();
+    let ended = false;
+    let _error;
+    return {
+        record: record.set,
+        actions: (_b = (_a = target.actions) === null || _a === void 0 ? void 0 : _a.call(target, { span })) !== null && _b !== void 0 ? _b : {},
+        fail(error) {
+            _error = error;
+            return error;
+        },
+        end() {
+            if (ended || !otel) {
+                return;
+            }
+            ended = true;
+            if (_error === undefined) {
+                span.setStatus({ code: otel.SpanStatusCode.OK });
+            }
+            else {
+                captureError(otel, span, _error);
+            }
+            try {
+                target.end({
+                    span,
+                    record: record.get(),
+                    duration: performance.now() - start,
+                    error: _error,
+                });
+            }
+            catch (endError) {
+                captureError(otel, span, endError);
+            }
+            finally {
+                span.end();
+            }
+        }
+    };
+}
+/**
+ * Records an error on the span and sets the span status to `ERROR`.
+ *
+ * @remarks
+ * - Non-`Error` values are stringified so thrown primitives are still captured.
+ */
+function captureError(otel, span, error) {
+    let message;
+    if (error instanceof Error) {
+        message = error.message;
+        span.recordException(error);
+    }
+    else {
+        message = String(error);
+        span.recordException({ name: String(typeof error), message });
+    }
+    span.setStatus({ code: otel.SpanStatusCode.ERROR, message });
+}
+//# sourceMappingURL=trace.js.map

package/dist/esm/src/observability/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../../../src/observability/trace.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { Logger } from './loggers/base.js';
+import { MetricNames, SpanNames } from './observability/constants.js';
+import type { Span, Meter } from '@opentelemetry/api';
+/**
+ * These type re-exports are intentional.
+ *
+ * @remarks
+ * This package is primarily a shared telemetry layer for other Agents SDK packages, so its
+ * TypeScript surface may depend on OpenTelemetry types even when runtime loading falls back
+ * to noop behavior if the optional dependencies are absent.
+ */
+export type * from '@opentelemetry/api';
+export type { Span, Meter } from '@opentelemetry/api';
+export type * from '@opentelemetry/api-logs';
+/**
+ * Runtime type for the optional OpenTelemetry API module.
+ */
+export type OTel = typeof import('@opentelemetry/api');
+/**
+ * Runtime type for the optional OpenTelemetry logs module.
+ */
+export type OTelLogs = typeof import('@opentelemetry/api-logs');
+/**
+ * Union of the supported span names exposed by the package constants.
+ */
+export type SpanName = typeof SpanNames[keyof typeof SpanNames];
+/**
+ * Mutable state container used while a trace is active.
+ *
+ * @remarks
+ * - `set()` performs a shallow merge.
+ * - `get()` returns the latest snapshot stored for the span.
+ */
+export interface TraceRecord<TRecord extends object> {
+    set(values: Partial<TRecord>): void;
+    get(): Readonly<TRecord>;
+}
+/**
+ * Context passed to traced callbacks.
+ */
+export interface TraceContext<TRecord extends object, TActions extends object> {
+    record(values: Partial<TRecord>): void;
+    actions: TActions;
+}
+/**
+ * Callback used by callback-based trace execution.
+ */
+export type TraceCallback<TRecord extends object, TActions extends object, TReturn = unknown> = (context: TraceContext<TRecord, TActions>) => TReturn;
+/**
+ * Context used to create action helpers backed by the underlying span.
+ */
+export interface TraceActionsContext {
+    span: Span;
+}
+/**
+ * Data provided to the `end` hook when a trace finishes.
+ */
+export interface TraceEndContext<TRecord extends object> {
+    span: Span;
+    record: Readonly<TRecord>;
+    duration: number;
+    error?: unknown;
+}
+/**
+ * Handle returned when a trace is created without a callback.
+ */
+export interface TraceManagedContext<TRecord extends object, TActions extends object> extends TraceContext<TRecord, TActions> {
+    end(): void;
+    fail<T extends unknown>(error: T): T;
+}
+/**
+ * Declares how a span should be created, enriched, and finalized.
+ *
+ * @remarks
+ * - `name` must come from `SpanNames`.
+ * - `record` provides the default shape for values collected during the span lifetime.
+ */
+export interface TraceDefinition<TRecord extends object = Record<string, never>, TActions extends object = Record<string, Function>> {
+    name: SpanName;
+    record: TRecord;
+    actions?(context: TraceActionsContext): TActions;
+    end(context: TraceEndContext<TRecord>): void;
+}
+/**
+ * Trace helper that supports both managed spans and callback-based spans.
+ */
+export interface TraceFunction {
+    define<TRecord extends object, TActions extends object>(definition: TraceDefinition<TRecord, TActions>): TraceDefinition<TRecord, TActions>;
+    <TRecord extends object, TActions extends object>(definition: TraceDefinition<TRecord, TActions>): TraceManagedContext<TRecord, TActions>;
+    <TRecord extends object, TActions extends object, TReturn>(definition: TraceDefinition<TRecord, TActions>, callback: TraceCallback<TRecord, TActions, TReturn>): TReturn;
+}
+/**
+ * Metric factory surface exposed by the package.
+ */
+export interface Metric {
+    histogram: Meter['createHistogram'];
+    counter: Meter['createCounter'];
+}
+/**
+ * Loader interface for the index function, which conditionally loads OpenTelemetry dependencies at runtime.
+ */
+export interface Loader {
+    otel(): OTel | Promise<OTel>;
+    logs(): OTelLogs | Promise<OTelLogs>;
+}
+/**
+ * Conditional return type for the index loader function, based on whether the loader returns Promises.
+ */
+export type LoaderReturn<TLoader extends Loader> = Extract<ReturnType<TLoader['otel']> | ReturnType<TLoader['logs']>, PromiseLike<unknown>> extends never ? Factory : Promise<Factory>;
+/**
+ * Public telemetry API exported by the package entrypoints.
+ */
+export interface Factory {
+    SpanNames: typeof SpanNames;
+    MetricNames: typeof MetricNames;
+    /**
+     * Creates a namespaced logger.
+     *
+      * @remarks
+     * - Debug output is always used.
+     * - When the OTel logs API is available, messages are mirrored to OpenTelemetry logs.
+     */
+    debug(namespace: string): Logger;
+    /**
+     * Starts spans from a `TraceDefinition`.
+     */
+    trace: TraceFunction;
+    /**
+     * Exposes histogram and counter creators from the package meter.
+     */
+    metric: Metric;
+}
+/**
+ * Options used by the shared `attempt()` helper.
+ *
+ * @remarks
+ * - Omitting catch preserves the original error.
+ * - catch is for side effects only; recovery values are not used.
+ * - Declare catch as returning never when it always rethrows.
+ * - Declare catch as returning void when it may swallow the failure.
+ */
+export interface AttemptOptions<TResult, TCatch = never> {
+    try(): TResult;
+    catch?(error: unknown): TCatch;
+    finally?(): void;
+}