@interopio/otel 0.0.219 → 0.0.221

package/insights.d.ts

@@ -48,25 +48,33 @@ import { deprecate } from "util";
  * io.Insights API.
  */
 export namespace IOInsights {
+  /**
+   * Entry point into the io.Insights API
+   */
   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;
+
+    /**
+     * io.Insights settings
+     */
+    settings: Settings;
   }
 
   /**
-   * Builder interface for constructing the IO.Insights API.
+   * Builder interface for constructing the io.Insights API.
    */
   export interface APIBuilder {
     /**
@@ -126,9 +134,46 @@ export namespace IOInsights {
    * Metrics API.
    */
   export interface MetricsManager extends Manager<MetricsSettings> {
-    get(type: MetricType): Metric | undefined;
+    /**
+     * Metrics settings.
+     */
+    settings: MetricsSettings;
+    /**
+     * 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;
@@ -137,11 +182,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>;
   }
@@ -158,6 +210,7 @@ export namespace IOInsights {
       unsubscribeCallback?: () => Promise<void>
     ): Metric;
   }
+
   /**
    * @ignore
    */
@@ -317,6 +370,9 @@ export namespace IOInsights {
     exporterSettings?: (OTLPExporterNodeConfigBase & OTLPMetricExporterOptions);
   }
 
+  /**
+   * Settings describing a metric.
+   */
   export interface MetricSettings {
     enabled: boolean;
     type: MetricType;
@@ -326,7 +382,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;
   }
@@ -335,6 +391,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.
@@ -356,14 +417,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
    */
@@ -430,11 +520,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,12 +545,43 @@ export namespace IOInsights {
        * 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;
-    };
+    } & Record<string, any>;
+    /**
+     * 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;
@@ -478,12 +609,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;
@@ -491,49 +629,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;
@@ -548,7 +708,9 @@ export namespace IOInsights {
     includesFrameCreation: boolean;
     [x: string]: any;
   }
-
+  /**
+   * @ignore
+   */
   export interface WorkspaceRestoredHandlerArgs extends WorkspaceActionHandlerArgs {
     startTime: Date;
     endTime: Date;
@@ -563,7 +725,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.
@@ -571,56 +735,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>;
@@ -628,25 +822,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;
@@ -657,6 +859,13 @@ export namespace IOInsights {
    * Traces API.
    */
   export interface TracesManager extends Manager<TracesSettings> {
+    /**
+     * Traces settings.
+     */
+    settings: TracesSettings;
+    /**
+     * The tracing state representing the currently active trace and span, if any.
+     */
     currentTracingState: TracingState | null;
 
     /**
@@ -679,6 +888,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;
 
     /**
@@ -696,8 +906,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:
@@ -706,6 +926,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:
@@ -717,6 +945,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:
@@ -731,6 +968,9 @@ export namespace IOInsights {
       callback:
         | IOInsights.WithSpanCallback<T>): Promise<T>;
 
+    /**
+     * @ignore
+     */
     withSequenceSpanEx<T>(
       source: string,
       traceName:
@@ -747,11 +987,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:
@@ -760,6 +1013,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:
@@ -771,6 +1032,9 @@ export namespace IOInsights {
       callback:
         | IOInsights.WithSpanCallback<T>): Promise<T>;
 
+  /**
+   * @ignore
+   */
   withSequenceSpan<T>(
     source: string,
     filteringContextOrCallback:
@@ -784,14 +1048,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,
@@ -799,6 +1085,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,
@@ -809,6 +1104,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
@@ -859,6 +1157,9 @@ export namespace IOInsights {
      */
     enabled: boolean;
 
+    /**
+     * Property for internal use.
+     */
     rootPropagationInfo?: PropagationInfo;
 
     /**
@@ -879,19 +1180,19 @@ export namespace IOInsights {
     /**
      * Name of span hit counter metric, set to null to disable.
      *
-     * Defaults to 'insights_trace_count'.
+     * @default insights_trace_count
      */
     countMetric?: string;
     /**
      * Name of span duration histogram metric, set to null to disable.
      *
-     * Defaults to 'insights_trace_duration'.
+     * @default insights_trace_duration
      */
     durationMetric?: string;
     /**
      * Name of span result counter metric, set to null to disable.
      *
-     * Defaults to 'insights_trace_result'.
+     * @default insights_trace_result
      */
     resultMetric?: string;
 
@@ -1072,12 +1373,6 @@ export namespace IOInsights {
      */
     processorSettings?: BatchSpanProcessorBrowserConfig;
 
-    /**
-     * Configuration for automatic instrumentation of common browser operations.
-     * Enables automatic tracing of document load, user interactions, fetch requests, and XHR calls.
-     */
-    autoInstrumentations?: AutoInstrumentationOptions;
-
     /**
      * Maximum length for parent operation names in span hierarchies.
      */
@@ -1110,18 +1405,35 @@ 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;
@@ -1134,8 +1446,14 @@ export namespace IOInsights {
       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 }
@@ -1144,20 +1462,30 @@ 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;
   }
 
+  /** @ignore */
   export type PropagationInfoCallback = (
     source: string,
     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;
@@ -1169,6 +1497,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,
@@ -1178,6 +1509,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";
@@ -1187,7 +1522,7 @@ export namespace IOInsights {
     /**
      * Whether the span will be created or will be a no-op. See 'Filter'.
      *
-     * Defaults to 'true'.
+     * @default true
      */
     enabled?: boolean;
     /**
@@ -1198,34 +1533,34 @@ export namespace IOInsights {
     /**
      * Default span attribute verbosity level. See 'Filter'.
      *
-     * Defaults to 'INFO'.
+     * @default INFO
      */
     level?: keyof typeof SpanVerbosity;
     /**
      * Whether the filtering context will be added as span attributes
      * to the span. See 'Filter'.
      *
-     * Defaults to 'true'.
+     * @default true
      */
     addContextToTrace?: boolean;
     /**
      * Whether the span's status will be set to OK on completion, if
      * it's still UNSET. See 'Filter'.
      *
-     * Defaults to 'false'.
+     * @default false
      */
     autoSetSuccessStatus?: boolean;
     /**
      * Default sampling setting/probability. See 'SamplingSettings'.
      *
-     * Defaults to 'true'.
+     * @default true
      */
     sample?: number | boolean;
     /**
      * Whether the span will not inject its propagation info into data
      * transfer objects for span nesting across system boundaries.
      *
-     * Defaults to 'false'.
+     * @default false
      */
     disablePropagation?: boolean;
     /**
@@ -1248,7 +1583,7 @@ export namespace IOInsights {
     /**
      * Whether the span will be counted in the insights_trace_count metric. See TracesSettings.countMetric.
      *
-     * Defaults to 'false'.
+     * @default false
      */
     countMetric?: boolean;
     /**
@@ -1258,7 +1593,7 @@ export namespace IOInsights {
     /**
      * Whether the span will be counted in the insights_trace_result metric. See TracesSettings.resultMetric.
      *
-     * Defaults to 'false'.
+     * @default false
      */
     resultMetric?: boolean;
     /**
@@ -1268,7 +1603,7 @@ export namespace IOInsights {
     /**
      * Whether the span will be counted in the insights_trace_duration metric. See TracesSettings.durationtMetric.
      *
-     * Defaults to 'false'.
+     * @default false
      */
     durationMetric?: boolean;
     /**
@@ -1279,7 +1614,7 @@ export namespace IOInsights {
      * Whether the span will be able to start a new trace. If false, it will only
      * be able to be added to an existing trace.
      *
-     * Defaults to 'true'.
+     * @default true
      */
     canBeRoot?: boolean;
     /**
@@ -1294,7 +1629,7 @@ export namespace IOInsights {
      * will be forced to be traced, even if their span filter configuration
      * is set to not enabled.
      *
-     * Defaults to 'false'.
+     * @default false
      */
     forceChildTracing?: boolean;
     /**
@@ -1302,6 +1637,7 @@ export namespace IOInsights {
      */
     minDurationMs?: number;
 
+    /** @ignore */
     getPropagationInfo?: PropagationInfoCallback;
 
     /**
@@ -1321,6 +1657,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.
@@ -1343,17 +1682,10 @@ 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;
-  }
+   * Settings used to control the sampling probability of spans.
+   */
   export interface SamplingSettings {
     /**
      * Span name to determine if span will match this sampling setting entry.
@@ -1511,8 +1843,19 @@ export namespace IOInsights {
    * Logs API.
    */
   export interface LogsManager extends Manager<LogsSettings> {
+    /**
+     * Logs settings.
+     */
+    settings: LogsSettings;
+
+    /**
+     * Publishes an OTEL log record.
+     */
     emit(logRecord: LogRecord): Promise<void> | null;
   }
+  /**
+   * Builder class used to set up Logs module.
+   */
   export interface LogsManagerBuilder {
     build(): LogsManager;
     withLogger(logger: Logger): this;
@@ -1597,7 +1940,7 @@ export namespace IOInsights {
     /**
      * Name of log level counter metric, set to null to disable.
      *
-     * Defaults to 'insights_log_level_count'.
+     * @default insights_log_level_count
      */
     levelCountMetric?: string;
 
@@ -1688,6 +2031,9 @@ export namespace IOInsights {
     enabled?: boolean;
   }
 
+  /**
+   * Level of log entry.
+   */
   export const enum LoggerLogLevel {
     NONE = 0,
     ERROR = 30,
@@ -1698,6 +2044,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;
@@ -1739,11 +2088,28 @@ export namespace IOInsights {
   }
 
   export interface Manager<TSettings> {
+    /**
+     * io.Insights settings.
+     */
     settings: TSettings;
+    /**
+     * Whether or not this instance is started.
+     */
     started: boolean;
-
+    /**
+     * Starts publishing data.
+     */
     start(): Promise<void>;
+    /**
+     * Stops publishing data.
+     */
     stop(): Promise<void>;
+
+    /**
+     * Waits for any pending data to be published, with the option to specify a timeout.
+     *
+     * @param timeoutMs maximum time to wait for export
+     */
     waitForFinalExport(timeoutMs?: number): Promise<void>;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interopio/otel",
-  "version": "0.0.219",
+  "version": "0.0.221",
   "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"