|
| 1 | +// Copyright (c) Microsoft Corporation. All rights reserved. |
| 2 | +// Licensed under the MIT License. |
| 3 | + |
| 4 | +import { IPromise } from "@nevware21/ts-async"; |
| 5 | +import { IOTelWebSdkConfig } from "./config/IOTelWebSdkConfig"; |
| 6 | +import { IOTelLogger } from "./logs/IOTelLogger"; |
| 7 | +import { IOTelLoggerOptions } from "./logs/IOTelLoggerOptions"; |
| 8 | +import { IOTelTracer } from "./trace/IOTelTracer"; |
| 9 | +import { IOTelTracerOptions } from "./trace/IOTelTracerOptions"; |
| 10 | + |
| 11 | +/** |
| 12 | + * Main interface for the OpenTelemetry Web SDK. |
| 13 | + * Provides access to tracer and logger providers, configuration management, |
| 14 | + * and complete lifecycle control including unload/cleanup. |
| 15 | + * |
| 16 | + * @remarks |
| 17 | + * - Supports multiple isolated instances without global state |
| 18 | + * - All dependencies injected through {@link IOTelWebSdkConfig} |
| 19 | + * - Complete unload support — every instance must fully clean up on unload |
| 20 | + * |
| 21 | + * @example |
| 22 | + * ```typescript |
| 23 | + * const sdk = createOTelWebSdk({ |
| 24 | + * resource: myResource, |
| 25 | + * errorHandlers: myHandlers, |
| 26 | + * contextManager: myContextManager, |
| 27 | + * idGenerator: myIdGenerator, |
| 28 | + * sampler: myAlwaysOnSampler |
| 29 | + * }); |
| 30 | + * |
| 31 | + * // Get a tracer and create spans |
| 32 | + * const tracer = sdk.getTracer("my-service"); |
| 33 | + * const span = tracer.startSpan("operation"); |
| 34 | + * span.end(); |
| 35 | + * |
| 36 | + * // Get a logger and emit log records |
| 37 | + * const logger = sdk.getLogger("my-service"); |
| 38 | + * logger.emit({ body: "Hello, World!" }); |
| 39 | + * |
| 40 | + * // Cleanup when done |
| 41 | + * sdk.shutdown(); |
| 42 | + * ``` |
| 43 | + * |
| 44 | + * @since 4.0.0 |
| 45 | + */ |
| 46 | +export interface IOTelWebSdk { |
| 47 | + /** |
| 48 | + * Returns a Tracer for creating spans. |
| 49 | + * Tracers are cached by name + version combination — requesting the same |
| 50 | + * name and version returns the same Tracer instance. |
| 51 | + * |
| 52 | + * @param name - The name of the tracer or instrumentation library |
| 53 | + * @param version - The version of the tracer or instrumentation library |
| 54 | + * @param options - Additional tracer options (e.g., schemaUrl) |
| 55 | + * @returns A Tracer with the given name and version, or null if the SDK is shutdown or |
| 56 | + * required dependencies are not configured |
| 57 | + * |
| 58 | + * @example |
| 59 | + * ```typescript |
| 60 | + * const tracer = sdk.getTracer("my-component", "1.0.0"); |
| 61 | + * const span = tracer.startSpan("my-operation"); |
| 62 | + * ``` |
| 63 | + */ |
| 64 | + getTracer(name: string, version?: string, options?: IOTelTracerOptions): IOTelTracer | null; |
| 65 | + |
| 66 | + /** |
| 67 | + * Returns a Logger for emitting log records. |
| 68 | + * Loggers are cached by name + version + schemaUrl combination — |
| 69 | + * requesting the same combination returns the same Logger instance. |
| 70 | + * |
| 71 | + * @param name - The name of the logger or instrumentation library |
| 72 | + * @param version - The version of the logger or instrumentation library |
| 73 | + * @param options - Additional logger options (e.g., schemaUrl, scopeAttributes) |
| 74 | + * @returns A Logger with the given name and version, or null if the SDK is shutdown |
| 75 | + * |
| 76 | + * @example |
| 77 | + * ```typescript |
| 78 | + * const logger = sdk.getLogger("my-component", "1.0.0"); |
| 79 | + * logger.emit({ body: "Operation completed", severityText: "INFO" }); |
| 80 | + * ``` |
| 81 | + */ |
| 82 | + getLogger(name: string, version?: string, options?: IOTelLoggerOptions): IOTelLogger | null; |
| 83 | + |
| 84 | + // TODO: Phase 5 - Uncomment when metrics are implemented |
| 85 | + // /** |
| 86 | + // * Returns a Meter for recording metrics. |
| 87 | + // * @param name - The name of the meter or instrumentation library |
| 88 | + // * @param version - The version of the meter or instrumentation library |
| 89 | + // * @param options - Additional meter options |
| 90 | + // * @returns A Meter with the given name and version |
| 91 | + // */ |
| 92 | + // getMeter(name: string, version?: string, options?: IOTelMeterOptions): IOTelMeter; |
| 93 | + |
| 94 | + /** |
| 95 | + * Forces all providers to flush any buffered data. |
| 96 | + * This is useful before application shutdown to ensure all telemetry |
| 97 | + * is exported. |
| 98 | + * |
| 99 | + * @returns A promise that resolves when the flush is complete |
| 100 | + */ |
| 101 | + forceFlush(): IPromise<void>; |
| 102 | + |
| 103 | + /** |
| 104 | + * Shuts down the SDK and releases all resources. |
| 105 | + * After shutdown, the SDK instance is no longer usable — all |
| 106 | + * subsequent calls to `getTracer` or `getLogger` will return null. |
| 107 | + * |
| 108 | + * @remarks |
| 109 | + * Shutdown performs the following: |
| 110 | + * - Flushes all pending telemetry |
| 111 | + * - Shuts down all providers (trace, log) |
| 112 | + * - Removes all config change listeners (calls `IUnloadHook.rm()`) |
| 113 | + * - Clears all cached instances |
| 114 | + * |
| 115 | + * @returns A promise that resolves when shutdown is complete |
| 116 | + */ |
| 117 | + shutdown(): IPromise<void>; |
| 118 | + |
| 119 | + /** |
| 120 | + * Gets the current SDK configuration as a live reference. |
| 121 | + * Callers should treat the returned configuration as read-only. |
| 122 | + * |
| 123 | + * @returns The current SDK configuration |
| 124 | + */ |
| 125 | + getConfig(): Readonly<IOTelWebSdkConfig>; |
| 126 | +} |
0 commit comments