@microsoft/agents-a365-observability 0.1.0-preview.103

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Microsoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @microsoft/agents-a365-observability
+
+[![npm](https://img.shields.io/npm/v/@microsoft/agents-a365-observability?label=npm&logo=npm)](https://www.npmjs.com/package/@microsoft/agents-a365-observability)
+[![npm Downloads](https://img.shields.io/npm/dm/@microsoft/agents-a365-observability?label=Downloads&logo=npm)](https://www.npmjs.com/package/@microsoft/agents-a365-observability)
+
+OpenTelemetry-based observability and tracing for Microsoft Agents A365 applications. This package provides comprehensive monitoring capabilities for agent invocations, tool executions, and AI model inference calls with seamless Azure Monitor integration.
+
+## Installation
+
+```bash
+npm install @microsoft/agents-a365-observability
+```
+
+## Usage
+
+For detailed usage examples and implementation guidance, see the [Microsoft Agent 365 Observability Documentation](https://learn.microsoft.com/microsoft-agent-365/developer/observability?tabs=nodejs).
+
+## Support
+
+For issues, questions, or feedback:
+
+- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-nodejs/issues) section
+- See the [main documentation](../../README.md) for more information
+
+## Trademarks
+
+*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.*
+
+## License
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+Licensed under the MIT License - see the [LICENSE](../../LICENSE.md) file for details

package/dist/cjs/ObservabilityBuilder.d.ts

@@ -0,0 +1,101 @@
+import type { TokenResolver } from './tracing/exporter/Agent365ExporterOptions';
+import { Agent365ExporterOptions } from './tracing/exporter/Agent365ExporterOptions';
+import { ClusterCategory } from '@microsoft/agents-a365-runtime';
+import { type ILogger } from './utils/logging';
+/**
+ * Configuration options for Agent 365 Observability Builder
+ */
+export interface BuilderOptions {
+    /** Custom service name for telemetry */
+    serviceName?: string;
+    /** Custom service version for telemetry */
+    serviceVersion?: string;
+    tokenResolver?: TokenResolver;
+    /** Environment / cluster category (e.g., "preprod", "prod"). */
+    clusterCategory?: ClusterCategory;
+    /**
+     * Optional partial set of exporter options allowing agent developers to customize.
+     * Any values omitted will fall back to the defaults defined in Agent365ExporterOptions.
+     * Values provided here will be overridden by explicitly configured tokenResolver or clusterCategory
+     * from dedicated builder methods.
+     */
+    exporterOptions?: Partial<Agent365ExporterOptions>;
+    /**
+     * Optional custom logger implementation for the observability SDK.
+     * If not provided, the SDK uses the default console logger.
+     * Implement ILogger to integrate with other logging services
+     */
+    customLogger?: ILogger;
+}
+/**
+ * Builder for configuring Agent 365 with OpenTelemetry tracing
+ */
+export declare class ObservabilityBuilder {
+    private options;
+    private isBuilt;
+    private sdk?;
+    /**
+     * Configures the service name and version for telemetry
+     * @param serviceName The service name
+     * @param serviceVersion The service version
+     * @returns The builder instance for method chaining
+     */
+    withService(serviceName: string, serviceVersion?: string): ObservabilityBuilder;
+    /**
+     * Configures the token resolver for Agent 365 exporter
+     * @param tokenResolver Function to resolve authentication tokens
+     * @returns The builder instance for method chaining
+     */
+    withTokenResolver(tokenResolver: TokenResolver): ObservabilityBuilder;
+    /**
+     * Configures the cluster category for Agent 365 exporter
+     * @param clusterCategory The cluster category (e.g., "preprod", "prod")
+     * @returns The builder instance for method chaining
+     */
+    withClusterCategory(clusterCategory: ClusterCategory): ObservabilityBuilder;
+    /**
+     * Provide a partial set of Agent365ExporterOptions. These will be merged with
+     * defaults and any explicitly configured clusterCategory/tokenResolver.
+     * @param exporterOptions Partial exporter options
+     * @returns The builder instance for chaining
+     */
+    withExporterOptions(exporterOptions: Partial<Agent365ExporterOptions>): ObservabilityBuilder;
+    /**
+     * Sets a custom logger implementation for the observability SDK
+     * @param customLogger The custom logger implementation (must implement ILogger interface)
+     * @returns The builder instance for method chaining
+     *
+     * Example with Winston:
+     * ```typescript
+     * const winstonLogger = winston.createLogger({...});
+     * builder.withCustomLogger({
+     *   info: (msg, ...args) => winstonLogger.info(msg, ...args),
+     *   warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
+     *   error: (msg, ...args) => winstonLogger.error(msg, ...args)
+     * });
+     * ```
+     */
+    withCustomLogger(customLogger: ILogger): ObservabilityBuilder;
+    private createBatchProcessor;
+    private createPerRequestProcessor;
+    private createExportProcessor;
+    private createResource;
+    /**
+     * Builds and initializes the Agent 365 configuration
+     * @returns The configured NodeSDK instance
+     */
+    build(): boolean;
+    /**
+     * Starts the OpenTelemetry SDK
+     */
+    start(): void;
+    /**
+     * Shuts down the OpenTelemetry SDK
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Helper to avoid double-registering same processor type.
+     */
+    private attachProcessorIfMissing;
+}
+//# sourceMappingURL=ObservabilityBuilder.d.ts.map

package/dist/cjs/ObservabilityBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObservabilityBuilder.d.ts","sourceRoot":"","sources":["../../src/ObservabilityBuilder.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4CAA4C,CAAC;AAChF,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AAKrF,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAe,EAAa,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAClE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,2CAA2C;IAC3C,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,gEAAgE;IAChE,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAEnD;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,GAAG,CAAC,CAAU;IAEtB;;;;;OAKG;IACI,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,oBAAoB;IAMtF;;;;OAIG;IACI,iBAAiB,CAAC,aAAa,EAAE,aAAa,GAAG,oBAAoB;IAK5E;;;;OAIG;IACI,mBAAmB,CAAC,eAAe,EAAE,eAAe,GAAG,oBAAoB;IAKlF;;;;;OAKG;IACI,mBAAmB,CAAC,eAAe,EAAE,OAAO,CAAC,uBAAuB,CAAC,GAAG,oBAAoB;IAQnG;;;;;;;;;;;;;;OAcG;IACI,gBAAgB,CAAC,YAAY,EAAE,OAAO,GAAG,oBAAoB;IAKpE,OAAO,CAAC,oBAAoB;IAsB5B,OAAO,CAAC,yBAAyB;IAiBjC,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,cAAc;IAUtB;;;OAGG;IACI,KAAK,IAAI,OAAO;IAoDvB;;OAEG;IACI,KAAK,IAAI,IAAI;IASpB;;OAEG;IACU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtC;;OAEG;IAEH,OAAO,CAAC,wBAAwB;CAUjC"}

package/dist/cjs/ObservabilityBuilder.js

@@ -0,0 +1,246 @@
+"use strict";
+// ------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// ------------------------------------------------------------------------------
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObservabilityBuilder = void 0;
+const sdk_node_1 = require("@opentelemetry/sdk-node");
+const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
+const SpanProcessor_1 = require("./tracing/processors/SpanProcessor");
+const utils_1 = require("./tracing/exporter/utils");
+const Agent365Exporter_1 = require("./tracing/exporter/Agent365Exporter");
+const Agent365ExporterOptions_1 = require("./tracing/exporter/Agent365ExporterOptions");
+const PerRequestSpanProcessor_1 = require("./tracing/PerRequestSpanProcessor");
+const resources_1 = require("@opentelemetry/resources");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const api_1 = require("@opentelemetry/api");
+const agents_a365_runtime_1 = require("@microsoft/agents-a365-runtime");
+const logging_1 = __importStar(require("./utils/logging"));
+/**
+ * Builder for configuring Agent 365 with OpenTelemetry tracing
+ */
+class ObservabilityBuilder {
+    constructor() {
+        this.options = {};
+        this.isBuilt = false;
+    }
+    /**
+     * Configures the service name and version for telemetry
+     * @param serviceName The service name
+     * @param serviceVersion The service version
+     * @returns The builder instance for method chaining
+     */
+    withService(serviceName, serviceVersion) {
+        this.options.serviceName = serviceName;
+        this.options.serviceVersion = serviceVersion;
+        return this;
+    }
+    /**
+     * Configures the token resolver for Agent 365 exporter
+     * @param tokenResolver Function to resolve authentication tokens
+     * @returns The builder instance for method chaining
+     */
+    withTokenResolver(tokenResolver) {
+        this.options.tokenResolver = tokenResolver;
+        return this;
+    }
+    /**
+     * Configures the cluster category for Agent 365 exporter
+     * @param clusterCategory The cluster category (e.g., "preprod", "prod")
+     * @returns The builder instance for method chaining
+     */
+    withClusterCategory(clusterCategory) {
+        this.options.clusterCategory = clusterCategory;
+        return this;
+    }
+    /**
+     * Provide a partial set of Agent365ExporterOptions. These will be merged with
+     * defaults and any explicitly configured clusterCategory/tokenResolver.
+     * @param exporterOptions Partial exporter options
+     * @returns The builder instance for chaining
+     */
+    withExporterOptions(exporterOptions) {
+        this.options.exporterOptions = {
+            ...(this.options.exporterOptions || {}),
+            ...exporterOptions
+        };
+        return this;
+    }
+    /**
+     * Sets a custom logger implementation for the observability SDK
+     * @param customLogger The custom logger implementation (must implement ILogger interface)
+     * @returns The builder instance for method chaining
+     *
+     * Example with Winston:
+     * ```typescript
+     * const winstonLogger = winston.createLogger({...});
+     * builder.withCustomLogger({
+     *   info: (msg, ...args) => winstonLogger.info(msg, ...args),
+     *   warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
+     *   error: (msg, ...args) => winstonLogger.error(msg, ...args)
+     * });
+     * ```
+     */
+    withCustomLogger(customLogger) {
+        this.options.customLogger = customLogger;
+        return this;
+    }
+    createBatchProcessor() {
+        if (!(0, utils_1.isAgent365ExporterEnabled)()) {
+            logging_1.default.info('[ObservabilityBuilder] Agent 365 exporter not enabled. Using ConsoleSpanExporter for BatchSpanProcessor.');
+            return new sdk_trace_base_1.BatchSpanProcessor(new sdk_trace_base_1.ConsoleSpanExporter());
+        }
+        const opts = new Agent365ExporterOptions_1.Agent365ExporterOptions();
+        if (this.options.exporterOptions) {
+            Object.assign(opts, this.options.exporterOptions);
+        }
+        opts.clusterCategory = this.options.clusterCategory || opts.clusterCategory || agents_a365_runtime_1.ClusterCategory.prod;
+        if (this.options.tokenResolver) {
+            opts.tokenResolver = this.options.tokenResolver;
+        }
+        return new sdk_trace_base_1.BatchSpanProcessor(new Agent365Exporter_1.Agent365Exporter(opts), {
+            maxQueueSize: opts.maxQueueSize,
+            scheduledDelayMillis: opts.scheduledDelayMilliseconds,
+            exportTimeoutMillis: opts.exporterTimeoutMilliseconds,
+            maxExportBatchSize: opts.maxExportBatchSize
+        });
+    }
+    createPerRequestProcessor() {
+        if (!(0, utils_1.isAgent365ExporterEnabled)()) {
+            logging_1.default.info('[Agent365Exporter] Per-request export enabled but Agent 365 exporter is disabled. Using ConsoleSpanExporter.');
+            return new PerRequestSpanProcessor_1.PerRequestSpanProcessor(new sdk_trace_base_1.ConsoleSpanExporter());
+        }
+        const opts = new Agent365ExporterOptions_1.Agent365ExporterOptions();
+        if (this.options.exporterOptions) {
+            Object.assign(opts, this.options.exporterOptions);
+        }
+        opts.clusterCategory = this.options.clusterCategory || opts.clusterCategory || agents_a365_runtime_1.ClusterCategory.prod;
+        // For per-request export, token is retrieved from OTel Context by Agent365Exporter
+        // using getExportToken(), so no tokenResolver is needed here
+        return new PerRequestSpanProcessor_1.PerRequestSpanProcessor(new Agent365Exporter_1.Agent365Exporter(opts));
+    }
+    createExportProcessor() {
+        if ((0, utils_1.isPerRequestExportEnabled)()) {
+            return this.createPerRequestProcessor();
+        }
+        return this.createBatchProcessor();
+    }
+    createResource() {
+        const serviceName = this.options.serviceVersion
+            ? `${this.options.serviceName}-${this.options.serviceVersion}`
+            : this.options.serviceName ?? 'Agent365-TypeScript';
+        return (0, resources_1.resourceFromAttributes)({
+            [semantic_conventions_1.ATTR_SERVICE_NAME]: serviceName,
+        });
+    }
+    /**
+     * Builds and initializes the Agent 365 configuration
+     * @returns The configured NodeSDK instance
+     */
+    build() {
+        if (this.isBuilt) {
+            return this.isBuilt;
+        }
+        // Apply custom logger if provided
+        if (this.options.customLogger) {
+            (0, logging_1.setLogger)(this.options.customLogger);
+        }
+        // Create processors in the desired order:
+        // 1. baggage enricher (copies baggage -> span attributes)
+        const spanProcessor = new SpanProcessor_1.SpanProcessor();
+        // 2. export processor (batch or per-request based on environment variable)
+        const exportProcessor = this.createExportProcessor();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const globalProvider = api_1.trace.getTracerProvider();
+        const canAddProcessors = typeof globalProvider?.addSpanProcessor === 'function' &&
+            typeof globalProvider?.resource !== 'undefined';
+        if (canAddProcessors) {
+            // Someone else already created a provider (maybe their own NodeSDK).
+            // We DO NOT create a new NodeSDK.
+            // We just add our baggage enricher + export processor to their provider,
+            // but only if they aren't already there.
+            this.attachProcessorIfMissing(globalProvider, spanProcessor);
+            this.attachProcessorIfMissing(globalProvider, exportProcessor);
+            this.isBuilt = true;
+            this.sdk = undefined; // we didn't create/own one
+            return this.isBuilt;
+        }
+        // Create & configure the NodeSDK manually so we can inject processors + resource.
+        this.sdk = new sdk_node_1.NodeSDK({
+            resource: this.createResource(),
+            spanProcessors: [
+                spanProcessor,
+                exportProcessor,
+            ],
+        });
+        this.isBuilt = true;
+        return this.isBuilt;
+    }
+    /**
+     * Starts the OpenTelemetry SDK
+     */
+    start() {
+        if (!this.isBuilt) {
+            this.build();
+        }
+        if (this.sdk) {
+            this.sdk.start();
+        }
+    }
+    /**
+     * Shuts down the OpenTelemetry SDK
+     */
+    async shutdown() {
+        if (this.sdk) {
+            await this.sdk.shutdown();
+        }
+    }
+    /**
+     * Helper to avoid double-registering same processor type.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    attachProcessorIfMissing(provider, processor) {
+        const active = provider._activeSpanProcessor?._spanProcessors;
+        const alreadyAdded = Array.isArray(active) &&
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            active.some((p) => p?.constructor?.name === processor.constructor.name);
+        if (!alreadyAdded) {
+            provider.addSpanProcessor(processor);
+        }
+    }
+}
+exports.ObservabilityBuilder = ObservabilityBuilder;
+//# sourceMappingURL=ObservabilityBuilder.js.map

package/dist/cjs/ObservabilityBuilder.js.map

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

package/dist/cjs/ObservabilityManager.d.ts

@@ -0,0 +1,29 @@
+import { ObservabilityBuilder, BuilderOptions } from './ObservabilityBuilder';
+/**
+ * Main entry point for Agent 365 providing OpenTelemetry tracing for AI agents and tools
+ */
+export declare class ObservabilityManager {
+    private static instance?;
+    /**
+     * Configures Agent 365 with OpenTelemetry tracing for AI agents and tools
+     * @param configure Optional configuration callback for the Builder
+     * @returns The configured Builder instance
+     */
+    static configure(configure?: (builder: ObservabilityBuilder) => void): ObservabilityBuilder;
+    /**
+     * Configures and starts Agent 365 with simplified options
+     * @param options Configuration options
+     * @returns The configured and started Builder instance
+     */
+    static start(options?: BuilderOptions): ObservabilityBuilder;
+    /**
+     * Gets the current Agent 365 instance
+     * @returns The current instance or null if not configured
+     */
+    static getInstance(): ObservabilityBuilder | null;
+    /**
+     * Shuts down Agent 365
+     */
+    static shutdown(): Promise<void>;
+}
+//# sourceMappingURL=ObservabilityManager.d.ts.map

package/dist/cjs/ObservabilityManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObservabilityManager.d.ts","sourceRoot":"","sources":["../../src/ObservabilityManager.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE9E;;GAEG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAuB;IAG/C;;;;OAIG;WACW,SAAS,CACrB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,GAClD,oBAAoB;IASvB;;;;OAIG;WACW,KAAK,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,oBAAoB;IAqBnE;;;OAGG;WACW,WAAW,IAAI,oBAAoB,GAAG,IAAI;IAIxD;;OAEG;WACiB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAM9C"}

package/dist/cjs/ObservabilityManager.js

@@ -0,0 +1,61 @@
+"use strict";
+// ------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// ------------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObservabilityManager = void 0;
+const ObservabilityBuilder_1 = require("./ObservabilityBuilder");
+/**
+ * Main entry point for Agent 365 providing OpenTelemetry tracing for AI agents and tools
+ */
+class ObservabilityManager {
+    /**
+     * Configures Agent 365 with OpenTelemetry tracing for AI agents and tools
+     * @param configure Optional configuration callback for the Builder
+     * @returns The configured Builder instance
+     */
+    static configure(configure) {
+        const builder = new ObservabilityBuilder_1.ObservabilityBuilder();
+        configure?.(builder);
+        ObservabilityManager.instance = builder;
+        return builder;
+    }
+    /**
+     * Configures and starts Agent 365 with simplified options
+     * @param options Configuration options
+     * @returns The configured and started Builder instance
+     */
+    static start(options) {
+        const builder = new ObservabilityBuilder_1.ObservabilityBuilder();
+        if (options?.serviceName) {
+            builder.withService(options.serviceName, options.serviceVersion);
+        }
+        if (options?.tokenResolver) {
+            builder.withTokenResolver(options.tokenResolver);
+        }
+        if (options?.clusterCategory) {
+            builder.withClusterCategory(options.clusterCategory);
+        }
+        builder.start();
+        ObservabilityManager.instance = builder;
+        return builder;
+    }
+    /**
+     * Gets the current Agent 365 instance
+     * @returns The current instance or null if not configured
+     */
+    static getInstance() {
+        return ObservabilityManager.instance || null;
+    }
+    /**
+     * Shuts down Agent 365
+     */
+    static async shutdown() {
+        if (ObservabilityManager.instance) {
+            await ObservabilityManager.instance.shutdown();
+            ObservabilityManager.instance = undefined;
+        }
+    }
+}
+exports.ObservabilityManager = ObservabilityManager;
+//# sourceMappingURL=ObservabilityManager.js.map

package/dist/cjs/ObservabilityManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObservabilityManager.js","sourceRoot":"","sources":["../../src/ObservabilityManager.ts"],"names":[],"mappings":";AAAA,iFAAiF;AACjF,4DAA4D;AAC5D,iFAAiF;;;AAEjF,iEAA8E;AAE9E;;GAEG;AACH,MAAa,oBAAoB;IAI/B;;;;OAIG;IACI,MAAM,CAAC,SAAS,CACrB,SAAmD;QAEnD,MAAM,OAAO,GAAG,IAAI,2CAAoB,EAAE,CAAC;QAE3C,SAAS,EAAE,CAAC,OAAO,CAAC,CAAC;QAErB,oBAAoB,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,KAAK,CAAC,OAAwB;QAC1C,MAAM,OAAO,GAAG,IAAI,2CAAoB,EAAE,CAAC;QAE3C,IAAI,OAAO,EAAE,WAAW,EAAE,CAAC;YACzB,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;QACnE,CAAC;QAED,IAAI,OAAO,EAAE,aAAa,EAAE,CAAC;YAC3B,OAAO,CAAC,iBAAiB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QACnD,CAAC;QAED,IAAI,OAAO,EAAE,eAAe,EAAE,CAAC;YAC7B,OAAO,CAAC,mBAAmB,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QACvD,CAAC;QAED,OAAO,CAAC,KAAK,EAAE,CAAC;QAEhB,oBAAoB,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;OAGG;IACI,MAAM,CAAC,WAAW;QACvB,OAAO,oBAAoB,CAAC,QAAQ,IAAI,IAAI,CAAC;IAC/C,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,KAAK,CAAC,QAAQ;QAC1B,IAAI,oBAAoB,CAAC,QAAQ,EAAE,CAAC;YAClC,MAAM,oBAAoB,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;YAC/C,oBAAoB,CAAC,QAAQ,GAAG,SAAS,CAAC;QAC5C,CAAC;IACH,CAAC;CACF;AA/DD,oDA+DC"}

package/dist/cjs/configuration/ObservabilityConfiguration.d.ts

@@ -0,0 +1,20 @@
+import { RuntimeConfiguration } from '@microsoft/agents-a365-runtime';
+import { ObservabilityConfigurationOptions } from './ObservabilityConfigurationOptions';
+/**
+ * Configuration for observability package.
+ * Inherits runtime settings and adds observability-specific settings.
+ */
+export declare class ObservabilityConfiguration extends RuntimeConfiguration {
+    protected get observabilityOverrides(): ObservabilityConfigurationOptions;
+    constructor(overrides?: ObservabilityConfigurationOptions);
+    /**
+     * Gets the observability authentication scopes.
+     * Used by AgenticTokenCache for observability service authentication.
+     */
+    get observabilityAuthenticationScopes(): readonly string[];
+    get isObservabilityExporterEnabled(): boolean;
+    get useCustomDomainForObservability(): boolean;
+    get observabilityDomainOverride(): string | null;
+    get observabilityLogLevel(): string;
+}
+//# sourceMappingURL=ObservabilityConfiguration.d.ts.map

package/dist/cjs/configuration/ObservabilityConfiguration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObservabilityConfiguration.d.ts","sourceRoot":"","sources":["../../../src/configuration/ObservabilityConfiguration.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,iCAAiC,EAAE,MAAM,qCAAqC,CAAC;AAKxF;;;GAGG;AACH,qBAAa,0BAA2B,SAAQ,oBAAoB;IAClE,SAAS,KAAK,sBAAsB,IAAI,iCAAiC,CAExE;gBAEW,SAAS,CAAC,EAAE,iCAAiC;IAMzD;;;OAGG;IACH,IAAI,iCAAiC,IAAI,SAAS,MAAM,EAAE,CAUzD;IAED,IAAI,8BAA8B,IAAI,OAAO,CAI5C;IAED,IAAI,+BAA+B,IAAI,OAAO,CAI7C;IAED,IAAI,2BAA2B,IAAI,MAAM,GAAG,IAAI,CAU/C;IAED,IAAI,qBAAqB,IAAI,MAAM,CAIlC;CACF"}

package/dist/cjs/configuration/ObservabilityConfiguration.js

@@ -0,0 +1,66 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObservabilityConfiguration = void 0;
+const agents_a365_runtime_1 = require("@microsoft/agents-a365-runtime");
+// Default constants
+const PROD_OBSERVABILITY_SCOPE = 'https://api.powerplatform.com/.default';
+/**
+ * Configuration for observability package.
+ * Inherits runtime settings and adds observability-specific settings.
+ */
+class ObservabilityConfiguration extends agents_a365_runtime_1.RuntimeConfiguration {
+    get observabilityOverrides() {
+        return this.overrides;
+    }
+    constructor(overrides) {
+        super(overrides);
+    }
+    // Inherited: clusterCategory, isDevelopmentEnvironment, isNodeEnvDevelopment
+    /**
+     * Gets the observability authentication scopes.
+     * Used by AgenticTokenCache for observability service authentication.
+     */
+    get observabilityAuthenticationScopes() {
+        const result = this.observabilityOverrides.observabilityAuthenticationScopes?.();
+        if (result !== undefined) {
+            return result;
+        }
+        const override = process.env.A365_OBSERVABILITY_SCOPES_OVERRIDE;
+        if (override?.trim()) {
+            return override.trim().split(/\s+/);
+        }
+        return [PROD_OBSERVABILITY_SCOPE];
+    }
+    get isObservabilityExporterEnabled() {
+        const result = this.observabilityOverrides.isObservabilityExporterEnabled?.();
+        if (result !== undefined)
+            return result;
+        return agents_a365_runtime_1.RuntimeConfiguration.parseEnvBoolean(process.env.ENABLE_A365_OBSERVABILITY_EXPORTER);
+    }
+    get useCustomDomainForObservability() {
+        const result = this.observabilityOverrides.useCustomDomainForObservability?.();
+        if (result !== undefined)
+            return result;
+        return agents_a365_runtime_1.RuntimeConfiguration.parseEnvBoolean(process.env.A365_OBSERVABILITY_USE_CUSTOM_DOMAIN);
+    }
+    get observabilityDomainOverride() {
+        const result = this.observabilityOverrides.observabilityDomainOverride?.();
+        if (result !== undefined) {
+            return result;
+        }
+        const override = process.env.A365_OBSERVABILITY_DOMAIN_OVERRIDE;
+        if (override?.trim()) {
+            return override.trim().replace(/\/+$/, '');
+        }
+        return null;
+    }
+    get observabilityLogLevel() {
+        return this.observabilityOverrides.observabilityLogLevel?.()
+            ?? process.env.A365_OBSERVABILITY_LOG_LEVEL
+            ?? 'none';
+    }
+}
+exports.ObservabilityConfiguration = ObservabilityConfiguration;
+//# sourceMappingURL=ObservabilityConfiguration.js.map

package/dist/cjs/configuration/ObservabilityConfiguration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObservabilityConfiguration.js","sourceRoot":"","sources":["../../../src/configuration/ObservabilityConfiguration.ts"],"names":[],"mappings":";AAAA,uCAAuC;AACvC,kCAAkC;;;AAElC,wEAAsE;AAGtE,oBAAoB;AACpB,MAAM,wBAAwB,GAAG,wCAAwC,CAAC;AAE1E;;;GAGG;AACH,MAAa,0BAA2B,SAAQ,0CAAoB;IAClE,IAAc,sBAAsB;QAClC,OAAO,IAAI,CAAC,SAA8C,CAAC;IAC7D,CAAC;IAED,YAAY,SAA6C;QACvD,KAAK,CAAC,SAAS,CAAC,CAAC;IACnB,CAAC;IAED,6EAA6E;IAE7E;;;OAGG;IACH,IAAI,iCAAiC;QACnC,MAAM,MAAM,GAAG,IAAI,CAAC,sBAAsB,CAAC,iCAAiC,EAAE,EAAE,CAAC;QACjF,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC;QAChE,IAAI,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC;YACrB,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACpC,CAAC;IAED,IAAI,8BAA8B;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,sBAAsB,CAAC,8BAA8B,EAAE,EAAE,CAAC;QAC9E,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;QACxC,OAAO,0CAAoB,CAAC,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;IAC9F,CAAC;IAED,IAAI,+BAA+B;QACjC,MAAM,MAAM,GAAG,IAAI,CAAC,sBAAsB,CAAC,+BAA+B,EAAE,EAAE,CAAC;QAC/E,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;QACxC,OAAO,0CAAoB,CAAC,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;IAChG,CAAC;IAED,IAAI,2BAA2B;QAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,sBAAsB,CAAC,2BAA2B,EAAE,EAAE,CAAC;QAC3E,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC;QAChE,IAAI,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC;YACrB,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,qBAAqB;QACvB,OAAO,IAAI,CAAC,sBAAsB,CAAC,qBAAqB,EAAE,EAAE;eACvD,OAAO,CAAC,GAAG,CAAC,4BAA4B;eACxC,MAAM,CAAC;IACd,CAAC;CACF;AAxDD,gEAwDC"}