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

package/dist/esm/utils/logging.d.ts

@@ -0,0 +1,111 @@
+import { IConfigurationProvider } from '@microsoft/agents-a365-runtime';
+import { ObservabilityConfiguration } from '../configuration';
+/**
+ * Custom logger interface for Agent 365 observability
+ * Implement this interface to support logging backends
+ */
+export interface ILogger {
+    /**
+     * Log an informational message
+     * @param message The log message
+     * @param args Optional arguments to include in the log
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * Log a warning message
+     * @param message The log message
+     * @param args Optional arguments to include in the log
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * Log an error message
+     * @param message The log message
+     * @param args Optional arguments to include in the log
+     */
+    error(message: string, ...args: unknown[]): void;
+    /**
+     * Log an event with standardized parameters
+     * @param eventType Standardized event name/category (e.g., ExporterEventNames.EXPORT)
+     * @param isSuccess Whether the operation/event succeeded
+     * @param durationMs Duration of the operation/event in milliseconds
+     * @param message Optional message or additional details about the event, especially useful for errors or failures
+     * @param correlationId Optional correlation identifier to connect events/logs across components
+  
+     */
+    event(eventType: string, isSuccess: boolean, durationMs: number, message?: string, correlationId?: string): void;
+}
+/**
+ * Format error object for logging with message and stack trace
+ */
+export declare function formatError(error: unknown): string;
+/**
+ * Default console-based logger implementation with configuration provider support.
+ *
+ * Environment Variable:
+ *   A365_OBSERVABILITY_LOG_LEVEL=none|info|warn|error (default: none)
+ *
+ *   Single values:
+ *   none = no logging (default)
+ *   info = info messages only
+ *   warn = warn messages only
+ *   error = error messages only
+ *
+ *   Multiple values (pipe-separated):
+ *   info|warn = info and warn messages
+ *   warn|error = warn and error messages
+ *   info|warn|error = all message types
+ */
+export declare class DefaultLogger implements ILogger {
+    private readonly configProvider;
+    constructor(configProvider?: IConfigurationProvider<ObservabilityConfiguration>);
+    private getEnabledLogLevels;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    event(eventType: string, isSuccess: boolean, durationMs: number, message?: string, correlationId?: string): void;
+}
+/**
+ * Set a custom logger implementation for the observability SDK
+ *
+ * Example with Winston:
+ * ```typescript
+ * import * as winston from 'winston';
+ * import { setLogger } from '@microsoft/agents-a365-observability';
+ *
+ * const winstonLogger = winston.createLogger({
+ *   level: 'info',
+ *   format: winston.format.json(),
+ *   transports: [
+ *     new winston.transports.File({ filename: 'error.log', level: 'error' }),
+ *     new winston.transports.File({ filename: 'combined.log' })
+ *   ]
+ * });
+ *
+ * setLogger({
+ *   info: (msg, ...args) => winstonLogger.info(msg, ...args),
+ *   warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
+ *   error: (msg, ...args) => winstonLogger.error(msg, ...args),
+ *   event: (eventType, isSuccess, durationMs, message, correlationId) => {
+ *     winstonLogger.log({ level: isSuccess ? 'info' : 'error', eventType, isSuccess, durationMs, message, correlationId });
+ *   }
+ * });
+ * ```
+ *
+ * @param customLogger The custom logger implementation
+ */
+export declare function setLogger(customLogger: ILogger): void;
+/**
+ * Get the current logger instance
+ */
+export declare function getLogger(): ILogger;
+/**
+ * Reset to the default console logger (mainly for testing)
+ */
+export declare function resetLogger(): void;
+/**
+ * Default logger instance for backward compatibility.
+ * Delegates to the global logger which can be replaced via setLogger().
+ */
+export declare const logger: ILogger;
+export default logger;
+//# sourceMappingURL=logging.d.ts.map

package/dist/esm/utils/logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../../src/utils/logging.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAEL,0BAA0B,EAC3B,MAAM,kBAAkB,CAAC;AAE1B;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAEhD;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAEhD;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAEjD;;;;;;;;OAQG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClH;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKlD;AAkCD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,YAAW,OAAO;IAEzC,OAAO,CAAC,QAAQ,CAAC,cAAc;gBAAd,cAAc,GAAE,sBAAsB,CAAC,0BAA0B,CAA6C;IAGjI,OAAO,CAAC,mBAAmB;IAI3B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAM/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAM/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAMhD,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;CAUjH;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,SAAS,CAAC,YAAY,EAAE,OAAO,GAAG,IAAI,CAWrD;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAElC;AAED;;;GAGG;AACH,eAAO,MAAM,MAAM,EAAE,OAMpB,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/esm/utils/logging.js

@@ -0,0 +1,155 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { defaultObservabilityConfigurationProvider } from '../configuration';
+/**
+ * Format error object for logging with message and stack trace
+ */
+export function formatError(error) {
+    if (error instanceof Error) {
+        return `${error.message}\nStack: ${error.stack || 'No stack trace'}`;
+    }
+    return String(error);
+}
+const LOG_LEVELS = {
+    none: 0,
+    info: 1,
+    warn: 2,
+    error: 3
+};
+/**
+ * Parse log level string into a set of enabled log levels.
+ * Supports pipe-separated values like "info|warn|error".
+ */
+function parseLogLevel(level) {
+    const levels = new Set();
+    const levelStrings = level.toLowerCase().trim().split('|');
+    for (const levelString of levelStrings) {
+        const normalizedLevel = levelString.trim();
+        const levelValue = LOG_LEVELS[normalizedLevel];
+        if (levelValue !== undefined) {
+            levels.add(levelValue);
+        }
+    }
+    // If no valid levels found, default to none
+    if (levels.size === 0) {
+        levels.add(LOG_LEVELS.none);
+    }
+    return levels;
+}
+/**
+ * Default console-based logger implementation with configuration provider support.
+ *
+ * Environment Variable:
+ *   A365_OBSERVABILITY_LOG_LEVEL=none|info|warn|error (default: none)
+ *
+ *   Single values:
+ *   none = no logging (default)
+ *   info = info messages only
+ *   warn = warn messages only
+ *   error = error messages only
+ *
+ *   Multiple values (pipe-separated):
+ *   info|warn = info and warn messages
+ *   warn|error = warn and error messages
+ *   info|warn|error = all message types
+ */
+export class DefaultLogger {
+    constructor(configProvider = defaultObservabilityConfigurationProvider) {
+        this.configProvider = configProvider;
+    }
+    getEnabledLogLevels() {
+        return parseLogLevel(this.configProvider.getConfiguration().observabilityLogLevel);
+    }
+    info(message, ...args) {
+        if (this.getEnabledLogLevels().has(LOG_LEVELS.info)) {
+            console.log('[INFO]', message, ...args);
+        }
+    }
+    warn(message, ...args) {
+        if (this.getEnabledLogLevels().has(LOG_LEVELS.warn)) {
+            console.warn('[WARN]', message, ...args);
+        }
+    }
+    error(message, ...args) {
+        if (this.getEnabledLogLevels().has(LOG_LEVELS.error)) {
+            console.error('[ERROR]', message, ...args);
+        }
+    }
+    event(eventType, isSuccess, durationMs, message, correlationId) {
+        const status = isSuccess ? 'succeeded' : 'failed';
+        const logLevelNeeded = isSuccess ? 1 : 3;
+        if (this.getEnabledLogLevels().has(logLevelNeeded)) {
+            const logFn = isSuccess ? console.log : console.error;
+            const messageInfo = message ? ` - ${message}` : '';
+            const correlationInfo = correlationId ? ` [${correlationId}]` : '';
+            logFn(`[EVENT]: ${eventType} ${status} in ${durationMs}ms${messageInfo}${correlationInfo}`);
+        }
+    }
+}
+/**
+ * Global logger instance - can be replaced with a custom logger via setLogger()
+ */
+let globalLogger = new DefaultLogger();
+/**
+ * Set a custom logger implementation for the observability SDK
+ *
+ * Example with Winston:
+ * ```typescript
+ * import * as winston from 'winston';
+ * import { setLogger } from '@microsoft/agents-a365-observability';
+ *
+ * const winstonLogger = winston.createLogger({
+ *   level: 'info',
+ *   format: winston.format.json(),
+ *   transports: [
+ *     new winston.transports.File({ filename: 'error.log', level: 'error' }),
+ *     new winston.transports.File({ filename: 'combined.log' })
+ *   ]
+ * });
+ *
+ * setLogger({
+ *   info: (msg, ...args) => winstonLogger.info(msg, ...args),
+ *   warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
+ *   error: (msg, ...args) => winstonLogger.error(msg, ...args),
+ *   event: (eventType, isSuccess, durationMs, message, correlationId) => {
+ *     winstonLogger.log({ level: isSuccess ? 'info' : 'error', eventType, isSuccess, durationMs, message, correlationId });
+ *   }
+ * });
+ * ```
+ *
+ * @param customLogger The custom logger implementation
+ */
+export function setLogger(customLogger) {
+    if (!customLogger ||
+        typeof customLogger.info !== 'function' ||
+        typeof customLogger.warn !== 'function' ||
+        typeof customLogger.error !== 'function' ||
+        typeof customLogger.event !== 'function') {
+        throw new Error('Custom logger must implement ILogger interface with all methods: info, warn, error, and event');
+    }
+    globalLogger = customLogger;
+}
+/**
+ * Get the current logger instance
+ */
+export function getLogger() {
+    return globalLogger;
+}
+/**
+ * Reset to the default console logger (mainly for testing)
+ */
+export function resetLogger() {
+    globalLogger = new DefaultLogger();
+}
+/**
+ * Default logger instance for backward compatibility.
+ * Delegates to the global logger which can be replaced via setLogger().
+ */
+export const logger = {
+    info: (message, ...args) => globalLogger.info(message, ...args),
+    warn: (message, ...args) => globalLogger.warn(message, ...args),
+    error: (message, ...args) => globalLogger.error(message, ...args),
+    event: (eventType, isSuccess, durationMs, message, correlationId) => globalLogger.event(eventType, isSuccess, durationMs, message, correlationId)
+};
+export default logger;
+//# sourceMappingURL=logging.js.map

package/dist/esm/utils/logging.js.map

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

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@microsoft/agents-a365-observability",
+  "version": "0.1.0-preview.103",
+  "description": "OpenTelemetry tracing and monitoring SDK for AI agents built with TypeScript/Node.js",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "keywords": [
+    "Agent365",
+    "opentelemetry",
+    "tracing",
+    "monitoring",
+    "ai",
+    "agents",
+    "azure",
+    "typescript"
+  ],
+  "author": "Microsoft Corporation",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/Agent365-nodejs.git",
+    "directory": "packages/agents-a365-observability"
+  },
+  "dependencies": {
+    "@azure/monitor-opentelemetry-exporter": "^1.0.0-beta.32",
+    "@microsoft/agents-a365-runtime": "0.1.0-preview.103",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.205.0",
+    "@opentelemetry/instrumentation": "^0.204.0",
+    "@opentelemetry/resources": "^2.1.0",
+    "@opentelemetry/sdk-node": "^0.204.0",
+    "@opentelemetry/sdk-trace-base": "^2.1.0",
+    "@opentelemetry/semantic-conventions": "^1.37.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.17.0",
+    "@typescript-eslint/eslint-plugin": "^8.47.0",
+    "@typescript-eslint/parser": "^8.47.0",
+    "eslint": "^9.39.1",
+    "jest": "^30.2.0",
+    "rimraf": "^6.0.0",
+    "ts-jest": "^29.4.5",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.47.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "build:cjs": "npx tsc --project tsconfig.cjs.json",
+    "build:esm": "npx tsc --project tsconfig.esm.json",
+    "build": "npm run build:cjs && npm run build:esm",
+    "build:watch": "npx tsc --watch",
+    "clean": "npx rimraf dist",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "ci": "npm ci",
+    "pack": "node ../../copyFiles.js . && pnpm pack --pack-destination=../"
+  }
+}