OTel Web SDK Phase 1

shared/otel-core/CONTEXT.md

@@ -404,9 +404,6 @@ export interface IOTelWebSdkConfig {
   /** REQUIRED: Logger for SDK internal diagnostics */
   logger: IOTelLogger;
 
-  /** REQUIRED: Performance timing function (injected for testability) */
-  performanceNow: () => number;
-
   /** REQUIRED: Span processors for trace pipeline */
   spanProcessors: IOTelSpanProcessor[];
 

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/Tests/Unit/src/sdk/OTelLoggerProvider.Tests.ts

@@ -39,7 +39,7 @@ export class OTelLoggerProviderTests extends AITestClass {
         });
 
         this.testCase({
-            name: "LoggerProvider: constructor without options should use noop processor by default",
+            name: "LoggerProvider: constructor without options should use default processor",
             test: (): IPromise<void> => {
                 const provider = createLoggerProvider();
                 const sharedState = this._getSharedState(provider);
@@ -296,21 +296,14 @@ export class OTelLoggerProviderTests extends AITestClass {
         });
 
         this.testCase({
-            name: "LoggerProvider: shutdown should return noop logger for new requests",
+            name: "LoggerProvider: shutdown should return null for new requests",
             test: (): IPromise<void> => {
                 const provider = createLoggerProvider();
                 return createPromise((resolve, reject) => {
                     provider.shutdown().then(() => {
                         try {
                             const logger = provider.getLogger("default", "1.0.0");
-                            Assert.equal(typeof logger.emit, "function", "Logger should expose emit function after shutdown");
-                            let threw = false;
-                            try {
-                                logger.emit({} as IOTelLogRecord);
-                            } catch (e) {
-                                threw = true;
-                            }
-                            Assert.ok(!threw, "Logger emit should not throw after shutdown");
+                            Assert.equal(logger, null, "Logger should be null after shutdown");
                             resolve();
                         } catch (e) {
                             reject(e);
@@ -394,7 +387,7 @@ export class OTelLoggerProviderTests extends AITestClass {
 
     /**
      * Creates a mock log record processor for testing purposes.
-     * This avoids dependency on the noop package.
+     * This avoids dependency on a separate mock package.
      */
     private _createMockProcessor(): IOTelLogRecordProcessor {
         return {

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,126 @@
+// 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
+ * });
+ *
+ * // 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, or null if the SDK is shutdown or
+     * required dependencies are not configured
+     *
+     * @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 | null;
+
+    /**
+     * 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, or null if the SDK is shutdown
+     *
+     * @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 | null;
+
+    // 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 null.
+     *
+     * @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>;
+}