@interopio/otel 0.0.122 → 0.0.123

package/insights.d.ts

@@ -0,0 +1,727 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable max-lines */
+import {
+  Attributes,
+  Context,
+  ContextManager,
+  Sampler,
+  Span,
+  SpanOptions,
+  SpanStatus,
+  TextMapPropagator,
+  TimeInput,
+  TracerProvider,
+} from "@opentelemetry/api";
+import { UserInteractionInstrumentationConfig as UserInteractionInstrumentationConfigBase } from "@opentelemetry/instrumentation-user-interaction";
+import { MetricsSettings } from "./src/metrics/settings/types";
+
+import { LoggerProvider, LogRecord } from "@opentelemetry/api-logs";
+import {
+  OTLPExporterConfigBase,
+  OTLPExporterNodeConfigBase,
+} from "@opentelemetry/otlp-exporter-base";
+import {
+  BufferConfig,
+  SpanExporter,
+  SpanProcessor,
+  TracerConfig,
+} from "@opentelemetry/sdk-trace-base";
+import { DocumentLoadInstrumentationConfig } from "@opentelemetry/instrumentation-document-load";
+import { FetchInstrumentationConfig } from "@opentelemetry/instrumentation-fetch";
+import { XMLHttpRequestInstrumentationConfig } from "@opentelemetry/instrumentation-xml-http-request";
+import {
+  LoggerProviderConfig,
+  LogRecordExporter,
+  LogRecordProcessor,
+} from "@opentelemetry/sdk-logs";
+
+/**
+ * @docname Insights
+ *
+ * @intro
+ * io.Insights API.
+ */
+export namespace IOConnectInsights {
+  export interface API extends Manager<Settings> {
+    /**
+     * io.insights.metrics
+     */
+    metrics: MetricsManager;
+
+    /**
+     * io.insights.traces
+     */
+    traces: TracesManager;
+
+    /**
+     * io.insights.logs
+     */
+    logs: LogsManager;
+  }
+
+  /**
+   * Metrics API.
+   */
+  export interface MetricsManager extends Manager<MetricsSettings> {
+    get(type: MetricType): Metric | undefined;
+    getFromSettings(settings: MetricSettings): Metric | undefined;
+  }
+
+  // /**
+  //  * Traces API.
+  //  */
+  export interface TracesManager extends Manager<TracesSettings> {
+    currentTracingState: TracingState | null;
+
+    /**
+     * Called by the application to signify that its startup has completed
+     * and no further spans should be nested under the startup trace.
+     */
+    startupTraceFinished?: () => void;
+    setStartupTraceFinished(startupTraceFinished: () => void): void;
+
+    withSpan<T>(source: string, callback: WithSpanCallback<T>): T;
+
+    withSpan<T>(
+      source: string,
+      filteringContext: FilteringContext,
+      callback: WithSpanCallback<T>
+    ): T;
+
+    withSpan<T>(
+      source: string,
+      filteringContext: FilteringContext,
+      propagationInfo: PropagationInfo | PropagationInfoCarrier | null,
+      callback: WithSpanCallback<T>
+    ): T;
+
+    withSpan<T>(
+      source: string,
+      filteringContext: FilteringContext,
+      propagationInfo: PropagationInfo | PropagationInfoCarrier | null,
+      options: WithSpanOptions | null,
+      callback: WithSpanCallback<T>
+    ): T;
+  }
+
+  export interface LogsManager extends Manager<LogsSettings> {
+    emit(logRecord: LogRecord): Promise<void> | null;
+  }
+
+  export interface Manager<TSettings> {
+    settings: TSettings;
+    started: boolean;
+
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    waitForFinalExport(timeoutMs?: number): Promise<void>;
+  }
+
+  export interface Settings {
+    /**
+     * Whether library is enabled.
+     * If disabled, API is still usable, but methods are no-ops.
+     */
+    enabled: boolean;
+    /**
+     * Interval in milliseconds to wait for any remaining telemetry data to be exported during shutdown of the platform. This is the maximum awaiting interval and the platform may shutdown before it expires if all telemetry data has already been published.
+     */
+    finalExportTimeoutMs?: number;
+    /**
+     * Interval in milliseconds to wait for any remaining telemetry data to be published by any apps before proceeding with the platform shutdown.
+     */
+    finalExportGracePeriodMs?: number;
+
+    errorlessMode?: boolean;
+    /**
+     * If the library should log the settings used to initialize it.
+     *
+     * @default true
+     */
+    logSettingsOnStartup?: boolean;
+    /**
+     * If failure to initialize library will throw upstream error.
+     */
+    failOnInitError?: boolean;
+    /**
+     * If provided, this value will be added to the metrics and span attributes
+     * and to the span filtering context (see 'filters' in TracesSettings).
+     */
+    platformVersion?: string;
+    /**
+     * If provided, this value will be added to the metrics and traces service.name attribute,
+     * unless an OTEL service object (e.g. TraceProvider) has been provided to the library with
+     * a different setting.
+     */
+    serviceName?: string;
+    /**
+     * If provided, this value will be added to the metrics and traces service.instance.id attribute,
+     * unless an OTEL service object (e.g. TraceProvider) has been provided to the library with
+     * a different setting.
+     */
+    serviceId?: string;
+    /**
+     * If provided, this value will be added to the metrics and traces service.version attribute,
+     * unless an OTEL service object (e.g. TraceProvider) has been provided to the library with
+     * a different setting.
+     * attribute.
+     */
+    serviceVersion?: string;
+    /**
+     * If provided, this value will be added to the metrics and traces user.id attribute,
+     * unless an OTEL service object (e.g. TraceProvider) has been provided to the library with
+     * a different setting.
+     */
+    userId?: string;
+
+    /**
+     * Additional headers to send in HTTP requests, e.g. when using HTTP exporters.
+     */
+    headers?: { [x: string]: string } | (() => { [x: string]: string });
+    /**
+     * Additional attributes to add to observability entities (metrics, spans, log entries) by default.
+     */
+    additionalAttributes?: { [x: string]: unknown } | (() => { [x: string]: unknown });
+    /**
+     * Additional attributes to add to the observability resource definition.
+     */
+    additionalResourceAttributes?: { [x: string]: unknown } | (() => { [x: string]: unknown });
+
+    traces?: TracesSettings;
+    metrics?: MetricsSettings;
+    logs?: LogsSettings;
+  }
+  export interface MetricSettings {
+    enabled: boolean;
+    type: MetricType;
+    name: string;
+    description: string;
+    platformVersion?: string;
+    user?: string;
+    unit?: string;
+    buckets?: number[];
+    baseMetricType?: "histogram" | "gauge";
+    additionalAttributes?: { [key: string]: unknown } | (() => { [key: string]: unknown });
+  }
+
+  export interface Metric {
+    settings: MetricSettings;
+    started: boolean;
+
+    start(): Promise<void>;
+    stop(): Promise<void>;
+  }
+
+  export type MetricType =
+    /*app:       */
+    | "app_count"
+    | "app_cpu"
+    | "app_crash"
+    | "app_duration"
+    | "app_duration_soft"
+    | "app_error"
+    | "app_memory"
+    | "app_started"
+    | "app_startup"
+    | "app_stopped"
+    /*layout:    */
+    | "layout_startup"
+    /*workspace: */
+    | "workspace_count"
+    | "workspace_selected"
+    | "workspace_started"
+    | "workspace_stopped"
+    | "workspace_startup_legacy"
+    // G4E-9759
+    | "workspace_startup"
+    | "workspace_startup_frame"
+    | "workspace_startup_frame_init"
+    | "workspace_startup_frame_page_load"
+    | "workspace_startup_frame_workspace_render"
+    | "workspace_startup_component"
+    | "workspace_startup_apps"
+    /*platform:  */
+    | "platform_error"
+    | "platform_startup"
+    /*system:    */
+    | "system_cpu"
+    | "system_memory"
+    /*custom     */
+    | "custom_gauge"
+    | "custom_observable_gauge"
+    | "custom_observable_counter"
+    | "custom_observable_up_down_counter"
+    | "custom_counter"
+    | "custom_histogram"
+    | "custom_up_down_counter"
+    /*rest:      */
+    | "null";
+
+  interface TracingState {
+    end(): void;
+    /**
+     * If false, this is a placeholder object, and all its methods
+     * are no-ops, with the possible exception of getPropagationInfo()
+     * and injectPropagationInfo()
+     */
+    enabled: boolean;
+    status?: SpanStatus;
+    level: keyof typeof SpanVerbosity;
+    addData(level: SpanVerbosity | keyof typeof SpanVerbosity, data: object): void;
+    source: string;
+    id?: string;
+    traceId?: string;
+    endSpan(): Promise<void>;
+    context?: Context;
+    span?: Span;
+    /**
+     * Gets the propagation info for the current span (see https://www.w3.org/TR/trace-context/#tracestate-field)
+     * @returns the propagation info, if a span is currently active
+     */
+    getPropagationInfo: () => PropagationInfo | null;
+    /**
+     * Sets a hidden property in the object that can be used to restore propagation
+     * information after serialization and deserialization (see withSpan 'propagationInfo' argument
+     * and Traces.extractPropagationInfo() method).
+     * @param carrier the object to populate
+     */
+    injectPropagationInfo: (carrier: PropagationInfoCarrier & object) => void;
+    addEvent: (
+      name: string,
+      attributesOrStartTime?: Attributes | TimeInput,
+      startTime?: TimeInput
+    ) => this;
+    recordException: Span["recordException"];
+    isRecording: Span["isRecording"];
+    updateName: (name: string) => this;
+    spanContext: Span["spanContext"] | (() => undefined);
+  }
+
+  export interface TracesSettings {
+    /**
+     * Name of span hit counter metric, set to null to disable.
+     *
+     * Defaults to 'insights_trace_count'.
+     */
+    countMetric?: string;
+    /**
+     * Name of span duration histogram metric, set to null to disable.
+     *
+     * Defaults to 'insights_trace_duration'.
+     */
+    durationMetric?: string;
+    /**
+     * Name of span result counter metric, set to null to disable.
+     *
+     * Defaults to 'insights_trace_result'.
+     */
+    resultMetric?: string;
+
+    /**
+     * Whether tracing functionality is enabled.
+     * If disabled, API is still usable, but methods are no-ops.
+     *
+     * Defaults to 'false'.
+     */
+    enabled: boolean;
+
+    /**
+     * Array of filter entries used to determine whether
+     * a particular operation will create a tracing span, and
+     * what verbosity level will apply to attributes added
+     * to that span.
+     *
+     * If no matching filter entry is found,
+     * the settings from 'default' are used.
+     */
+    filters?: SpanFilter[];
+    /**
+     * If true, use a predefined list of filters for well-known
+     * platform traces.
+     *
+     * Defaults to true.
+     */
+    useDefaultFilters?: boolean;
+
+    defaultFilters?: SpanFilter[];
+    /**
+     * Array of sampling setting entries used to determine
+     * whether a span will be sampled.
+     *
+     * If no matching sampling setting entry is found,
+     * the settings from 'defaults' are used.
+     */
+    sampling?: SamplingSettings[];
+    /**
+     * Default settings if appropriate entries aren't found
+     * in 'filters' and 'sampling' collections.
+     */
+    defaults?: SpanCreationOptions;
+    /**
+     * If 'true', the library will use the ContextManager provided
+     * by the active OTEL SDK to manage and derive propagation information
+     * to ensure spans created across asynchronous operations are properly
+     * nested.
+     *
+     * Otherwise, use 'Traces.currentTracingState' to set and retrieve propagation
+     * info across asynchronous operations manually.
+     *
+     * See https://opentelemetry.io/docs/languages/js/propagation/ and
+     * https://opentelemetry.io/docs/languages/js/context/#context-manager for
+     * more information.
+     */
+    useOTELContextManager?: boolean;
+    /**
+     * If an OTEL TraceProvider isn't provided to the library,
+     * it will initialize its own.
+     *
+     * If 'url' is specified, TracerProvider will
+     * have an OTLPTraceExporter using this destination URL.
+     */
+    url?: string;
+    /**
+     * Whether the clickstream trace will be enabled.
+     *
+     * @default false
+     */
+    clickstream?: boolean | "nested" | "sibling";
+    /**
+     * Whether the user journey trace will be enabled.
+     *
+     * @default true
+     */
+    userJourney?: boolean | "nested" | "sibling";
+    /**
+     * How long after application startup will any traced operations
+     * automatically be nested under the application startup trace.
+     */
+    startupParentSpanTimeoutMs?: number;
+    /**
+     * Called by the application to signify that its startup has completed
+     * and no further spans should be nested under the startup trace.
+     */
+    startupTraceFinished?: () => void;
+
+    /**
+     * If an OTEL TraceProvider isn't provided to the library,
+     * it will initialize its own.
+     *
+     * If 'url' is specified, TracerProvider will
+     * have an OTLPTraceExporter with 'url' as detination URL and
+     * 'otlpExporterConfig' as additional * config.
+     */
+    otlpExporterConfig?: OTLPExporterNodeConfigBase;
+
+    tracerProviderConfig?: TracerConfig;
+
+  batchSpanProcessorConfig?: BufferConfig;
+
+    autoInstrumentations?: AutoInstrumentationOptions;
+
+    /**
+     * If an OTEL TraceProvider isn't provided to the library,
+     * it will initialize its own.
+     *
+     * If 'console' is 'true', TracerProvider will
+     * have a ConsoleTraceExporter.
+     */
+    console?: boolean;
+
+    /**
+     * Additional headers to send in HTTP requests, e.g. when using HTTP exporters.
+     */
+    headers?: { [x: string]: string } | (() => { [x: string]: string });
+    addResourceAttributesToAttributes?: boolean;
+    /**
+     * Additional attributes to add to observability entities (metrics, spans, log entries) by default.
+     */
+    additionalAttributes?: { [x: string]: unknown } | (() => { [x: string]: unknown });
+    /**
+     * Additional attributes to add to the observability resource definition.
+     */
+    additionalResourceAttributes?: { [x: string]: unknown } | (() => { [x: string]: unknown });
+
+    tracerProvider?: () => TracerProvider;
+    samplerGetter?: (defaultSampler: Sampler) => Sampler;
+    spanProcessors?: () => SpanProcessor[];
+    spanExporters?: () => SpanExporter[];
+    propagator?: () => TextMapPropagator;
+    contextManager?: () => ContextManager;
+    providerRegistrationSettings?: () => {
+      propagator?: TextMapPropagator;
+      contextManager?: ContextManager;
+    };
+  }
+
+  export type WithSpanCallback<T> = (tracingState: TracingState) => T;
+
+  export interface PropagationInfo {
+    traceparent?: string;
+    tracestate?: string;
+    forceTracing?: boolean;
+  }
+  export interface PropagationInfoCarrier {
+    __interopIOTracePropagationInfo?: PropagationInfo;
+  }
+
+  export type PropagationInfoCallback = (
+    source: string,
+    fullFilteringContext: FilteringContext
+  ) => PropagationInfo | null;
+
+  export type FilteringContext = {
+    app?: string;
+    user?: string;
+    host?: string;
+    serviceName?: string;
+    serviceId?: string;
+    platformVersion?: string;
+    serviceVersion?: string;
+    userId?: string;
+  } & Record<string, any>;
+
+  export enum SpanVerbosity {
+    OFF,
+    LOWEST,
+    DIAGNOSTIC,
+    DEBUG,
+    INFO,
+    WARN,
+    HIGHEST,
+  }
+  export interface WithSpanOptions extends Omit<SpanCreationOptions, "sample"> {
+    defaultFilters?: SpanFilter[];
+  }
+
+  export interface SpanCreationOptions {
+    /**
+     * Whether the span will be created or will be a no-op. See 'Filter'.
+     *
+     * Defaults to 'true'.
+     */
+    enabled?: boolean;
+    /**
+     * If a tracing span is disabled by filter, setting this to "true" will stop the propagation
+     * of trace nesting info across it.
+     */
+    stopPropagationIfSpanIsDisabled?: boolean;
+    /**
+     * Default span attribute verbosity level. See 'Filter'.
+     *
+     * Defaults to 'INFO'.
+     */
+    level?: keyof typeof SpanVerbosity;
+    /**
+     * Whether the filtering context will be added as span attributes
+     * to the span. See 'Filter'.
+     *
+     * Defaults to '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'.
+     */
+    autoSetSuccessStatus?: boolean;
+    /**
+     * Default sampling setting/probability. See 'SamplingSettings'.
+     *
+     * Defaults to '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'.
+     */
+    disablePropagation?: boolean;
+    /**
+     * Forces the span to create a new trace.
+     */
+    disableNesting?: boolean;
+
+    log?: boolean;
+
+    logOnDisabledSpans?: boolean;
+
+    /**
+     * Whether the span will be counted in the insights_trace_count metric. See TracesSettings.countMetric.
+     *
+     * Defaults to 'false'.
+     */
+    countMetric?: boolean;
+    /**
+     * Whether the span will be counted in the insights_trace_count metric if disabled. See TracesSettings.countMetric.
+     */
+    countMetricOnDisabledSpans?: boolean;
+    /**
+     * Whether the span will be counted in the insights_trace_result metric. See TracesSettings.resultMetric.
+     *
+     * Defaults to 'false'.
+     */
+    resultMetric?: boolean;
+    /**
+     * Whether the span will be counted in the insights_trace_result metric if disabled. See TracesSettings.resultMetric.
+     */
+    resultMetricOnDisabledSpans?: boolean;
+    /**
+     * Whether the span will be counted in the insights_trace_duration metric. See TracesSettings.durationtMetric.
+     *
+     * Defaults to 'false'.
+     */
+    durationMetric?: boolean;
+    /**
+     * Whether the span will be counted in the insights_trace_count metric if disabled. See TracesSettings.durationMetric.
+     */
+    durationMetricOnDisabledSpans?: boolean;
+    /**
+     * 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'.
+     */
+    canBeRoot?: boolean;
+    /**
+     * How deep addData method should recurse into objects when adding
+     * attributes to spans.
+     *
+     * Defaults to 3.
+     */
+    maxAttributeDepth?: number;
+    /**
+     * If true, any child spans (including nested spans across sytem boundaries)
+     * will be forced to be traced, even if their span filter configuration
+     * is set to not enabled.
+     *
+     * Defaults to 'false'.
+     */
+    forceChildTracing?: boolean;
+    /**
+     * If specified, spans whose duration is lower than this will not be sampled.
+     */
+    minDurationMs?: number;
+
+    getPropagationInfo?: PropagationInfoCallback;
+
+    /**
+     * OTEL span options
+     */
+    otelSpanOptions?: SpanOptions;
+
+    overrideDefaultFilters?: boolean;
+  }
+
+  export interface SpanFilter extends Omit<SpanCreationOptions, "getPropagationInfo"> {
+    /**
+     * Specifies the source string used for matching spans.
+     * Spans match only if their source equals this value, or
+     * if their source starts with '<source>.' (e.g. my.api.foo
+     * starts with my.api).
+     *
+     * Start string with "#" for case-insensitive regex match.
+     */
+    source?: string;
+    /**
+     * Specifies the filtering context values used for matching spans.
+     * Spans match only if all the values in this object match
+     * the context values returned by the context getter callback
+     * and the filteringContext config property.
+     *
+     * Start strings with "#" for case-insensitive regex match.
+     */
+    context?: {
+      [key: string]: string | number | boolean;
+    };
+  }
+  export interface AutoInstrumentationOptions {
+    documentLoad?: boolean | DocumentLoadInstrumentationConfig;
+    userInteraction?: boolean | UserInteractionInstrumentationConfig;
+    fetch?: boolean | FetchInstrumentationConfig;
+    xhr?: boolean | XMLHttpRequestInstrumentationConfig;
+    ignoreObservabilityUrls?: boolean;
+  }
+  export interface SamplingSettings {
+    /**
+     * Span name to determine if span will match this sampling setting entry.
+     * Start string with "#" for case-insensitive regex match
+     */
+    name?: string;
+    /**
+     * Span attributes that determine if span will match this sampling setting entry.
+     * Useful e.g. for checking otel.library.name/otel.scope.name attribute to filter
+     * auto-instrumentated spans.
+     * Start strings with "#" for case-insensitive regex match.
+     */
+    attributes?: { [key: string]: string | number | boolean };
+    /**
+     * Context values that determine if span will match this sampling setting entry.
+     * 'Context' here refers to the object returned from the 'contextGetter' callback at the
+     * time of sampling, not the OTEL context concept.
+     * This is useful for sampling based on the current client environment - current user, application,
+     * server node, time of day, etc.
+     * Start strings with "#" for case-insensitive regex match.
+     */
+    context?: { [key: string]: string | number | boolean };
+    /**
+     * Probability that span will be sampled, based on its traceId
+     * Spans from the same trace will always either all be sampled, or none will,
+     * provided they all have the same sampling probability.
+     * If true: will be sampled
+     * If false: will not be sampled
+     * If number between 0 and 1: has this probability of being sampled.
+     * Precision: 3 decimal digits
+     */
+    sample: number | boolean;
+  }
+
+  export interface UserInteractionInstrumentationConfig
+    extends UserInteractionInstrumentationConfigBase {
+    throttleIntervalMs?: number;
+  }
+
+  export interface LogsSettings {
+    enabled: boolean;
+    url?: string;
+
+    keepAlive?: boolean;
+    exporterSettings?: OTLPExporterConfigBase;
+    batchSettings?: BufferConfig;
+    providerSettings?: LoggerProviderConfig;
+
+    loggerProvider?: LoggerProvider;
+    logProcessors?: LogRecordProcessor[];
+    logExporters?: LogRecordExporter[];
+
+    maxAttributeDepth?: number;
+    filters?: LogFilter[];
+    defaults?: LogOptions;
+
+    /**
+     * Additional headers to send in HTTP requests, e.g. when using HTTP exporters.
+     */
+    headers?: { [x: string]: string } | (() => { [x: string]: string });
+    addResourceAttributesToAttributes?: boolean;
+    /**
+     * Additional attributes to add to observability entities (metrics, spans, log entries) by default.
+     */
+    additionalAttributes?: { [x: string]: unknown } | (() => { [x: string]: unknown });
+    /**
+     * Additional attributes to add to the observability resource definition.
+     */
+    additionalResourceAttributes?: { [x: string]: unknown } | (() => { [x: string]: unknown });
+  }
+
+  export interface LogFilter extends LogOptions {
+    categoryName?: string;
+    severity?: "TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR" | "FATAL";
+    bodyRegex?: string;
+  }
+  export interface LogOptions {
+    allowedAttributes?: string[];
+    hideRegex?: string;
+    enabled?: boolean;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interopio/otel",
-  "version": "0.0.122",
+  "version": "0.0.123",
   "description": "otel library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",