OTel Web SDK Phase 1

shared/otel-core/Tests/Unit/src/index.tests.ts

@@ -7,6 +7,7 @@ import { OTelMultiLogRecordProcessorTests } from "./sdk/OTelMultiLogRecordProces
 import { CommonUtilsTests } from "./sdk/commonUtils.Tests";
 import { OpenTelemetryErrorsTests } from "./ai/errors.Tests";
 import { OTelTraceApiTests } from "./trace/traceState.Tests";
+import { OTelWebSdkTests } from "./sdk/OTelWebSdk.Tests";
 
 // AppInsightsCommon tests
 import { ApplicationInsightsTests } from "./ai/AppInsightsCommon.tests";
@@ -47,6 +48,7 @@ export function runTests() {
     new CommonUtilsTests().registerTests();
     new OpenTelemetryErrorsTests().registerTests();
     new OTelTraceApiTests().registerTests();
+    new OTelWebSdkTests().registerTests();
 
     new GlobalTestHooks().registerTests();
     new DynamicTests().registerTests();

shared/otel-core/src/index.ts

@@ -171,7 +171,6 @@ export { IOTelAttributes, OTelAttributeValue, ExtendedOTelAttributeValue } from
 export { OTelException, IOTelExceptionWithCode, IOTelExceptionWithMessage, IOTelExceptionWithName } from "./interfaces/IException";
 export { IOTelHrTime, OTelTimeInput } from "./interfaces/IOTelHrTime";
 export { createOTelApi } from "./otel/api/OTelApi";
-export { OTelSdk } from "./otel/sdk/OTelSdk";
 
 // OpenTelemetry Trace Interfaces
 export { ITraceApi } from "./interfaces/otel/trace/IOTelTraceApi";
@@ -194,8 +193,8 @@ export { IOTelErrorHandlers } from "./interfaces/otel/config/IOTelErrorHandlers"
 export { ITraceCfg } from "./interfaces/otel/config/IOTelTraceCfg";
 
 // OpenTelemetry SDK Interfaces
-export { IOTelSdk } from "./interfaces/otel/IOTelSdk";
-export { IOTelSdkCtx } from "./interfaces/otel/IOTelSdkCtx";
+export { IOTelWebSdk } from "./interfaces/otel/IOTelWebSdk";
+export { IOTelWebSdkConfig } from "./interfaces/otel/config/IOTelWebSdkConfig";
 
 // OpenTelemetry Context
 export { createContextManager } from "./otel/api/context/contextManager";
@@ -262,6 +261,9 @@ export { createLogger } from "./otel/sdk/OTelLogger";
 export { createMultiLogRecordProcessor } from "./otel/sdk/OTelMultiLogRecordProcessor";
 export { loadDefaultConfig, reconfigureLimits } from "./otel/sdk/config";
 
+// SDK Entry Point
+export { createOTelWebSdk } from "./otel/sdk/OTelWebSdk";
+
 // ========================================
 // Application Insights Common Exports
 // ========================================

shared/otel-core/src/interfaces/otel/IOTelWebSdk.ts

@@ -0,0 +1,127 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { IPromise } from "@nevware21/ts-async";
+import { IOTelWebSdkConfig } from "./config/IOTelWebSdkConfig";
+import { IOTelLogger } from "./logs/IOTelLogger";
+import { IOTelLoggerOptions } from "./logs/IOTelLoggerOptions";
+import { IOTelTracer } from "./trace/IOTelTracer";
+import { IOTelTracerOptions } from "./trace/IOTelTracerOptions";
+
+/**
+ * Main interface for the OpenTelemetry Web SDK.
+ * Provides access to tracer and logger providers, configuration management,
+ * and complete lifecycle control including unload/cleanup.
+ *
+ * @remarks
+ * - Supports multiple isolated instances without global state
+ * - All dependencies injected through {@link IOTelWebSdkConfig}
+ * - Complete unload support — every instance must fully clean up on unload
+ *
+ * @example
+ * ```typescript
+ * const sdk = createOTelWebSdk({
+ *   resource: myResource,
+ *   errorHandlers: myHandlers,
+ *   contextManager: myContextManager,
+ *   idGenerator: myIdGenerator,
+ *   sampler: myAlwaysOnSampler,
+ *   performanceNow: () => performance.now()
+ * });
+ *
+ * // Get a tracer and create spans
+ * const tracer = sdk.getTracer("my-service");
+ * const span = tracer.startSpan("operation");
+ * span.end();
+ *
+ * // Get a logger and emit log records
+ * const logger = sdk.getLogger("my-service");
+ * logger.emit({ body: "Hello, World!" });
+ *
+ * // Cleanup when done
+ * sdk.shutdown();
+ * ```
+ *
+ * @since 4.0.0
+ */
+export interface IOTelWebSdk {
+    /**
+     * Returns a Tracer for creating spans.
+     * Tracers are cached by name + version combination — requesting the same
+     * name and version returns the same Tracer instance.
+     *
+     * @param name - The name of the tracer or instrumentation library
+     * @param version - The version of the tracer or instrumentation library
+     * @param options - Additional tracer options (e.g., schemaUrl)
+     * @returns A Tracer with the given name and version
+     *
+     * @example
+     * ```typescript
+     * const tracer = sdk.getTracer("my-component", "1.0.0");
+     * const span = tracer.startSpan("my-operation");
+     * ```
+     */
+    getTracer(name: string, version?: string, options?: IOTelTracerOptions): IOTelTracer;
+
+    /**
+     * Returns a Logger for emitting log records.
+     * Loggers are cached by name + version + schemaUrl combination —
+     * requesting the same combination returns the same Logger instance.
+     *
+     * @param name - The name of the logger or instrumentation library
+     * @param version - The version of the logger or instrumentation library
+     * @param options - Additional logger options (e.g., schemaUrl, scopeAttributes)
+     * @returns A Logger with the given name and version
+     *
+     * @example
+     * ```typescript
+     * const logger = sdk.getLogger("my-component", "1.0.0");
+     * logger.emit({ body: "Operation completed", severityText: "INFO" });
+     * ```
+     */
+    getLogger(name: string, version?: string, options?: IOTelLoggerOptions): IOTelLogger;
+
+    // TODO: Phase 5 - Uncomment when metrics are implemented
+    // /**
+    //  * Returns a Meter for recording metrics.
+    //  * @param name - The name of the meter or instrumentation library
+    //  * @param version - The version of the meter or instrumentation library
+    //  * @param options - Additional meter options
+    //  * @returns A Meter with the given name and version
+    //  */
+    // getMeter(name: string, version?: string, options?: IOTelMeterOptions): IOTelMeter;
+
+    /**
+     * Forces all providers to flush any buffered data.
+     * This is useful before application shutdown to ensure all telemetry
+     * is exported.
+     *
+     * @returns A promise that resolves when the flush is complete
+     */
+    forceFlush(): IPromise<void>;
+
+    /**
+     * Shuts down the SDK and releases all resources.
+     * After shutdown, the SDK instance is no longer usable — all
+     * subsequent calls to `getTracer` or `getLogger` will return
+     * no-op implementations.
+     *
+     * @remarks
+     * Shutdown performs the following:
+     * - Flushes all pending telemetry
+     * - Shuts down all providers (trace, log)
+     * - Removes all config change listeners (calls `IUnloadHook.rm()`)
+     * - Clears all cached instances
+     *
+     * @returns A promise that resolves when shutdown is complete
+     */
+    shutdown(): IPromise<void>;
+
+    /**
+     * Gets the current SDK configuration as a live reference.
+     * Callers should treat the returned configuration as read-only.
+     *
+     * @returns The current SDK configuration
+     */
+    getConfig(): Readonly<IOTelWebSdkConfig>;
+}

shared/otel-core/src/interfaces/otel/config/IOTelWebSdkConfig.ts

@@ -0,0 +1,136 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { IOTelContextManager } from "../context/IOTelContextManager";
+import { IOTelLogRecordProcessor } from "../logs/IOTelLogRecordProcessor";
+import { IOTelResource } from "../resources/IOTelResource";
+import { IOTelIdGenerator } from "../trace/IOTelIdGenerator";
+import { IOTelSampler } from "../trace/IOTelSampler";
+import { IOTelErrorHandlers } from "./IOTelErrorHandlers";
+
+/**
+ * Configuration interface for the OpenTelemetry Web SDK.
+ * Provides all configuration options required for SDK initialization.
+ *
+ *
+ * @remarks
+ * - All properties must be provided during SDK creation
+ * - Local caching of config values uses `onConfigChange` callbacks
+ * - Supports dynamic configuration — config values can change at runtime
+ *
+ * @example
+ * ```typescript
+ * const config: IOTelWebSdkConfig = {
+ *   resource: myResource,
+ *   errorHandlers: myErrorHandlers,
+ *   contextManager: myContextManager,
+ *   idGenerator: myIdGenerator,
+ *   sampler: myAlwaysOnSampler,
+ *   logProcessors: [myLogProcessor],
+ *   performanceNow: () => performance.now()
+ * };
+ *
+ * const sdk = createOTelWebSdk(config);
+ * ```
+ *
+ * @since 4.0.0
+ */
+export interface IOTelWebSdkConfig {
+    /**
+     * Resource information for telemetry source identification.
+     * Provides attributes that describe the entity producing telemetry,
+     * such as service name, version, and environment.
+     *
+     * @remarks
+     * The resource is shared across all providers (trace, log, metrics)
+     * within this SDK instance.
+     */
+    resource: IOTelResource;
+
+    /**
+     * Error handlers for SDK internal diagnostics.
+     * Provides hooks to customize how different types of errors and
+     * diagnostic messages are handled within the SDK.
+     *
+     * @remarks
+     * Error handlers are propagated to all sub-components created by the SDK.
+     * If individual handler callbacks are not provided, default behavior
+     * (console logging) is used.
+     *
+     * @see {@link IOTelErrorHandlers}
+     */
+    errorHandlers: IOTelErrorHandlers;
+
+    /**
+     * Context manager implementation.
+     * Manages the propagation of context (including active spans) across
+     * asynchronous operations.
+     *
+     * @see {@link IOTelContextManager}
+     */
+    contextManager: IOTelContextManager;
+
+    /**
+     * ID generator for span and trace IDs.
+     * Generates unique identifiers for distributed tracing.
+     *
+     * @see {@link IOTelIdGenerator}
+     */
+    idGenerator: IOTelIdGenerator;
+
+    /**
+     * Sampler implementation.
+     * Determines which traces/spans should be recorded and exported.
+     *
+     * @see {@link IOTelSampler}
+     */
+    sampler: IOTelSampler;
+
+    /**
+     * Performance timing function.
+     * Injected for testability — allows tests to control time measurement.
+     *
+     * @returns The current high-resolution time in milliseconds
+     *
+     * @example
+     * ```typescript
+     * // Production usage
+     * performanceNow: () => performance.now()
+     *
+     * // Test usage with fake timers
+     * performanceNow: () => fakeTimer.now()
+     * ```
+     */
+    performanceNow: () => number;
+
+    /**
+     * Log record processors for the log pipeline.
+     * Each processor receives log records and can transform, filter,
+     * or export them.
+     *
+     * @remarks
+     * Processors are invoked in order. If not provided, defaults to
+     * an empty array (no log processing).
+     *
+     * @see {@link IOTelLogRecordProcessor}
+     */
+    logProcessors?: IOTelLogRecordProcessor[];
+
+    // TODO: Phase 2 - Uncomment when IOTelSpanProcessor is implemented
+    // /**
+    //  * Span processors for the trace pipeline.
+    //  * Each processor receives spans and can transform, filter,
+    //  * or export them.
+    //  *
+    //  * @see IOTelSpanProcessor
+    //  */
+    // spanProcessors?: IOTelSpanProcessor[];
+
+    // TODO: Phase 5 - Uncomment when IOTelMetricReader is implemented
+    // /**
+    //  * Metric readers for the metric pipeline.
+    //  *
+    //  * @see IOTelMetricReader
+    //  */
+    // metricReaders?: IOTelMetricReader[];
+}

shared/otel-core/src/interfaces/otel/trace/IOTelTracerCtx.ts

@@ -8,7 +8,7 @@ import { IOTelSpanOptions } from "./IOTelSpanOptions";
 import { IReadableSpan } from "./IReadableSpan";
 
 /**
- * The context for the current IOTelSdk instance and it's configuration
+ * The context for a tracer instance and its configuration
  * @since 3.4.0
  */
 export interface IOTelTracerCtx {