@interopio/otel 0.0.218 → 0.0.220

package/dist/traces/builder.d.ts

@@ -1,4 +1,4 @@
-import { type TracerProvider } from "@opentelemetry/api";
+import { ContextManager, type TracerProvider } from "@opentelemetry/api";
 import { IOInsights } from "../../insights";
 import { PropagationInfo } from "..";
 export declare class TracesManagerBuilder implements IOInsights.TracesManagerBuilder {
@@ -14,6 +14,7 @@ export declare class TracesManagerBuilder implements IOInsights.TracesManagerBui
     withSettings(settings: IOInsights.Settings): this;
     withMetrics(metrics: IOInsights.MetricsManager): this;
     withTracerProvider(tracerProvider: TracerProvider): this;
+    withContextManager(contextManager: ContextManager): this;
     withPropagationInfoStorage(store: (source: string, pi: PropagationInfo) => Promise<void>, read: (source: string) => Promise<PropagationInfo | null>): this;
     build(): IOInsights.TracesManager;
     private buildCore;

package/dist/traces/builder.js

@@ -27,6 +27,14 @@ class TracesManagerBuilder {
         this.tracerProvider = tracerProvider;
         return this;
     }
+    withContextManager(contextManager) {
+        var _a, _b;
+        this.settings = (_a = this.settings) !== null && _a !== void 0 ? _a : { enabled: false };
+        this.settings.traces = (_b = this.settings.traces) !== null && _b !== void 0 ? _b : { enabled: false };
+        this.settings.traces.contextManager = () => contextManager;
+        this.settings.traces.useOTELContextManager = true;
+        return this;
+    }
     withPropagationInfoStorage(store, read) {
         this.store = store;
         this.read = read;
@@ -47,14 +55,17 @@ class TracesManagerBuilder {
         return toReturn;
     }
     buildCore() {
-        var _a, _b, _c, _d, _e;
+        var _a, _b, _c, _d, _e, _f, _g, _h;
+        this.settings.traces = (_a = this.settings.traces) !== null && _a !== void 0 ? _a : { enabled: false };
+        this.settings.traces.otlpExporterConfig = (_b = this.settings.traces.exporterSettings) !== null && _b !== void 0 ? _b : this.settings.traces.otlpExporterConfig;
+        this.settings.traces.exporterSettings = (_c = this.settings.traces.exporterSettings) !== null && _c !== void 0 ? _c : this.settings.traces.otlpExporterConfig;
         let tracePlugin;
-        if (((_a = this.settings) === null || _a === void 0 ? void 0 : _a.enabled) !== true ||
-            ((_c = (_b = this.settings) === null || _b === void 0 ? void 0 : _b.traces) === null || _c === void 0 ? void 0 : _c.enabled) !== true ||
+        if (((_d = this.settings) === null || _d === void 0 ? void 0 : _d.enabled) !== true ||
+            ((_f = (_e = this.settings) === null || _e === void 0 ? void 0 : _e.traces) === null || _f === void 0 ? void 0 : _f.enabled) !== true ||
             !(tracePlugin = (0, __1.loadInsightsPlugin)("traces", this.logger))) {
-            return new nullTracesManager_1.NullTracesManager((_d = this.settings) === null || _d === void 0 ? void 0 : _d.traces, this.settings, this.logger);
+            return new nullTracesManager_1.NullTracesManager((_g = this.settings) === null || _g === void 0 ? void 0 : _g.traces, this.settings, this.logger);
         }
-        const manager = tracePlugin.newTracesManager(this.logger, this.settings, (_e = this.traceLogger) !== null && _e !== void 0 ? _e : this.logger, this.metrics, this.store, this.read);
+        const manager = tracePlugin.newTracesManager(this.logger, this.settings, (_h = this.traceLogger) !== null && _h !== void 0 ? _h : this.logger, this.metrics, this.store, this.read);
         return manager;
     }
 }

package/dist/traces/builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../src/traces/builder.ts"],"names":[],"mappings":";;;AACA,2DAAwD;AAGxD,0BAAgG;AAIhG,MAAa,oBAAoB;IAAjC;QAES,gBAAW,GAA6B,IAAI,CAAC;IAyEtD,CAAC;IAlEQ,UAAU,CAAC,MAAyB;QACzC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAEM,eAAe,CAAC,WAA8B;QACnD,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;IAEM,YAAY,CAAC,QAA6B;QAC/C,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAEM,WAAW,CAAC,OAAkC;QACnD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAEM,kBAAkB,CAAC,cAA8B;QACpD,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;QACrC,OAAO,IAAI,CAAC;IAChB,CAAC;IAEM,0BAA0B,CAC/B,KAA6D,EAC7D,IAAyD;QACvD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,OAAO,IAAI,CAAC;IAChB,CAAC;IAEM,KAAK;;QACV,IAAI,CAAA,MAAA,UAAU,CAAC,mBAAmB,0CAAE,MAAM;YACxC,CAAA,MAAA,IAAI,CAAC,QAAQ,0CAAE,kBAAkB,MAAK,IAAI,EAAE;YAC5C,OAAO,UAAU,CAAC,mBAAmB,CAAC,MAAM,CAAC;SAC9C;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAElC,UAAU,CAAC,mBAAmB,GAAG,MAAA,UAAU,CAAC,mBAAmB,mCAAI,EAAE,CAAC;QACtE,IAAI,CAAC,UAAU,CAAC,mBAAmB,CAAC,MAAM;aACtC,MAAA,IAAI,CAAC,QAAQ,0CAAE,kBAAkB,CAAA,EAAE;YACrC,UAAU,CAAC,mBAAmB,CAAC,MAAM,GAAG,QAAQ,CAAC;SAClD;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAEO,SAAS;;QACf,IAAI,WAA0C,CAAC;QAC/C,IAAI,CAAA,MAAA,IAAI,CAAC,QAAQ,0CAAE,OAAO,MAAK,IAAI;YAChC,CAAA,MAAA,MAAA,IAAI,CAAC,QAAQ,0CAAE,MAAM,0CAAE,OAAO,MAAK,IAAI;YACvC,CAAC,CAAC,WAAW,GAAG,IAAA,sBAAkB,EAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE;YAC7D,OAAO,IAAI,qCAAiB,CAAC,MAAA,IAAI,CAAC,QAAQ,0CAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;SACjF;QAED,MAAM,OAAO,GAAG,WAAW,CAAC,gBAAgB,CAC1C,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,QAAQ,EACb,MAAA,IAAI,CAAC,WAAW,mCAAI,IAAI,CAAC,MAAM,EAC/B,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,IAAI,CAAC,CAAC;QACb,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AA3ED,oDA2EC"}
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../src/traces/builder.ts"],"names":[],"mappings":"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"}

package/insights.d.ts

@@ -39,6 +39,7 @@ import {
 } from "@opentelemetry/sdk-logs";
 import { MeterProvider, MeterProviderOptions, type MetricReader, type PeriodicExportingMetricReaderOptions, type PushMetricExporter } from "@opentelemetry/sdk-metrics";
 import { type OTLPMetricExporterOptions } from "@opentelemetry/exporter-metrics-otlp-http";
+import { deprecate } from "util";
 
 /**
  * @docname Insights
@@ -49,17 +50,17 @@ import { type OTLPMetricExporterOptions } from "@opentelemetry/exporter-metrics-
 export namespace IOInsights {
   export interface API extends Manager<Settings> {
     /**
-     * io.insights.metrics
+     * io.insights Metrics API, often accessible as io.insights.metrics
      */
     metrics: MetricsManager;
 
     /**
-     * io.insights.traces
+     * io.insights Traces API, often accessible as io.insights.traces
      */
     traces: TracesManager;
 
     /**
-     * io.insights.logs
+     * io.insights Logs API, often accessible as io.insights.logs
      */
     logs: LogsManager;
   }
@@ -125,9 +126,42 @@ export namespace IOInsights {
    * Metrics API.
    */
   export interface MetricsManager extends Manager<MetricsSettings> {
-    get(type: MetricType): Metric | undefined;
+    /**
+     * Creates or retrieves a metric by name.
+     *
+     * If a metric is already created with this name, it will be returned.
+     *
+     * Otherwise, if settings exist for a metric with this name, either provided
+     * by the platform or by configuration, a metric will be created.
+     * 
+     * Otherwise, returns undefined.
+     *
+     * Subsequent calls to this method with the same name return the same metric.
+     *
+     * @param name the name of the metric, e.g. platform_startup
+     */
+    get(name: string): Metric | undefined;
+    /**
+     * Creates or retrieves a metric based on the provided settings.
+     *
+     * If a metric is already created with this name, it will be returned.
+     * 
+     * Otherwise, if settings exist for a metric with this name, either provided
+     * by the platform or by configuration, they will be merged with the
+     * settings provided to this method before creating it.
+     * 
+     * Otherwise, the settings provided will be used as is.
+     *
+     * Subsequent calls to this method with the same name return the same metric.
+     *
+     * @param settings settings to use when creating the metric
+     */
     getFromSettings(settings: MetricSettings): Metric | undefined;
   }
+
+  /**
+   * Builder class used to set up Metrics module.
+   */
   export interface MetricsManagerBuilder {
     build(): MetricsManager;
     withLogger(logger: Logger): this;
@@ -136,11 +170,18 @@ export namespace IOInsights {
     withDependencyContainer(container: MetricsDependencyContainer): this;
   }
 
+  /**
+   * Advanced usage. Allows overriding meterProvider and metricReaders instantiation
+   * logic.
+   */
   export type MetricsMeterProviderCreateFunc = () => {
     meterProvider: MetricsMeterProvider;
     metricReaders: MetricReader[];
   };
 
+  /**
+   * @ignore
+   */
   export interface MetricsMeterProvider extends MeterProvider {
     forceFlush(): Promise<void>;
   }
@@ -157,6 +198,7 @@ export namespace IOInsights {
       unsubscribeCallback?: () => Promise<void>
     ): Metric;
   }
+
   /**
    * @ignore
    */
@@ -325,7 +367,7 @@ export namespace IOInsights {
     user?: string;
     unit?: string;
     buckets?: number[];
-    baseMetricType?: "histogram" | "gauge"; // | "counter" | "updowncounter";
+    baseMetricType?: "histogram" | "gauge";
     additionalAttributes?: { [key: string]: unknown } | (() => { [key: string]: unknown });
     publishingSettings?: MetricPublishingSettings;
   }
@@ -334,6 +376,11 @@ export namespace IOInsights {
    * Controls the publishing of the metric.
    */
   export interface MetricPublishingSettings {
+    /**
+     * Defines sampling probability for the metric.
+     * 
+     * @default true
+     */
     sample?: number | boolean;
     /**
      * Controls the publishing of specific attributes.
@@ -355,14 +402,43 @@ export namespace IOInsights {
     reduceModality?: number;
   }
 
+  /**
+   * Base interface for all metrics.
+   */
   export interface Metric {
+    /**
+     * Settings used to create the metric.
+     */
     settings: MetricSettings;
+    /**
+     * Whether the metric is started.
+     */
     started: boolean;
 
+    /**
+     * Starts the metric, allowing it to publish values.
+     */
     start(): Promise<void>;
+    /**
+     * Stops the metric, meaning it can no long publish values.
+     */
     stop(): Promise<void>;
   }
 
+  /**
+   * Base interface for non-observable metrics with independent values, such as Gauge and Histogram.
+   */
+  export interface RecordingMetric<TData extends IOInsights.MetricData> extends Metric {
+    record(value: number, data?: TData): void;
+  }
+
+  /**
+   * Base interface for non-observable metrics with incremental values, such as Counter and UpDownCounter.
+   */
+  export interface IncrementalMetric<TData extends IOInsights.MetricData> extends Metric {
+    add(count: number, data?: TData): void;
+  }
+
   /**
    * @ignore
    */
@@ -429,11 +505,21 @@ export namespace IOInsights {
     /*rest:      */
     | "null";
 
+  /**
+   * Metric filters that can be specified as default.
+   *
+   * Metric filters allow controlling specific metric data points, e.g.
+   * whether a particular value of a specific metric will be published.
+   */
   export interface MetricDefaultFilter {
+    /**
+     * Matches the type of the metric.
+     */
     type?: MetricType;
-    enabled: boolean;
-    sample?: number | boolean;
-    overrideDefaultFilters?: boolean;
+    /**
+     * Matches the attributes attached to a metric value. Not all metrics
+     * have all attribute values.
+     */
     attributes?: {
       /**
        * Indicates whether the workspace loading involved a complex operation where existing apps are added to a new workspace.
@@ -445,11 +531,42 @@ export namespace IOInsights {
        */
       includesFrameCreation?: boolean;
     };
+    /**
+     * Whether or not the value for the matching metric will be published.
+     */
+    enabled: boolean;
+    /**
+     * Sampling probability.
+     */
+    sample?: number | boolean;
+    /**
+     * If `true`, this filter rule will be matched before any default filters provided
+     * by io.Connect. The default filters are usually meant filter out non-representative
+     * operations (e.g. partial workspace loads), but you can use this property to
+     * force them to be measured.
+     * If `false`, default filters will be matched before this filtering rule.
+     *
+     * @default false
+     */
+    overrideDefaultFilters?: boolean;
   }
+  /**
+   * Metric filters that can be specified as part of a specific metric.
+   */
   export interface MetricFilter extends MetricDefaultFilter {
+    /**
+     * The name of the matched metric.
+     */
     name: string;
+    /**
+     * The type of the matched metric.
+     */
     type: MetricType;
   }
+
+  /**
+   * @ignore
+   */
   export interface MetricsDependencyContainer {
     performanceProvider: PerformanceProvider;
     instanceStartedHandler: InstanceActionHandler;
@@ -477,12 +594,19 @@ export namespace IOInsights {
     platformStartedHandler: PlatformStartedHandler;
     platformErrorHandler: PlatformErrorHandler;
   }
+  /**
+   * @ignore
+   */
   export type Unsubscribe = () => void;
-
+  /**
+   * @ignore
+   */
   export interface InstanceActionHandlerArgs {
     application: string;
   }
-
+  /**
+   * @ignore
+   */
   export type InstanceActionHandler = (
     callback: (args: InstanceActionHandlerArgs) => void
   ) => Unsubscribe;
@@ -490,49 +614,71 @@ export namespace IOInsights {
   export interface InstanceErrorHandlerArgs {
     application: string;
   }
-
+  /**
+   * @ignore
+   */
   export type InstanceErrorHandler = (
     callback: (args: InstanceErrorHandlerArgs) => void
   ) => Unsubscribe;
-
+  /**
+   * @ignore
+   */
   export interface PlatformErrorHandlerArgs {}
-
+  /**
+   * @ignore
+   */
   export type PlatformErrorHandler = (
     callback: (args: PlatformErrorHandlerArgs) => void
   ) => Unsubscribe;
-
+  /**
+   * @ignore
+   */
   export interface InstanceCrashHandlerArgs {
     application: string;
     reason: string;
   }
-
+  /**
+   * @ignore
+   */
   export type InstanceCrashHandler = (
     callback: (args: InstanceCrashHandlerArgs) => void
   ) => Unsubscribe;
-
+  /**
+   * @ignore
+   */
   export interface InstanceFocusedHandlerArgs {
     application: string;
     focused: boolean;
   }
-
+  /**
+   * @ignore
+   */
   export type InstanceFocusedHandler = (
     callback: (args: InstanceFocusedHandlerArgs) => void
   ) => Unsubscribe;
-
+  /**
+   * @ignore
+   */
   export interface LayoutRestoredHandlerArgs {
     layout: string;
     startTime: Date;
     endTime: Date;
   }
-
+  /**
+   * @ignore
+   */
   export type LayoutRestoredHandler = (
     callback: (args: LayoutRestoredHandlerArgs) => void
   ) => Unsubscribe;
-
+  /**
+   * @ignore
+   */
   export interface WorkspaceActionHandlerArgs {
     layout: string;
   }
-
+  /**
+   * @ignore
+   */
   export interface WorkspaceTimedActionHandlerArgs extends WorkspaceActionHandlerArgs {
     startTime: Date;
     endTime: Date;
@@ -547,7 +693,9 @@ export namespace IOInsights {
     includesFrameCreation: boolean;
     [x: string]: any;
   }
-
+  /**
+   * @ignore
+   */
   export interface WorkspaceRestoredHandlerArgs extends WorkspaceActionHandlerArgs {
     startTime: Date;
     endTime: Date;
@@ -562,7 +710,9 @@ export namespace IOInsights {
     includesFrameCreation?: boolean;
     [x: string]: any;
   }
-
+  /**
+   * @ignore
+   */
   export interface WorkspaceAppsStartedHandlerArgs extends WorkspaceTimedActionHandlerArgs {
     /**
      * Indicates whether the workspace loading involved a complex operation where existing apps are added to a new workspace.
@@ -570,56 +720,86 @@ export namespace IOInsights {
      */
     complexLoad: boolean;
   }
-
+  /**
+   * @ignore
+   */
   export interface WorkspaceStartupHandlerArgs extends WorkspaceAppsStartedHandlerArgs {
     /**
      * Indicates whether the metric includes the time to create and load the Workspace Frame App when the workspace is opened in a new frame.
      */
     includesFrameCreation: boolean;
   }
-
+  /**
+   * @ignore
+   */
   export interface WorkspaceSavedHandlerArgs extends WorkspaceActionHandlerArgs {
     oldLayout: string;
   }
+    /**
+   * @ignore
+   */
   export interface WorkspaceLoadedHandlerArgs extends WorkspaceActionHandlerArgs {
     startTime: Date;
     endTime: Date;
     complexLoad?: boolean;
     includesFrameCreation?: boolean;
   }
-
+  /**
+   * @ignore
+   */
   export type WorkspaceGenericActionHandler<T extends WorkspaceActionHandlerArgs> = (
     callback: (args: T) => void
   ) => Unsubscribe;
-
+  /**
+   * @ignore
+   */
   export type WorkspaceActionHandler = WorkspaceGenericActionHandler<WorkspaceActionHandlerArgs>;
+  /**
+   * @ignore
+   */
   export type WorkspaceLoadedHandler = WorkspaceGenericActionHandler<WorkspaceLoadedHandlerArgs>;
+  /**
+   * @ignore
+   */
   export type WorkspaceRestoredHandler =
     WorkspaceGenericActionHandler<WorkspaceRestoredHandlerArgs>;
+  /**
+   * @ignore
+   */
   export type WorkspaceSavedHandler = WorkspaceGenericActionHandler<WorkspaceSavedHandlerArgs>;
-
+  /**
+   * @ignore
+   */
   export interface InstanceReadyHandlerArgs {
     application: string;
     startTime: Date;
     endTime: Date;
     api: string;
   }
-
+  /**
+   * @ignore
+   */
   export type InstanceReadyHandler = (
     callback: (args: InstanceReadyHandlerArgs) => void
   ) => Unsubscribe;
-
+  /**
+   * @ignore
+   */
   export interface PlatformStartedHandlerArgs {
     startTime: Date;
     endTime: Date;
     idleTimeMs?: number;
     api: string;
   }
-
+  /**
+   * @ignore
+   */
   export type PlatformStartedHandler = (
     callback: (args: PlatformStartedHandlerArgs) => void
   ) => Unsubscribe;
-
+  /**
+   * @ignore
+   */
   export interface PerformanceProvider {
     getAppsCPU(): Promise<AppCPU[] | undefined>;
     getAppsMemory(): Promise<AppMemory[] | undefined>;
@@ -627,25 +807,33 @@ export namespace IOInsights {
     getSystemCPU(): Promise<SystemCPU | undefined>;
     getSystemMemory(): Promise<SystemMemory | undefined>;
   }
-
+  /**
+   * @ignore
+   */
   export interface AppCPU {
     app: string;
     instance: string;
     cpu: number;
   }
-
+  /**
+   * @ignore
+   */
   export interface AppMemory {
     app: string;
     instance: string;
     memory: number;
   }
-
+  /**
+   * @ignore
+   */
   export interface SystemCPU {
     current: number;
     average: number;
     platform: number;
   }
-
+  /**
+   * @ignore
+   */
   export interface SystemMemory {
     platformTotal: number;
     systemTotal: number;
@@ -656,6 +844,9 @@ export namespace IOInsights {
    * Traces API.
    */
   export interface TracesManager extends Manager<TracesSettings> {
+    /**
+     * The tracing state representing the currently active trace and span, if any.
+     */
     currentTracingState: TracingState | null;
 
     /**
@@ -678,6 +869,7 @@ export namespace IOInsights {
      * Works in conjunction with the userJourney setting to track the user's entire session flow.
      */
     userJourneyMarker?: MarkerSpanCallback;
+    /** @ignore */
     setUserJourneyMarker(userJourneyMarker: MarkerSpanCallback): void;
 
     /**
@@ -695,8 +887,18 @@ export namespace IOInsights {
      */
     clickstreamMarker?: MarkerSpanCallback;
 
+    /**
+     * Allows updating the configured filters.
+     */
     setFilterConfig(filters: SpanFilter[]): void;
 
+    /**
+     * Allows creating a span for a named trace.
+     *
+     * @param source The name of the span to create.
+     * @param traceName The name of the trace to nest the span in. If one doesn't exist, it will be created.
+     * @param callback Logic to execute in the span.
+     */
     withSequenceSpanEx<T>(
       source: string,
       traceName:
@@ -705,6 +907,14 @@ export namespace IOInsights {
       callback:
         | IOInsights.WithSpanCallback<T>): Promise<T>;
 
+    /**
+     * Allows creating a span for a named trace.
+     *
+     * @param source The name of the span to create.
+     * @param traceName The name of the trace to nest the span in. If one doesn't exist, it will be created.
+     * @param filteringContext Filtering context used to match against the tracing filtering configuration.
+     * @param callback Logic to execute in the span.
+     */
     withSequenceSpanEx<T>(
       source: string,
       traceName:
@@ -716,6 +926,15 @@ export namespace IOInsights {
       callback:
         | IOInsights.WithSpanCallback<T>): Promise<T>;
 
+    /**
+     * Allows creating a span for a named trace.
+     *
+     * @param source The name of the span to create.
+     * @param traceName The name of the trace to nest the span in. If one doesn't exist, it will be created.
+     * @param filteringContext Filtering context used to match against the tracing filtering configuration.
+     * @param options Options to use when creating the span.
+     * @param callback Logic to execute in the span.
+     */
     withSequenceSpanEx<T>(
       source: string,
       traceName:
@@ -730,6 +949,9 @@ export namespace IOInsights {
       callback:
         | IOInsights.WithSpanCallback<T>): Promise<T>;
 
+    /**
+     * @ignore
+     */
     withSequenceSpanEx<T>(
       source: string,
       traceName:
@@ -746,11 +968,24 @@ export namespace IOInsights {
       callback?:
         | IOInsights.WithSpanCallback<T>): Promise<T>;
 
+    /**
+     * Allows creating a span for a named trace.
+     *
+     * @param source The name of the span to create. The name of the trace will be <source>.start, and if one doesn't exist, it will be created.
+     * @param callback Logic to execute in the span.
+     */
     withSequenceSpan<T>(
       source: string,
       callback:
         | IOInsights.WithSpanCallback<T>): Promise<T>;
 
+    /**
+     * Allows creating a span for a named trace.
+     *
+     * @param source The name of the span to create. The name of the trace will be <source>.start, and if one doesn't exist, it will be created.
+     * @param filteringContext Filtering context used to match against the tracing filtering configuration.
+     * @param callback Logic to execute in the span.
+     */
     withSequenceSpan<T>(
       source: string,
       filteringContext:
@@ -759,6 +994,14 @@ export namespace IOInsights {
       callback:
         | IOInsights.WithSpanCallback<T>): Promise<T>;
 
+    /**
+     * Allows creating a span for a named trace.
+     *
+     * @param source The name of the span to create. The name of the trace will be <source>.start, and if one doesn't exist, it will be created.
+     * @param filteringContext Filtering context used to match against the tracing filtering configuration.
+     * @param options Options to use when creating the span.
+     * @param callback Logic to execute in the span.
+     */
     withSequenceSpan<T>(
       source: string,
       filteringContext:
@@ -770,6 +1013,9 @@ export namespace IOInsights {
       callback:
         | IOInsights.WithSpanCallback<T>): Promise<T>;
 
+  /**
+   * @ignore
+   */
   withSequenceSpan<T>(
     source: string,
     filteringContextOrCallback:
@@ -783,14 +1029,36 @@ export namespace IOInsights {
     callback?:
       | IOInsights.WithSpanCallback<T>): Promise<T>;
 
-    withSpan<T>(source: string, callback: WithSpanCallback<T>): T;
-
+    /**
+     * Allows creating a span for the currently active trace. If one doesn't exist, it will be created.
+     *
+     * @param source The name of the span to create.
+     * @param callback Logic to execute in the span.
+     */
+    withSpan<T>(
+      source: string,
+      callback: WithSpanCallback<T>): T;
+    /**
+     * Allows creating a span for the currently active trace. If one doesn't exist, it will be created.
+     *
+     * @param source The name of the span to create.
+     * @param filteringContext Filtering context used to match against the tracing filtering configuration.
+     * @param callback Logic to execute in the span.
+     */
     withSpan<T>(
       source: string,
       filteringContext: FilteringContext,
       callback: WithSpanCallback<T>
     ): T;
 
+    /**
+     * Allows creating a span for the currently active trace or a specified trace. If one doesn't exist, it will be created.
+     *
+     * @param source The name of the span to create.
+     * @param filteringContext Filtering context used to match against the tracing filtering configuration.
+     * @param propagationInfo Span and trace id to use for manually nesting the new trace.
+     * @param callback Logic to execute in the span.
+     */
     withSpan<T>(
       source: string,
       filteringContext: FilteringContext,
@@ -798,6 +1066,15 @@ export namespace IOInsights {
       callback: WithSpanCallback<T>
     ): T;
 
+    /**
+     * Allows creating a span for the currently active trace or a specified trace. If one doesn't exist, it will be created.
+     *
+     * @param source The name of the span to create.
+     * @param filteringContext Filtering context used to match against the tracing filtering configuration.
+     * @param propagationInfo Span and trace id to use for manually nesting the new trace.
+     * @param options Options to use when creating the span.
+     * @param callback Logic to execute in the span.
+     */
     withSpan<T>(
       source: string,
       filteringContext: FilteringContext,
@@ -808,6 +1085,9 @@ export namespace IOInsights {
   }
 
   interface TracingState {
+    /**
+     * Ends the current span. Same as endSpan().
+     */
     end(): void;
     /**
      * If false, this is a placeholder object, and all its methods
@@ -858,6 +1138,9 @@ export namespace IOInsights {
      */
     enabled: boolean;
 
+    /**
+     * Property for internal use.
+     */
     rootPropagationInfo?: PropagationInfo;
 
     /**
@@ -1051,10 +1334,16 @@ export namespace IOInsights {
      *
      * If 'url' is specified, TracerProvider will
      * have an OTLPTraceExporter with 'url' as detination URL and
-     * 'otlpExporterConfig' as additional config.
+     * 'exporterSettings' as additional config.
      */
     exporterSettings?: OTLPExporterNodeConfigBase;
 
+    /**
+     * @deprecated Use exporterSettings
+     */
+    otlpExporterConfig?: OTLPExporterNodeConfigBase;
+
+
     /**
      * OTEL TracerConfig - provides an interface for configuring a Basic Tracer.
      */
@@ -1103,31 +1392,55 @@ export namespace IOInsights {
      */
     additionalResourceAttributes?: { [x: string]: unknown } | (() => { [x: string]: unknown });
 
+    /**
+     * Allows specifying a constructor callback for creating the tracerProvider instance.
+     */
     tracerProvider?: (tracerProviderSettings: TracerConfig, tracesSettings: IOInsights.TracesSettings, settings: IOInsights.Settings) => TracerProvider;
+    /**
+     * Allows specifying a constructor callback for creating the Sampler instance.
+     */
     sampler?: (defaultSampler: Sampler, tracesSettings: IOInsights.TracesSettings, settings: IOInsights.Settings) => Sampler;
+    /**
+     * Allows specifying a constructor callback for creating the SpanProcessor instances.
+     */
     spanProcessors?: (processorSettings: BatchSpanProcessorBrowserConfig | undefined, exporterSettings: OTLPExporterNodeConfigBase, tracesSettings: IOInsights.TracesSettings, settings: IOInsights.Settings) => SpanProcessor[];
+    /**
+     * Allows specifying a constructor callback for creating the SpanExporter instances.
+     */
     spanExporters?: (exporterSettings: OTLPExporterNodeConfigBase, tracesSettings: IOInsights.TracesSettings, settings: IOInsights.Settings) => SpanExporter[];
+    /**
+     * Allows specifying a constructor callback for creating the TextMapPropagator instance.
+     */
     propagator?: (tracesSettings: IOInsights.TracesSettings, settings: IOInsights.Settings) => TextMapPropagator;
+    /**
+     * Allows specifying a constructor callback for creating the ContextManager instance.
+     */
     contextManager?: (tracesSettings: IOInsights.TracesSettings, settings: IOInsights.Settings) => ContextManager;
-    providerRegistrationSettings?: (tracesSettings: IOInsights.TracesSettings, settings: IOInsights.Settings) => {
-      propagator?: TextMapPropagator;
-      contextManager?: ContextManager;
-    };
   }
 
+  /**
+   * Builder class used to set up Traces module.
+   */
   export interface TracesManagerBuilder {
     build(): TracesManager;
     withLogger(logger: Logger): this;
     withSettings(settings: TracesSettings): this;
     withMetrics(metrics: IOInsights.MetricsManager): this;
     withTraceLogger(traceLogger: IOInsights.Logger): this;
+    withContextManager(contextManager: ContextManager): this;
     withPropagationInfoStorage(
       store: (source: string, pi: PropagationInfo) => Promise<void>,
       read: (source: string) => Promise<PropagationInfo | null>): this;
   }
 
+  /**
+   * Callback executed during a span. See `withSpan`
+   */
   export type WithSpanCallback<T> = (tracingState: TracingState) => T;
 
+  /**
+   * Options that can be provided when using `withSpan` as a decorator
+   */
   export interface WithSpanDecoratorOptions extends WithSpanOptions {
     argMapping?:
       | { [x: string]: string }
@@ -1136,11 +1449,17 @@ export namespace IOInsights {
     thisMapping?: { [x: string]: string } | ((that: any) => any);
   }
 
+  /**
+   * Span and trace information that can be used to manually control the
+   * nesting of a newly created span.
+   */
   export interface PropagationInfo {
     traceparent?: string;
     tracestate?: string;
     forceTracing?: boolean;
   }
+
+  /** @ignore */
   export interface PropagationInfoCarrier {
     __interopIOTracePropagationInfo?: PropagationInfo;
   }
@@ -1150,6 +1469,9 @@ export namespace IOInsights {
     fullFilteringContext: FilteringContext
   ) => PropagationInfo | null;
 
+  /**
+   * Key-value pair that can be used to match a span against a filter in the tracing filtering config.
+   */
   export type FilteringContext = {
     app?: string;
     user?: string;
@@ -1161,6 +1483,9 @@ export namespace IOInsights {
     userId?: string;
   } & Record<string, any>;
 
+  /**
+   * Verbosity level of a span. Controls how much information is added using `.addData()`.
+   */
   export enum SpanVerbosity {
     OFF,
     LOWEST,
@@ -1170,6 +1495,10 @@ export namespace IOInsights {
     WARN,
     HIGHEST,
   }
+
+  /**
+   * Options that can be used when creating a span.
+   */
   export interface WithSpanOptions extends Omit<SpanCreationOptions, "sample"> {
     defaultFilters?: SpanFilter[];
     structure?: "sibling" | "nested";
@@ -1294,6 +1623,7 @@ export namespace IOInsights {
      */
     minDurationMs?: number;
 
+    /** @ignore */
     getPropagationInfo?: PropagationInfoCallback;
 
     /**
@@ -1313,6 +1643,9 @@ export namespace IOInsights {
     overrideDefaultFilters?: boolean;
   }
 
+  /**
+   * Filter entry that can match a span to control its settings.
+   */
   export interface SpanFilter extends Omit<SpanCreationOptions, "getPropagationInfo"> {
     /**
      * Specifies the source string used for matching spans.
@@ -1335,17 +1668,21 @@ export namespace IOInsights {
       [key: string]: string | number | boolean;
     };
   }
+
+  // /**
+  //  * Configuration for automatic instrumentation of common browser operations.
+  //  * Enables automatic tracing of document load, user interactions, fetch requests, and XHR calls.
+  //  */ 
+  // export interface AutoInstrumentationOptions {
+  //   documentLoad?: boolean | DocumentLoadInstrumentationConfig;
+  //   userInteraction?: boolean | UserInteractionInstrumentationConfig;
+  //   fetch?: boolean | FetchInstrumentationConfig;
+  //   xhr?: boolean | XMLHttpRequestInstrumentationConfig;
+  //   ignoreObservabilityUrls?: boolean;
+  // }
   /**
-   * Configuration for automatic instrumentation of common browser operations.
-   * Enables automatic tracing of document load, user interactions, fetch requests, and XHR calls.
-   */ 
-  export interface AutoInstrumentationOptions {
-    documentLoad?: boolean | DocumentLoadInstrumentationConfig;
-    userInteraction?: boolean | UserInteractionInstrumentationConfig;
-    fetch?: boolean | FetchInstrumentationConfig;
-    xhr?: boolean | XMLHttpRequestInstrumentationConfig;
-    ignoreObservabilityUrls?: boolean;
-  }
+   * Settings used to control the sampling probability of spans.
+   */
   export interface SamplingSettings {
     /**
      * Span name to determine if span will match this sampling setting entry.
@@ -1505,6 +1842,9 @@ export namespace IOInsights {
   export interface LogsManager extends Manager<LogsSettings> {
     emit(logRecord: LogRecord): Promise<void> | null;
   }
+  /**
+   * Builder class used to set up Logs module.
+   */
   export interface LogsManagerBuilder {
     build(): LogsManager;
     withLogger(logger: Logger): this;
@@ -1680,6 +2020,9 @@ export namespace IOInsights {
     enabled?: boolean;
   }
 
+  /**
+   * Level of log entry.
+   */
   export const enum LoggerLogLevel {
     NONE = 0,
     ERROR = 30,
@@ -1690,6 +2033,9 @@ export namespace IOInsights {
     ALL = 9999,
   }
 
+  /**
+   * Log interface that can be passed to library for its own logging.
+   */
   export interface Logger {
     level?: LoggerLogLevel;
     error(message: string, ...args: unknown[]): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interopio/otel",
-  "version": "0.0.218",
+  "version": "0.0.220",
   "description": "io.Insights observability library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -39,7 +39,8 @@
     "@opentelemetry/resources": "^2.0.0",
     "@opentelemetry/sdk-logs": "^0.200.0",
     "@opentelemetry/sdk-metrics": "^2.0.0",
-    "@opentelemetry/sdk-trace-base": "^2.0.0"
+    "@opentelemetry/sdk-trace-base": "^2.0.0",
+    "log4js": "^6.9.1"
   },
   "devDependencies": {
     "@types/chai": "^4.3.20",
@@ -49,7 +50,6 @@
     "@typescript-eslint/parser": "^7.18.0",
     "chai": "^4.5.0",
     "eslint": "^8.57.1",
-    "log4js": "^6.9.1",
     "mocha": "^10.8.2",
     "rimraf": "^5.0.10",
     "typescript": "^4.9.5"