@interopio/otel 0.1.18 → 0.1.20

package/insights.d.ts

@@ -2,6 +2,7 @@
 /* eslint-disable max-lines */
 import { type Layout } from "log4js";
 import {
+  MeterProvider,
   type Attributes,
   type Context,
   type ContextManager,
@@ -34,7 +35,6 @@ import {
   type LogRecordProcessor,
 } from "@opentelemetry/sdk-logs";
 import {
-  type MeterProvider,
   type MeterProviderOptions,
   type MetricReader,
   type PeriodicExportingMetricReaderOptions,
@@ -363,6 +363,12 @@ export namespace IOInsights {
      */
     headers?: { [x: string]: string } | (() => { [x: string]: string });
 
+    /**
+     * Overrides the properties of the top-level `ssoAuth` for the metrics export requests; the ones
+     * that aren't specified here are taken from it.
+     */
+    ssoAuth?: SSOAuthSettings;
+
     /**
      * Whether to add resource attributes to metric data point attributes.
      *
@@ -431,8 +437,8 @@ export namespace IOInsights {
    */
   export interface MetricSettings {
     enabled?: boolean;
-    type: MetricType;
-    name?: string;
+    type?: MetricType;
+    name: string;
     description?: string;
     platformVersion?: string;
     user?: string;
@@ -459,6 +465,28 @@ export namespace IOInsights {
     attributeSettings?: {
       [x: string]: MetricAttributeSettings;
     }
+    /**
+     * Attribute allow list: if specified, only the attributes it names are published with the
+     * values of the metric - everything else is dropped. Every distinct combination of attribute
+     * values is a time series of its own, so this is the way to keep a metric to the dimensions
+     * that are actually needed.
+     *
+     * An entry names an attribute by its flattened (dot-separated) name, or everything nested
+     * under it: `"bounds"` covers `"bounds.left"`. An empty list publishes no attributes at all.
+     *
+     * Can be specified for a single metric (`publishingSettings`), for all metrics
+     * (`defaultPublishingSettings`) and in a metric filter. The list of the most specific level
+     * that has one applies - a matching filter, then the metric, then the defaults; lists are
+     * not merged. Applies to the attributes of the metric values, not to the resource attributes.
+     */
+    allowAttributes?: string[];
+    /**
+     * Attribute drop list: the attributes it names are never published with the values of the
+     * metric. Entries are matched like the ones of `allowAttributes`. The drop lists of all the
+     * levels add up (the defaults, the metric and a matching filter), and an attribute that is
+     * dropped stays dropped even if an allow list names it.
+     */
+    dropAttributes?: string[];
   }
 
   /**
@@ -700,6 +728,12 @@ export namespace IOInsights {
   export interface InstanceErrorHandlerArgs {
     application: string;
     stack?: ApplicationStack;
+    /**
+     * The type (name) of the error, e.g. "TypeError". Published as the `error.type` attribute of
+     * the app_error metric - the same key the error spans use - so keep the set of values small:
+     * every distinct value is a metric series of its own.
+     */
+    errorType?: string;
   }
   /**
    * @ignore
@@ -1057,6 +1091,17 @@ export namespace IOInsights {
      */
     clickstreamMarker?: MarkerSpanCallback;
 
+    /**
+     * Ends every span that is still open, so that it gets exported: a span is only exported once
+     * it has ended, and whatever is still open when the process goes away is lost. The spans are
+     * ended as they stand and marked with an `endedByShutdown` attribute (and
+     * `endedByShutdownReason`, when a reason is given). Called by waitForFinalExport(); call it
+     * directly ahead of any other last flush.
+     *
+     * @returns the number of spans that were ended
+     */
+    endOpenSpans?: (reason?: string) => number;
+
     /**
      * Allows updating the configured filters.
      */
@@ -1315,23 +1360,32 @@ export namespace IOInsights {
     rootPropagationInfo?: PropagationInfo;
 
     /**
-     * Name of span hit counter metric, set to null to disable.
+     * If `true` or a string, span hits are published as a counter metric. If a string value
+     * is specified, this will be the name of the metric. Otherwise, the default
+     * "insights_trace_count" is used. Set to `false` or `null` to disable the metric. Spans opt in
+     * through the `countMetric` span creation option (see 'filters' and 'defaults').
      *
-     * @default insights_trace_count
+     * @default true
      */
-    countMetric?: string;
+    countMetric?: boolean | string | null;
     /**
-     * Name of span duration histogram metric, set to null to disable.
+     * If `true` or a string, span durations are published as a histogram metric. If a string
+     * value is specified, this will be the name of the metric. Otherwise, the default
+     * "insights_trace_duration" is used. Set to `false` or `null` to disable the metric. Spans opt in
+     * through the `durationMetric` span creation option (see 'filters' and 'defaults').
      *
-     * @default insights_trace_duration
+     * @default true
      */
-    durationMetric?: string;
+    durationMetric?: boolean | string | null;
     /**
-     * Name of span result counter metric, set to null to disable.
+     * If `true` or a string, span results (status codes) are published as a counter metric.
+     * If a string value is specified, this will be the name of the metric. Otherwise, the
+     * default "insights_trace_result" is used. Set to `false` or `null` to disable the metric. Spans opt
+     * in through the `resultMetric` span creation option (see 'filters' and 'defaults').
      *
-     * @default insights_trace_result
+     * @default true
      */
-    resultMetric?: string;
+    resultMetric?: boolean | string | null;
 
     /**
      * If `true` (or a configuration object with `enabled: true`), io.Insights
@@ -1677,6 +1731,12 @@ export namespace IOInsights {
      * Additional headers to send in HTTP requests, e.g. when using HTTP exporters.
      */
     headers?: { [x: string]: string } | (() => { [x: string]: string });
+
+    /**
+     * Overrides the properties of the top-level `ssoAuth` for the traces export requests; the ones
+     * that aren't specified here are taken from it.
+     */
+    ssoAuth?: SSOAuthSettings;
     /**
      * Whether to add resource attributes to span attributes.
      *
@@ -1802,6 +1862,9 @@ export namespace IOInsights {
    */
   export interface WithSpanOptions extends Omit<SpanCreationOptions, "sample"> {
     defaultFilters?: SpanFilter[];
+    /**
+     * Used to determine the structure of sequence spans.
+     */
     structure?: "sibling" | "nested";
     /**
      * Overrides the name of the exported OTEL span. The `source` remains the identity
@@ -1864,20 +1927,18 @@ export namespace IOInsights {
     disableNesting?: boolean;
 
     /**
-     * If true, enabled spans will also be published as log entries using the `traceLogger` passed to the
-     * builder instance when building the Traces module.
-     * 
-     * @default false
-     */
-    log?: boolean;
-
-    /**
-     * If true, disabled spans will also be published as log entries using the `traceLogger` passed to the
-     * builder instance when building the Traces module.
-     * 
+     * "Traces as logs": whether the span is also published as a log entry, using the `traceLogger`
+     * passed to the builder instance when building the Traces module. `true` logs the span when it
+     * is enabled; `false` turns the logging off altogether; a `TracesAsLogsOptions` object says
+     * what is logged in more detail.
+     *
+     * The places the option can be set in - a matching filter, the span's own options, the
+     * `defaults` - are combined option by option: `defaults: { log: { includeResourceAttributes: true } }`
+     * with `log: true` in a filter logs that filter's spans with their resource attributes.
+     *
      * @default false
      */
-    logOnDisabledSpans?: boolean;
+    log?: boolean | TracesAsLogsOptions;
 
     /**
      * Whether the span will be counted in the insights_trace_count metric. See TracesSettings.countMetric.
@@ -2247,7 +2308,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    requestFirstByteDurationMetric?: boolean | string;
+    requestFirstByteDurationMetric?: boolean | string | null;
 
     /**
      * If `true` or a string, the end-to-end request time (request issued until the response
@@ -2269,7 +2330,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    requestTotalDurationMetric?: boolean | string;
+    requestTotalDurationMetric?: boolean | string | null;
 
     /**
      * If `true` or a string, the download phase (response headers received until the response
@@ -2284,7 +2345,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    requestBodyDownloadDurationMetric?: boolean | string;
+    requestBodyDownloadDurationMetric?: boolean | string | null;
 
     /**
      * Explicit histogram bucket boundaries for requestFirstByteDurationMetric, in seconds, ascending.
@@ -2328,7 +2389,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    requestBodyDownloadThroughputMetric?: boolean | string;
+    requestBodyDownloadThroughputMetric?: boolean | string | null;
 
     /**
      * Explicit histogram bucket boundaries for requestBodyDownloadThroughputMetric, in
@@ -2345,7 +2406,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    requestBytesMetric?: boolean | string;
+    requestBytesMetric?: boolean | string | null;
 
     /**
      * If `true` or a string, the request size in bytes will be published as a histogram metric.
@@ -2354,7 +2415,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    responseBytesMetric?: boolean | string;
+    responseBytesMetric?: boolean | string | null;
 
     /**
      * Controls only the naming of the fetch/XHR request spans.
@@ -2441,7 +2502,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    inputDelayMetric?: boolean | string;
+    inputDelayMetric?: boolean | string | null;
 
     /**
      * Explicit histogram bucket boundaries for inputDelayMetric, in seconds, ascending.
@@ -2491,7 +2552,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    eventLoopBlockingMetric?: boolean | string;
+    eventLoopBlockingMetric?: boolean | string | null;
 
     /**
      * Explicit histogram bucket boundaries for eventLoopBlockingMetric, in seconds,
@@ -2544,7 +2605,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    dnsDurationMetric?: boolean | string;
+    dnsDurationMetric?: boolean | string | null;
 
     /**
      * Explicit histogram bucket boundaries for dnsDurationMetric, in seconds, ascending.
@@ -2561,7 +2622,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    connectDurationMetric?: boolean | string;
+    connectDurationMetric?: boolean | string | null;
 
     /**
      * Explicit histogram bucket boundaries for connectDurationMetric, in seconds, ascending.
@@ -2578,7 +2639,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    tlsDurationMetric?: boolean | string;
+    tlsDurationMetric?: boolean | string | null;
 
     /**
      * Explicit histogram bucket boundaries for tlsDurationMetric, in seconds, ascending.
@@ -2598,7 +2659,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    firstByteDurationMetric?: boolean | string;
+    firstByteDurationMetric?: boolean | string | null;
 
     /**
      * Explicit histogram bucket boundaries for firstByteDurationMetric, in seconds, ascending.
@@ -2620,7 +2681,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    downloadThroughputMetric?: boolean | string;
+    downloadThroughputMetric?: boolean | string | null;
 
     /**
      * Explicit histogram bucket boundaries for downloadThroughputMetric, in bytes
@@ -2646,7 +2707,55 @@ export namespace IOInsights {
      *
      * @default false
      */
-    cacheStateMetric?: boolean | string;
+    cacheStateMetric?: boolean | string | null;
+  }
+
+  /**
+   * What "traces as logs" (the `log` span creation option) publishes for a span.
+   */
+  export interface TracesAsLogsOptions {
+    /**
+     * If true, the span is published as a log entry when it is enabled. Leave it out to keep what
+     * a less specific place (the span's options, the `defaults`) says.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+
+    /**
+     * If true, the span is published as a log entry when it is disabled. There is no span behind
+     * such an entry: it is logged at the level the span is configured with, with ids of its own
+     * (under the trace and parent it would have had), the attributes it would have carried, and
+     * `insightsSpanDisabled: true` among them.
+     *
+     * @default false
+     */
+    onDisabledSpans?: boolean;
+
+    /**
+     * If true, the log entries published for the span also carry the resource attributes, as
+     * `resource` in the details object that follows the span attributes. They are the same for every
+     * span of a process, so they are left out by default.
+     *
+     * @default false
+     */
+    includeResourceAttributes?: boolean;
+
+    /**
+     * If true, the log entries published for the span also carry its events - among them the
+     * exceptions recorded on it, with their type, message and stack trace, which can make the
+     * entries long.
+     *
+     * @default false
+     */
+    includeEvents?: boolean;
+
+    /**
+     * If true, the log entries published for the span also carry its links to other spans.
+     *
+     * @default false
+     */
+    includeLinks?: boolean;
   }
 
   /**
@@ -2745,7 +2854,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    messagesMetric?: boolean | string;
+    messagesMetric?: boolean | string | null;
 
     /**
      * If `true` or a string, a counter summing WebSocket payload bytes is published
@@ -2754,7 +2863,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    bytesMetric?: boolean | string;
+    bytesMetric?: boolean | string | null;
 
     /**
      * If `true` or a string, the connection establishment time (construction until
@@ -2764,7 +2873,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    connectDurationMetric?: boolean | string;
+    connectDurationMetric?: boolean | string | null;
 
     /**
      * Explicit histogram bucket boundaries for connectDurationMetric, in seconds, ascending.
@@ -2808,7 +2917,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    clsMetric?: boolean | string;
+    clsMetric?: boolean | string | null;
 
     /**
      * Explicit histogram bucket boundaries for clsMetric (unitless score), ascending.
@@ -2826,7 +2935,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    inpMetric?: boolean | string;
+    inpMetric?: boolean | string | null;
 
     /**
      * Explicit histogram bucket boundaries for inpMetric, in seconds, ascending.
@@ -2843,7 +2952,7 @@ export namespace IOInsights {
      *
      * @default false
      */
-    lcpMetric?: boolean | string;
+    lcpMetric?: boolean | string | null;
 
     /**
      * Explicit histogram bucket boundaries for lcpMetric, in seconds, ascending.
@@ -2888,6 +2997,18 @@ export namespace IOInsights {
      * @default 0
      */
     chainLength?: number;
+    /**
+     * Unless `false`, focus spans for windows that sit in a workspace also
+     * carry the workspace context - workspaceId, workspaceName and
+     * workspaceTitle. Only workspace membership is resolvable synchronously;
+     * the id/name/title are fetched from the workspaces frame asynchronously
+     * (two round trips per focus change into a workspace window) and added to
+     * the still-open focus span when they arrive - a focus change racing the
+     * lookup loses only these attributes.
+     *
+     * @default true
+     */
+    includeWorkspaceInfo?: boolean;
   }
 
   /**
@@ -3003,18 +3124,6 @@ export namespace IOInsights {
      * Log record exporters.
      */
     logExporters?: (exporterSettings: OTLPExporterNodeConfigBase, settings: LogsSettings, otelSettings: Settings) => LogRecordExporter[];
-    /**
-     * Name of log level counter metric, set to null to disable.
-     *
-     * @default insights_log_level_count
-     */
-    levelCountMetric?: string;
-
-    // /**
-    //  * How long after application startup will any log entries
-    //  * automatically be associated with the application startup trace.
-    //  */
-    // startupTraceAssociationTimeoutMs?: number;
 
     /**
      * If true, use a predefined list of filters for well-known
@@ -3050,6 +3159,12 @@ export namespace IOInsights {
      */
     headers?: { [x: string]: string } | (() => { [x: string]: string });
 
+    /**
+     * Overrides the properties of the top-level `ssoAuth` for the logs export requests; the ones
+     * that aren't specified here are taken from it.
+     */
+    ssoAuth?: SSOAuthSettings;
+
     /**
      * Whether to add resource attributes to log entry attributes.
      *
@@ -3184,6 +3299,162 @@ export namespace IOInsights {
     waitForFinalExport(timeoutMs?: number): Promise<void>;
   }
 
+  /**
+   * The SSO login information, as far as io.Insights is concerned - see SSOAuthSettings. Whatever
+   * else the login object carries goes into the `auth` header with it (`useAuthHeader`).
+   */
+  export interface SSOAuthInfo {
+    /** The SSO token. */
+    token?: string;
+    /** Headers the SSO login wants sent along. */
+    headers?: { [x: string]: string };
+  }
+
+  /**
+   * Settings for injecting the io.Connect SSO login information into the headers of the
+   * OpenTelemetry export requests.
+   *
+   * The login is asked for on every export (and cached for a while - see `authInfoCacheMs`), so
+   * it doesn't have to be there when io.Insights is initialized, and a refreshed token is picked
+   * up. Exports that happen before anybody has logged in go out without it, unless `waitForLogin`
+   * is set.
+   *
+   * In io.Connect Desktop the login of the platform is used: by the platform itself, and by the
+   * applications that are allowed to have it (`allowAuthInfo` set to `true` in the application
+   * definition) - the rest export without it. It isn't available to Node.js applications. The
+   * io.Connect Gateway gets the login as it is when the gateway is started, which is usually
+   * before anybody has logged in.
+   *
+   * Only applies to the OTLP exporters io.Insights creates itself (from `url`), and to custom
+   * ones that are created from the exporter settings they are handed.
+   */
+  export interface SSOAuthSettings {
+    /**
+     * If `true`, the io.Connect SSO token is sent as the `Authorization` header of the
+     * OpenTelemetry export requests, together with any headers the SSO login provides.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * If `true`, will also use a custom `auth` header to send the entire io.Connect SSO
+     * authorization object as a JSON string, unless `headers` already specifies one.
+     *
+     * @default false
+     */
+    useAuthHeader?: boolean;
+    /**
+     * If `true`, will use the io.Connect SSO token as-is. If `false`, "Bearer " will be prepended
+     * to the token if it lacks the prefix.
+     *
+     * @default true
+     */
+    useRawToken?: boolean;
+    /**
+     * If `true`, an export that happens before anybody has logged in waits for the login - for
+     * up to `waitForLoginTimeoutMs` - instead of going out without it (and most likely being
+     * rejected, and lost). Only until the first login, and only until the first time the wait
+     * times out: from then on exports don't wait.
+     *
+     * The wait is part of the export, so it counts against the export timeout of the batch
+     * processors (`processorSettings.exportTimeoutMillis`, 30 seconds by default), and whatever
+     * is published in the meantime queues up (`processorSettings.maxQueueSize`).
+     *
+     * @default false
+     */
+    waitForLogin?: boolean;
+    /**
+     * How long an export waits for the login when `waitForLogin` is set, in milliseconds.
+     *
+     * @default 5000
+     */
+    waitForLoginTimeoutMs?: number;
+    /**
+     * For how long the login is reused before it is asked for again, in milliseconds. In an
+     * application of io.Connect Desktop asking means a round trip to the platform.
+     *
+     * @default 30000
+     */
+    authInfoCacheMs?: number;
+    /**
+     * How long to wait for the login to be provided, in milliseconds. A login that doesn't come
+     * in time is treated like one that isn't available: the export goes out without it, and the
+     * login isn't asked for again until `authInfoCacheMs` has passed.
+     *
+     * @default 5000
+     */
+    authInfoTimeoutMs?: number;
+    /**
+     * Provides the login. By default the login of io.Connect Desktop is used, when running in it
+     * (`iodesktop.getAuth()`); hosts with a login of their own specify this. Called on every export
+     * that doesn't find the login in the cache; can return `null` while nobody has logged in.
+     */
+    getAuthInfo?: () => SSOAuthInfo | null | undefined | Promise<SSOAuthInfo | null | undefined>;
+  }
+
+  /**
+   * In io.Connect Desktop, the settings of a late io.Insights initialization - see
+   * Settings.lateInit.
+   */
+  export interface LateInitSettings {
+    /**
+     * Whether io.Insights is initialized late. Applies to an object that leaves it out as well.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * At what point of the startup io.Insights is initialized. "post-sso" - the only stage for
+     * now - means right after the SSO authentication has completed, which is after the "pre-sso"
+     * autoStart apps have been started and before the "post-sso" ones are.
+     *
+     * @default "post-sso"
+     */
+    initStage?: "post-sso";
+    /**
+     * How long (in milliseconds) to wait for a "pre-sso" autoStart application to provide
+     * additional OTEL attributes by invoking the T42.Otel.AddAttributes Interop method
+     * (`attributes` and `resourceAttributes`, merged into `additionalAttributes` and
+     * `additionalResourceAttributes`) before io.Insights gets initialized. The method is
+     * registered before the "pre-sso" apps are started, the wait begins once the SSO
+     * authentication has completed, and the first invocation ends it; attributes that arrive
+     * later are ignored. `0` (the default) disables the hand-over: the method is not registered
+     * and nothing is waited for. How long the startup waited is published as the
+     * `otelAttributesWaitMs` attribute of the startup span, and logged.
+     *
+     * @default 0
+     */
+    attributesTimeoutMs?: number;
+  }
+
+  /**
+   * In io.Connect Desktop, the settings of the last chance export of the telemetry describing an
+   * abnormal exit - see Settings.lastChanceExportOnError.
+   */
+  export interface LastChanceExportOnErrorSettings {
+    /**
+     * Whether the telemetry describing an abnormal exit is got out before the platform exits.
+     * Applies to an object that leaves it out as well.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * How long (in milliseconds) to wait for io.Insights to initialize after an error that takes
+     * the platform down before a late initialization, before proceeding with exiting the platform.
+     *
+     * @default 5000
+     */
+    initTimeoutMs?: number;
+    /**
+     * How long (in milliseconds) to wait for the final export of the telemetry before an abnormal
+     * exit of the platform. Used instead of `finalExportTimeoutMs`.
+     *
+     * @default 5000
+     */
+    exportTimeoutMs?: number;
+  }
+
   export interface Settings {
     /**
      * Whether library is enabled.
@@ -3191,6 +3462,69 @@ export namespace IOInsights {
      */
     enabled: boolean;
 
+    /**
+     * In io.Connect Desktop, initializes io.Insights late in the startup - right after the SSO
+     * authentication has completed (see LateInitSettings.initStage) - rather than as early as
+     * possible. The startup telemetry gathered until then is buffered and published once
+     * io.Insights is initialized.
+     *
+     * Early initialization makes the startup trace richer and helps telemetry be published even
+     * in the case of an early startup error; a late one lets a "pre-sso" autoStart application
+     * provide additional OTEL attributes at runtime before io.Insights gets initialized (see
+     * LateInitSettings.attributesTimeoutMs), and lets the platform's own export requests carry
+     * the SSO login from the first one on (see `ssoAuth`).
+     *
+     * `true` switches it on with the default settings; an object also configures it. Has no
+     * effect when io.Insights is disabled.
+     *
+     * @default false
+     */
+    lateInit?: boolean | LateInitSettings;
+
+    /**
+     * In io.Connect Desktop, gets the telemetry describing an abnormal exit out before the
+     * platform exits: a startup error, an unhandled error (crash) at any later point, an exit
+     * with an error code, or a shutdown before the startup has completed (restarts excluded).
+     * The final export waits for up to LastChanceExportOnErrorSettings.exportTimeoutMs instead
+     * of `finalExportTimeoutMs`, and - with a late initialization (`lateInit`) - io.Insights is
+     * initialized after all, within LastChanceExportOnErrorSettings.initTimeoutMs, when the
+     * platform goes down before it was, so the telemetry buffered so far, the error included,
+     * still gets published.
+     *
+     * `true` (the default) uses the default settings; an object configures them; `false`
+     * switches it off - an abnormal exit then waits for the final export as long as a normal one
+     * would, and telemetry buffered before a late initialization is lost.
+     *
+     * @default true
+     */
+    lastChanceExportOnError?: boolean | LastChanceExportOnErrorSettings;
+
+    /**
+     * If `true`, io.Insights publishes through the host application's own
+     * OTEL SDK instead of building providers of its own: the tracer, meter
+     * and logger providers are taken from the OTEL API globals
+     * unconditionally (the globals are never absent - unregistered APIs
+     * return proxy/noop providers, so there is no meaningful fallback).
+     *
+     * Ordering matters: the trace and logs globals are proxies that
+     * late-bind, so signals emitted before the host registers its SDK are
+     * dropped and start flowing once it does; the metrics global is a
+     * snapshot, which io.Insights compensates for by re-resolving it per
+     * meter creation - but meters created before the host registered stay
+     * bound to the noop. Register the host SDK before initializing
+     * io.Insights for full coverage.
+     *
+     * In this mode io.Insights registers nothing: registerGlobalOTELObjects
+     * is effectively ignored, the global propagator is whatever the host
+     * registered (header injection rides it), resource attributes come from
+     * the host's providers (io.Insights resource settings are unused), and
+     * waitForFinalExport is best-effort - flushing on shutdown is the host
+     * SDK's responsibility.
+     *
+     * @default false
+     */
+    useExistingOTELSDK?: boolean;
+
     /**
      * Whether the library should register its own instances of the OTEL SDK global objects,
      * e.g. MeterProvider. This is useful for controlling which instance of the SDK is used,
@@ -3246,28 +3580,19 @@ export namespace IOInsights {
     applicationName?: string;
 
     /**
-     * Settings for injecting the io.Connect SSO login information into OpenTelemetry export requests when the platform is configured to use the Electron networking stack.
+     * In io.Connect Desktop: if `true`, the platform will add CPU, memory, and OS information
+     * to the resource attributes of the published signals.
+     *
+     * @default false
      */
-    ssoAuth?: {
-      /**
-       * If `true`, will instruct the platform to use the io.Connect SSO login information when making OpenTelemetry export requests. This only applies to OpenTelemetry exports performed after SSO completes.
-       *
-       * @default false
-       */
-      enabled?: boolean;
-      /**
-       * If `true`, will use a custom `auth` header to send the entire io.Connect SSO authorization object as a JSON string.
-       *
-       * @default false
-       */
-      useAuthHeader?: boolean;
-      /**
-       * If `true`, will use the io.Connect SSO token as-is. If `false`, "Bearer " will be prepended to the token if it lacks the prefix.
-       *
-       * @default true
-       */
-      useRawToken?: boolean;
-    };
+    addHardwareDataToAttributes?: boolean;
+
+    /**
+     * Settings for injecting the io.Connect SSO login information into the headers of the
+     * OpenTelemetry export requests. Can be overridden for the traces, the metrics and the logs
+     * in their own settings. See SSOAuthSettings.
+     */
+    ssoAuth?: SSOAuthSettings;
 
     /**
      * Suppress double initialization warnings from the OTEL SDK.
@@ -3277,13 +3602,20 @@ export namespace IOInsights {
     suppressDoubleInitializationWarnings?: 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.
+     * 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.
+     *
+     * If `0`, the final export is fire-and-forget: it is started - which also ends, and thereby
+     * publishes, the spans that are still open - but the shutdown doesn't wait for it, so only
+     * what makes it out before the process exits is published. On an abnormal exit of the
+     * platform, `lastChanceExportOnError.exportTimeoutMs` is used instead.
+     *
+     * @default 0
      */
     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;
 
     /**
      * If `true`, the library will swallow all errors, instead of propagating them.