Configuration

io.Insights comes as a built-in feature of io.Connect Desktop. The default OpenTelemetry signals it publishes can be enabled, disabled or customized based on your specific business scenarios.

⚠️ Note that the following sections describe how to configure the main features of io.Insights in io.Connect Desktop. All available settings for configuring io.Insights are described in the otel.json configuration schema.

io.Insights is disabled by default. To enable io.Insights and configure its features in io.Connect Desktop, use the "otel" top-level key in the system.json system configuration file of io.Connect Desktop located in the <installation_location>/config folder:

{
    "otel": {
        "enabled": true,
        "metrics": {
            "enabled": true,
            "url": "http://localhost:4242/my-metrics-collector",
            "publishInterval": 60000,
            "platformMetricsEnabled": true,
            "metrics": [
                {
                   "type": "app_crash",
                   "enabled": false
                }
            ]
        }
    }
}

The "otel" object has the following properties:

Property	Type	Description
"addHardwareDataToAttributes"	boolean	If true, the platform will add CPU, memory and OS information to the resource attributes of the published signals. Defaults to false. Available since io.Connect Desktop 10.3.
"additionalAttributes"	object	Additional properties to publish as part of each OpenTelemetry signal, specified as key/value pairs. You can use environment variables as values. Environment variables must start and end with a percent sign (e.g., %MyEnvVar%), and can contain a fallback value (e.g., %MyEnvVar?DefaultValue%). Available since io.Connect Desktop 9.9.
"additionalResourceAttributes"	object	Additional properties to publish as part of the OpenTelemetry resource definition for all OpenTelemetry signals, specified as key/value pairs. You can use environment variables as values. Environment variables must start and end with a percent sign (e.g., %MyEnvVar%), and can contain a fallback value (e.g., %MyEnvVar?DefaultValue%). Available since io.Connect Desktop 9.9.
"addResourceAttributesToAttributes"	boolean	If true, all resource-level attributes will be copied into every signal data point (metric data points, spans, log records). Defaults to false. Signal-level settings take precedence over this value. Available since io.Connect Desktop 10.1.
"applicationName"	string	App name to use in the published telemetry data. If not provided, defaults to the app name assigned by io.Connect Desktop. Available since io.Connect Desktop 10.1.
"enabled"	boolean	Required. If true, will enable publishing of telemetry data. Defaults to false.
"errorlessMode"	boolean	If true, the library will silently swallow all errors instead of propagating them. Useful in production environments where telemetry failures should not affect the platform. Defaults to false. Available since io.Connect Desktop 10.1.
"failOnInitError"	boolean	If true, a failure to initialize the library will propagate as an error to the caller. If false (default), the library will fail silently and operate in no-op mode. Available since io.Connect Desktop 10.1.
"finalExportGracePeriodMs"	number	Interval in milliseconds to wait for any remaining telemetry data to be published by any apps before proceeding with the platform shutdown. Defaults to 0. Available since io.Connect Desktop 9.8.
"finalExportTimeoutMs"	number	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 shut down before it expires if all telemetry data has already been published. Defaults to 0. Available since io.Connect Desktop 9.8.
"headers"	object	Additional headers to send with all HTTP export requests across all signals (metrics, traces, logs), specified as key/value pairs where values are strings. Signal-level "headers" settings will be merged with and take precedence over this value. Available since io.Connect Desktop 10.1.
"logs"	object	Settings for publishing logs. Available since io.Connect Desktop 10.1.
"logSettingsOnStartup"	boolean	If true (default), the library will log the effective settings used to initialize it. Available since io.Connect Desktop 10.1.
"metrics"	object	Settings for publishing metrics.
"platformVersion"	string	If provided, this value will be added to the metric and span attributes and to the span filtering context. If not provided, defaults to the platform version. Available since io.Connect Desktop 10.1.
"requestSettings"	boolean	For Node.js apps: if true (default), the app will request the io.Insights settings from the platform when initializing. Available since io.Connect Desktop 10.1.
"serviceId"	string	Value to use for the service.instance.id OpenTelemetry resource attribute. If not provided, defaults to the platform-generated instance identifier. Available since io.Connect Desktop 10.1.
"serviceName"	string	Value to use for the service.name OpenTelemetry resource attribute. If not provided, defaults to the platform name. Available since io.Connect Desktop 10.1.
"serviceVersion"	string	Value to use for the service.version OpenTelemetry resource attribute. If not provided, defaults to the platform version. Available since io.Connect Desktop 10.1.
"suppressDoubleInitializationWarnings"	boolean	If true, warnings from the OpenTelemetry SDK about double initialization will be suppressed. Defaults to false. Available since io.Connect Desktop 10.1.
"traces"	object	Settings for publishing traces. Available since io.Connect Desktop 10.1.
"userId"	string	Value to use for the user.id (and user) OpenTelemetry resource attribute. If not provided, defaults to the authenticated user identity. Available since io.Connect Desktop 10.1.
"useSSOAuth"	boolean	If true, the platform SSO login information will be used when making requests to the OpenTelemetry collector. When enabled, the Authorization header will be set using the SSO token, and any authentication headers will be appended to the export requests. Defaults to false. Signal-level "useSSOAuth" settings take precedence over this value. Available since io.Connect Desktop 10.1.
"useSSOAuthRawToken"	boolean	Used when the SSO login information contains a token property. If true, the token will be used as-is. If false (default), the token may be prepended with "Bearer " if it doesn't already contain an Authorization type prefix. Signal-level settings take precedence. Available since io.Connect Desktop 10.1.

Per-App Configuration

Available since io.Connect Desktop 10.5

To override the io.Insights platform settings for a specific app, use the "insights" top-level key in the app definition. It accepts the same properties as the "otel" top-level key in the system.json file of io.Connect Desktop. The app settings are merged with the platform settings and take precedence over them. The array entries defined in the app settings (e.g., span filters or metric filters) are placed before the ones defined in the platform settings, so the app filters will be matched first.

The following example demonstrates how to set a custom service name and an additional attribute for an app, and enable the Click Stream trace only for it:

{
    "name": "my-app",
    "insights": {
        "serviceName": "my-app-service",
        "additionalAttributes": {
            "team": "trading"
        },
        "traces": {
            "clickstream": true
        }
    }
}

To provide custom settings for publishing metrics, use the "metrics" property of the "otel" object.

The "metrics" object has the following properties:

Property	Type	Description
"additionalAttributes"	object	Additional properties to publish as part of each metric, specified as key/value pairs. You can use environment variables as values. Environment variables must start and end with a percent sign (e.g., %MyEnvVar%), and can contain a fallback value (e.g., %MyEnvVar?DefaultValue%). Available since io.Connect Desktop 9.9.
"additionalResourceAttributes"	object	Additional properties to publish as part of the OpenTelemetry resource definition for metrics signals, specified as key/value pairs. You can use environment variables as values. Environment variables must start and end with a percent sign (e.g., %MyEnvVar%), and can contain a fallback value (e.g., %MyEnvVar?DefaultValue%). Available since io.Connect Desktop 9.9.
"addResourceAttributesToAttributes"	boolean	Whether to add resource attributes to metric data point attributes. Defaults to false. Signal-level setting takes precedence over the top-level one. Available since io.Connect Desktop 10.1.
"compression"	"none" | "gzip"	Compression algorithm to use for metric export requests. Available since io.Connect Desktop 10.1.
"concurrencyLimit"	number	Maximum number of concurrent metric export requests. Available since io.Connect Desktop 10.1.
"defaultPublishingSettings"	object	Default publishing settings applied to all metrics that don't define their own "publishingSettings". Accepts the same properties as the "publishingSettings" property of a metric entry (see Platform Metrics). Available since io.Connect Desktop 10.1.
"enabled"	boolean	If true, will enable publishing metrics. Defaults to false.
"exporterSettings"	object	Options to use when creating the OTLP metric exporter. Provides fine-grained control over the HTTP transport ("headers", "url", "concurrencyLimit", "timeoutMillis", "keepAlive", "compression", "httpAgentOptions") and accepts a "temporalityPreference" property (0 = DELTA, 1 = CUMULATIVE, 2 = LOWMEMORY). Available since io.Connect Desktop 10.1.
"filters"	object[]	Array of filter rules to determine which metrics should be collected and exported. Each entry matches metrics by "name" and "type", and can enable or disable them individually. Available since io.Connect Desktop 10.1.
"headers"	object	Additional headers to send with metric export HTTP requests, specified as key/value pairs where values are strings. Merged with and takes precedence over the top-level "headers" setting. Available since io.Connect Desktop 10.1.
"hostname"	string	Hostname to include in exported metrics. Available since io.Connect Desktop 10.1.
"keepAlive"	boolean	If true, will use HTTP keep-alive connections for metric exports. Available since io.Connect Desktop 10.1.
"maxAttributeDepth"	number	How deep the library should recurse into objects when adding attributes to metrics. Defaults to 5. Available since io.Connect Desktop 10.1.
"meter"	object	Partial meter configuration options. Available since io.Connect Desktop 10.1.
"meterProviderSettings"	object	Options to use when creating the OpenTelemetry MeterProvider for exporting metrics. Available since io.Connect Desktop 10.1.
"metrics"	object[]	Settings for the default platform metrics. Defaults to an array of the default platform metrics.
"platformMetricsEnabled"	boolean	If true (default), will enable publishing of all default platform metrics.
"publishInterval"	number	Interval in milliseconds at which to publish the generated metrics. Defaults to 30000.
"readerSettings"	object	Options to use when creating the OpenTelemetry PeriodicExportingMetricReader for exporting metrics. Available since io.Connect Desktop 10.1.
"timeoutMillis"	number	Maximum time in milliseconds the OTLP exporter will wait for each batch export. Defaults to 10000. Available since io.Connect Desktop 10.1.
"url"	string	URL pointing to an OpenTelemetry metrics collector.
"useDefaultFilters"	boolean	If true (default), the predefined default filters for platform metrics will be applied. Available since io.Connect Desktop 10.1.
"useSSOAuth"	boolean	If true, the platform SSO login information will be used when making metric export requests. Takes precedence over the top-level "useSSOAuth" setting. Defaults to false. Available since io.Connect Desktop 10.1.
"useSSOAuthRawToken"	boolean	Used when the SSO login information contains a token property. If true (default), the token will be used as-is. If false, the token may be prepended with "Bearer ". Takes precedence over the top-level setting. Available since io.Connect Desktop 10.1.

The following sections describe the configuration settings for the the main features related to publishing metrics with io.Insights.

ℹ️ For details on all available settings for configuring io.Insights, see the otel.json configuration schema.

Platform Metrics

You can enable, disable, or override the settings for the default platform metrics published by io.Insights by using a combination of the "platformMetricsEnabled" and the "metrics" properties of the "metrics" object. For instance, you can enable all default platform metrics by setting the "platformMetricsEnabled" to true, and then disable or customize individual metrics by specifying the predefined metric type in the "metrics" array:

{
    "otel": {
        "enabled": true,
        "metrics": {
            "url": "http://localhost:4242/my-metrics-collector",
            "platformMetricsEnabled": true,
            "metrics": [
                // Disabling a default metric.
                {
                   "type": "app_error",
                   "enabled": false
                },
                // Overriding the default settings for a predefined metric.
                {
                    "type": "layout_startup",
                    "name": "Global Layout Startup",
                    "description": "The time it takes to load a Global Layout.",
                    "buckets": [
                        10000,
                        15000,
                        20000
                    ]
                }
            ]
        }
    }
}

Each object in the "metrics" array has the following properties:

Property	Type	Description
"additionalAttributes"	object	Additional attributes to add to this specific metric, specified as key/value pairs. Available since io.Connect Desktop 9.9.
"baseMetricType"	"histogram" | "gauge"	Override the base OpenTelemetry instrument type for this metric. This allows publishing the same predefined metric in different forms simultaneously (e.g., as both a histogram and a gauge with different names). Available since io.Connect Desktop 10.1.
"buckets"	number[]	Specify explicit bucket boundaries for the OpenTelemetry SDK if the metric is a Histogram.
"description"	string	Required. Description for the metric.
"enabled"	boolean	Required. If true (default), will enable publishing the metric.
"name"	string	Required. Name for the metric. May be used in visualization tools.
"platformVersion"	string	If provided, this value will be added to the metric attributes. Available since io.Connect Desktop 10.1.
"publishingSettings"	object	Controls the publishing of this metric - the sampling probability and the publishing of individual attributes. See Metric Publishing Settings. Available since io.Connect Desktop 10.1.
"type"	string	Required. Type of the predefined metric.
"unit"	string	The unit of measurement for this metric (e.g., "ms", "bytes"). Available since io.Connect Desktop 10.1.
"user"	string	If provided, this value will be added to the metric attributes. Available since io.Connect Desktop 10.1.

The "type" property accepts the following values describing a predefined metric type:

Value
"app_count"
"app_cpu"
"app_crash"
"app_duration"
"app_duration_soft"
"app_error"
"app_memory"
"app_started"
"app_startup"
"app_stopped"
"custom_counter"
"custom_gauge"
"custom_histogram"
"custom_observable_counter"
"custom_observable_gauge"
"custom_observable_up_down_counter"
"custom_up_down_counter"
"layout_startup"
"platform_error"
"platform_startup"
"system_cpu"
"system_memory"
"workspace_count"
"workspace_selected"
"workspace_started"
"workspace_startup"
"workspace_startup_apps"
"workspace_startup_component"
"workspace_startup_frame"
"workspace_startup_frame_init"
"workspace_startup_frame_page_load"
"workspace_startup_frame_workspace_render"
"workspace_stopped"

Metric Filters

You can use the "filters" property of the "metrics" object to control which metrics are collected and exported. Each filter rule matches metrics by "name" and "type", and can enable or disable them. The "useDefaultFilters" property controls whether the built-in default filters for platform metrics are applied.

The following example demonstrates how to disable a specific metric by name using a filter:

{
    "otel": {
        "enabled": true,
        "metrics": {
            "enabled": true,
            "url": "http://localhost:4242/my-metrics-collector",
            "useDefaultFilters": true,
            "filters": [
                {
                    "name": "app_cpu",
                    "type": "app_cpu",
                    "enabled": false
                }
            ]
        }
    }
}

Each object in the "filters" array has the following properties:

Property	Type	Description
"attributes"	object	Attributes used for matching metrics. Not all metrics have all attribute values. For details on the attributes published by each metric, see the Signals > Metrics > io.Connect Desktop section.
"attributeSettings"	object	Controls the publishing of specific attributes of the matched metric. See Metric Publishing Settings. Available since io.Connect Desktop 10.1.
"enabled"	boolean	If true, the matching metric will be collected. If false, the matching metric will be suppressed.
"name"	string	Required. Name of the metric to match.
"overrideDefaultFilters"	boolean	If true, this filter rule will be matched before any default filters provided by the platform. Defaults to false.
"sample"	boolean | number	Sampling setting for the matched metric. If true (default), the metric will be published. If false, it won't be published. If a number between 0 and 1, it represents the publishing probability. Available since io.Connect Desktop 10.1.
"type"	string	Required. Type of the metric to match. Must be one of the predefined metric types (see Platform Metrics).

Default Metric Filters

When "useDefaultFilters" is set to true (the default), the platform applies a predefined set of metric filters that reduce the default verbosity of the published metric data. These default filters are evaluated before any user-defined filters (unless a user filter has "overrideDefaultFilters" set to true).

Currently, the default metric filters disable all workspace_startup_xxx metrics when the complexLoad attribute is true, preventing complex Workspace load scenarios from inflating the metric data:

[
    {
        "name": "workspace_startup",
        "type": "workspace_startup",
        "attributes": { "complexLoad": true },
        "enabled": false
    },
    {
        "name": "workspace_startup_frame",
        "type": "workspace_startup_frame",
        "attributes": { "complexLoad": true },
        "enabled": false
    },
    {
        "name": "workspace_startup_frame_init",
        "type": "workspace_startup_frame_init",
        "attributes": { "complexLoad": true },
        "enabled": false
    },
    {
        "name": "workspace_startup_frame_page_load",
        "type": "workspace_startup_frame_page_load",
        "attributes": { "complexLoad": true },
        "enabled": false
    },
    {
        "name": "workspace_startup_frame_workspace_render",
        "type": "workspace_startup_frame_workspace_render",
        "attributes": { "complexLoad": true },
        "enabled": false
    },
    {
        "name": "workspace_startup_component",
        "type": "workspace_startup_component",
        "attributes": { "complexLoad": true },
        "enabled": false
    },
    {
        "name": "workspace_startup_apps",
        "type": "workspace_startup_apps",
        "attributes": { "complexLoad": true },
        "enabled": false
    }
]

To override a specific default filter, add a filter entry with the same "name" and "type" in the "filters" array and set "overrideDefaultFilters" to true:

{
    "otel": {
        "enabled": true,
        "metrics": {
            "enabled": true,
            "url": "http://localhost:4318/v1/metrics",
            "useDefaultFilters": true,
            "filters": [
                {
                    "name": "workspace_startup",
                    "type": "workspace_startup",
                    "overrideDefaultFilters": true,
                    "enabled": true
                }
            ]
        }
    }
}

To disable all default metric filters entirely, set "useDefaultFilters" to false.

Metric Publishing Settings

Available since io.Connect Desktop 10.1

Publishing settings control the sampling probability of a metric and the publishing of its individual attributes. You can specify them per metric using the "publishingSettings" property of a metric entry, per filter rule using the "attributeSettings" and "sample" properties of a filter entry, or for all metrics at once using the "defaultPublishingSettings" property of the "metrics" object.

A publishing settings object has the following properties:

Property	Type	Description
"attributeSettings"	object	Controls the publishing of specific attributes, specified as key/value pairs where the key is the attribute name and the value is an object with a "reduceModality" property. Available since io.Connect Desktop 10.1.
"sample"	boolean | number	Sampling probability for the metric. If true (default), the metric will be published. If false, it won't be published. If a number between 0 and 1, it represents the publishing probability. Available since io.Connect Desktop 10.1.

Each object in the "attributeSettings" map has the following properties:

Property	Type	Description
"reduceModality"	number	If specified, the attribute value will be hashed and truncated to this length in order to reduce the number of unique values published for this attribute. Set to 0 to drop the attribute entirely. Set to -1 to override any defaults.

In most metrics backends, every unique combination of attribute values is stored as a separate time series, so attributes with a high number of possible values (e.g., "service.instance.id", "applicationInstance", "user", "machineName") can significantly increase your storage requirements. Reducing the modality of such an attribute lowers the number of time series at the cost of no longer being able to correlate events by its exact value.

The following example demonstrates how to sample half of the "app_cpu" measurements, reduce the modality of the "applicationInstance" attribute and drop the "machineName" attribute entirely:

{
    "otel": {
        "enabled": true,
        "metrics": {
            "enabled": true,
            "url": "http://localhost:4318/v1/metrics",
            "defaultPublishingSettings": {
                "attributeSettings": {
                    "machineName": {
                        "reduceModality": 0
                    }
                }
            },
            "metrics": [
                {
                    "type": "app_cpu",
                    "name": "app_cpu",
                    "description": "CPU usage per app.",
                    "enabled": true,
                    "publishingSettings": {
                        "sample": 0.5,
                        "attributeSettings": {
                            "applicationInstance": {
                                "reduceModality": 8
                            }
                        }
                    }
                }
            ]
        }
    }
}

Side-by-Side Publishing

Available since io.Connect Desktop 10.1

You can publish the same predefined metric in different forms simultaneously by defining multiple entries with the same "type" but different "name" values in the "metrics" array, and using the "baseMetricType" property to override the base OpenTelemetry instrument type of each entry.

The following example demonstrates how to publish the "platform_startup" metric both as a Histogram (for distribution analysis) and as a Gauge (for last-value dashboards), each with its own name and independent settings:

{
    "otel": {
        "enabled": true,
        "metrics": {
            "enabled": true,
            "url": "http://localhost:4318/v1/metrics",
            "metrics": [
                {
                    "type": "platform_startup",
                    "name": "platform_startup_histogram",
                    "description": "Distribution of the platform startup time.",
                    "enabled": true,
                    "baseMetricType": "histogram",
                    "unit": "ms",
                    "buckets": [
                        5000,
                        10000,
                        20000
                    ]
                },
                {
                    "type": "platform_startup",
                    "name": "platform_startup_last",
                    "description": "Last recorded platform startup time.",
                    "enabled": true,
                    "baseMetricType": "gauge",
                    "unit": "ms"
                }
            ]
        }
    }
}

Exporter Settings

The metrics exporter can be fine-tuned using the "compression", "timeoutMillis", "concurrencyLimit", and "keepAlive" properties of the "metrics" object. These settings control the HTTP transport behavior of the OTLP metrics exporter.

The following example demonstrates how to configure the metrics exporter with GZIP compression and a custom timeout:

{
    "otel": {
        "enabled": true,
        "metrics": {
            "enabled": true,
            "url": "http://localhost:4318/v1/metrics",
            "publishInterval": 60000,
            "compression": "gzip",
            "timeoutMillis": 15000,
            "keepAlive": true,
            "concurrencyLimit": 5
        }
    }
}

For advanced scenarios, you can pass options directly to the underlying OpenTelemetry SDK objects using the "exporterSettings", "meterProviderSettings" and "readerSettings" properties of the "metrics" object. The "exporterSettings" property also accepts a "temporalityPreference" value (0 = DELTA, 1 = CUMULATIVE, 2 = LOWMEMORY) which controls the preferred aggregation temporality of the exported metrics.

Resource & Metric Attributes

You can customize the OpenTelemetry resource-level attributes and the metric data point attributes using the "additionalResourceAttributes" and "additionalAttributes" properties of the "metrics" object. These are merged with (and take precedence over) the respective top-level settings.

If you set "addResourceAttributesToAttributes" to true, all resource-level attributes will be copied into every metric data point, making them available for grouping and filtering in your metrics backend.

ℹ️ For details on the common resource-level attributes published by io.Connect Desktop, see the Signals > Overview > Common Resource Attributes section.

The following example demonstrates how to add custom resource and data point attributes to metrics, and how to merge resource attributes into data points:

{
    "otel": {
        "enabled": true,
        "metrics": {
            "enabled": true,
            "url": "http://localhost:4318/v1/metrics",
            "additionalResourceAttributes": {
                "deployment.environment": "production",
                "team": "platform-engineering"
            },
            "additionalAttributes": {
                "datacenter": "%DATACENTER_NAME%"
            },
            "addResourceAttributesToAttributes": true
        }
    }
}

Available since io.Connect Desktop 10.1

To provide custom settings for publishing traces, use the "traces" property of the "otel" object.

The "traces" object has the following properties:

Property	Type	Description
"additionalAttributes"	object	Additional span attributes to publish as part of each span, specified as key/value pairs. You can use environment variables as values. Environment variables must start and end with a percent sign (e.g., %MyEnvVar%), and can contain a fallback value (e.g., %MyEnvVar?DefaultValue%).
"additionalResourceAttributes"	object	Additional attributes to publish as part of the OpenTelemetry resource definition for trace signals, specified as key/value pairs. You can use environment variables as values. Environment variables must start and end with a percent sign (e.g., %MyEnvVar%), and can contain a fallback value (e.g., %MyEnvVar?DefaultValue%).
"addResourceAttributesToAttributes"	boolean	Whether to add resource attributes to span attributes. Defaults to false. Signal-level setting takes precedence over the top-level one.
"clickstream"	boolean | string | object	Whether the Click Stream trace will be enabled. Can be set to true/false, to "nested" or "sibling" to control the span structure, or to an object for full configuration. Defaults to false. See Click Stream.
"closeTrace"	boolean	If true, the app will create a span named interopio.api.application.close when it's being closed. This requires close handlers to be enabled in the app configuration. Defaults to false.
"compression"	"none" | "gzip"	Compression algorithm to use for trace export requests.
"concurrencyLimit"	number	Maximum number of concurrent trace export requests.
"console"	boolean	If true, a ConsoleTraceExporter will be added, which logs all spans to the console. Useful for debugging. Defaults to false.
"countMetric"	string | null	Name of the span hit counter metric used for Traces as Metrics. Set to null to disable. Defaults to "insights_trace_count".
"defaults"	object	Default span creation options used as a fallback when no matching filter or sampling rule is found.
"durationMetric"	string | null	Name of the span duration histogram metric used for Traces as Metrics. Set to null to disable. Defaults to "insights_trace_duration".
"enabled"	boolean	If true, will enable publishing traces. Defaults to false.
"exporterSettings"	object	Options to use when creating the OTLP trace exporter. Provides fine-grained control over the HTTP transport ("headers", "url", "concurrencyLimit", "timeoutMillis", "keepAlive", "compression", "httpAgentOptions").
"filters"	object[]	Array of filter entries used to determine whether a particular operation will create a tracing span.
"headers"	object	Additional headers to send with trace export HTTP requests, specified as key/value pairs where values are strings. Merged with and takes precedence over the top-level "headers" setting.
"hybridContextMode"	boolean	If true, the library will use both the ContextManager provided by the OpenTelemetry SDK and the Traces.currentTracingState property to resolve the current context. Defaults to false. See Context Management.
"instrumentAppStartup"	boolean	If true (default), io.Insights will trace the app startup automatically. See Auto Instrumentation. Available since io.Connect Desktop 10.5.
"instrumentErrors"	boolean | object	If true, uncaught errors and unhandled Promise rejections will be published as spans. Defaults to false. See Auto Instrumentation. Available since io.Connect Desktop 10.5.
"instrumentEventLoop"	boolean | object	If true, slow input events and long tasks blocking the main thread will be published as spans. Defaults to false. See Auto Instrumentation. Available since io.Connect Desktop 10.5.
"instrumentNavigation"	boolean	If true, in-page navigations will be published as spans. Defaults to false. Available since io.Connect Desktop 10.5.
"instrumentRequests"	boolean | object	If true, io.Insights will instrument and trace XMLHttpRequest and fetch() requests automatically. Defaults to false. See Auto Instrumentation.
"instrumentResources"	boolean | object	If true, resource loads (scripts, stylesheets, images, fonts) will be published as spans. Defaults to false. See Auto Instrumentation. Available since io.Connect Desktop 10.5.
"instrumentWebSockets"	boolean | object	If true, WebSocket connections will be published as spans. Defaults to false. See Auto Instrumentation. Available since io.Connect Desktop 10.5.
"instrumentWebVitals"	boolean | object	If true, the CLS, INP, and LCP Web Vitals for the session will be published as spans. Defaults to false. See Auto Instrumentation. Available since io.Connect Desktop 10.5.
"keepAlive"	boolean	If true (default), will use HTTP keep-alive connections for trace exports.
"parentNameLimit"	number	Maximum length for parent operation names in span hierarchies.
"processorSettings"	object	Options to use when creating the batch span processor. Accepts "maxExportBatchSize" (defaults to 512), "scheduledDelayMillis" (defaults to 5000), "exportTimeoutMillis" (defaults to 30000) and "maxQueueSize" (defaults to 2048).
"publishInterval"	number	Interval in milliseconds between trace export batches.
"resultMetric"	string | null	Name of the span result counter metric used for Traces as Metrics. Set to null to disable. Defaults to "insights_trace_result".
"sampling"	object[]	Array of sampling setting entries used to determine whether a span will be sampled (exported).
"startupParentSpanTimeoutMs"	number	How long in milliseconds after app startup any traced operations will automatically be nested under the app startup trace. Defaults to 3000.
"timeoutMillis"	number	Maximum time in milliseconds the OTLP exporter will wait for each batch export. Defaults to 10000.
"tracerProviderSettings"	object	Options to use when creating the OpenTelemetry TracerProvider. Accepts "sampler", "generalLimits", "spanLimits", "resource", "idGenerator", "forceFlushTimeoutMillis" and "spanProcessors".
"url"	string	URL pointing to an OpenTelemetry traces collector.
"useDefaultFilters"	boolean	If true (default), a predefined list of filters for well-known platform traces will be applied.
"useOTELContextManager"	boolean	If true, the library will use the ContextManager provided by the active OpenTelemetry SDK to manage propagation information across asynchronous operations. Defaults to false. See Context Management.
"userJourney"	boolean | string | object	If true (default), the User Journey trace will be enabled. Can be set to true/false, to "nested" or "sibling" to control the span structure, or to an object for full configuration.
"useSSOAuth"	boolean	If true, the platform SSO login information will be used when making trace export requests. Takes precedence over the top-level "useSSOAuth" setting. Defaults to false.
"useSSOAuthRawToken"	boolean	Used when the SSO login information contains a token property. If true (default), the token will be used as-is. If false, the token may be prepended with "Bearer ". Takes precedence over the top-level setting.

The following sections describe the configuration settings for the main features related to publishing traces with io.Insights.

ℹ️ For details on all available settings for configuring io.Insights, see the otel.json configuration schema.

Span Filters

You can use the "filters" property of the "traces" object to control which operations create tracing spans. Each filter entry matches spans by their "source" (span name/operation identifier) and optionally by "context" values. When a traced operation is initiated, the filter list is searched for a matching entry, and the settings from that entry are applied. If no match is found, the settings from "defaults" are used.

The following example demonstrates how to disable tracing for a specific Interop method invocation and customize settings for a specific app start by using the "context" property to narrow down the filter matching:

{
    "otel": {
        "enabled": true,
        "traces": {
            "enabled": true,
            "url": "http://localhost:4318/v1/traces",
            "useDefaultFilters": true,
            "filters": [
                {
                    "source": "interopio.api.interop.invoke",
                    "context": {
                        "method": "T42.UserPreferences"
                    },
                    "enabled": false
                },
                {
                    "source": "interopio.desktop.app.start",
                    "context": {
                        "appName": "clientportfolio"
                    },
                    "enabled": true,
                    "level": "DEBUG",
                    "sample": 0.5
                }
            ],
            "defaults": {
                "enabled": true,
                "level": "INFO",
                "sample": true
            }
        }
    }
}

Each object in the "filters" array has the following properties:

Property	Type	Description
"addContextToTrace"	boolean	Whether the filtering context will be added as span attributes to the span. Defaults to true.
"autoSetSuccessStatus"	boolean	Whether the span's status will be automatically set to OK on completion if it's still UNSET. Defaults to false.
"canBeRoot"	boolean	Whether the span can start a new trace. If false, the span will only be created if an existing trace is currently active. Defaults to true.
"context"	object	Specifies filtering context values used for matching spans. Values are strings, numbers, or Boolean values. Start string values with # for case-insensitive regex matching.
"countMetric"	boolean	Whether the span will be counted in the insights_trace_count metric. Requires both the traces and metrics modules to be enabled. Defaults to false.
"countMetricOnDisabledSpans"	boolean	Whether the span will be counted in the insights_trace_count metric even when the span itself is disabled. Allows using tracing instrumentation purely for generating metrics.
"disableNesting"	boolean	If true, forces the span to always create a new trace, even if a parent span is currently active.
"disablePropagation"	boolean	If true, the span will not inject its propagation info into data transfer objects for span nesting across system boundaries. Defaults to false.
"durationMetric"	boolean	Whether the span duration will be recorded in the insights_trace_duration histogram metric. Requires both the traces and metrics modules to be enabled. Defaults to false.
"durationMetricOnDisabledSpans"	boolean	Whether the span duration will be recorded in the insights_trace_duration metric even when the span itself is disabled.
"enabled"	boolean	If true (default), the matching span will be created. If false, the operation will be a no-op.
"forceChildTracing"	boolean	If true, any child spans (including nested spans across system boundaries) will be forced to be traced, even if their own filter configuration disables them. Defaults to false.
"level"	"OFF" | "LOWEST" | "DIAGNOSTIC" | "DEBUG" | "INFO" | "WARN" | "HIGHEST"	Attribute verbosity level for the span. Defaults to "INFO".
"log"	boolean	If true, enabled spans will also be published as log entries via the io.Connect logging API.
"logOnDisabledSpans"	boolean	If true, disabled spans will also be published as log entries via the io.Connect logging API.
"maxAttributeDepth"	number	How deep the addData() method should recurse into objects when adding attributes to spans. Defaults to 5.
"minDurationMs"	number	If specified, spans whose duration is lower than this value (in milliseconds) will not be sampled. Useful for filtering out short-lived spans such as quick app focus changes.
"otelSpanOptions"	object	OpenTelemetry span options. Accepts "kind" (SpanKind: 0 = INTERNAL, 1 = SERVER, 2 = CLIENT, 3 = PRODUCER, 4 = CONSUMER), "attributes", "links", "startTime", and "root".
"overrideDefaultFilters"	boolean	If true, this filter rule will be matched before any default filters provided by the platform. Default filters reduce verbosity by not tracing some internal operations. Defaults to false.
"resultMetric"	boolean	Whether the span will be counted in the insights_trace_result metric, which includes the final span status (OK or error) as an attribute. Requires both the traces and metrics modules to be enabled. Defaults to false.
"resultMetricOnDisabledSpans"	boolean	Whether the span will be counted in the insights_trace_result metric even when the span itself is disabled.
"sample"	boolean | number	Sampling setting. If true, the span will be sampled. If false, it won't be sampled. If a number between 0 and 1, it represents the sampling probability. Defaults to true.
"source"	string	Specifies the source string used for matching spans (operation name). Start the string with # for case-insensitive regex matching.
"stopPropagationIfSpanIsDisabled"	boolean	If a span is disabled by its filter, setting this to true will stop the propagation of trace nesting info across it, preventing subsequent spans from being nested under the disabled span's parent.

The "defaults" object accepts the same properties as a filter entry (except "source" and "context") and is used as a fallback when no matching filter is found.

Default Span Filters

When "useDefaultFilters" is set to true (the default), the platform applies a predefined set of span filters that reduce the default verbosity of the published trace data. These default filters disable tracing for internal platform operations and prevent certain spans from starting new traces. They are evaluated before any user-defined filters (unless a user filter has "overrideDefaultFilters" set to true).

The following is the full list of default span filters applied by the platform:

[
    {
        "source": "interopio.api.appStartup.finished",
        "enabled": false,
        "context": {
            "tracingAppName": "web-group-application"
        }
    },
    {
        "source": "interopio.api.startup",
        "enabled": false,
        "context": {
            "tracingAppName": "web-group-application"
        }
    },
    {
        "source": "interopio.desktop.workspaces.open",
        "canBeRoot": true
    },
    {
        "source": "interopio.desktop.startup",
        "canBeRoot": true
    },
    {
        "source": "interopio.api.interop.register.callback",
        "disableNesting": true
    },
    {
        "source": "interopio.desktop.app.start",
        "canBeRoot": true
    },
    {
        "source": "interopio.desktop.userJourney",
        "canBeRoot": true
    },
    {
        "source": "interopio.desktop.layouts.restore",
        "canBeRoot": true
    },
    {
        "source": "interopio.desktop.events",
        "enabled": false
    },
    {
        "source": "interopio.desktop",
        "canBeRoot": false
    },
    {
        "source": "interopio.desktop.internal",
        "canBeRoot": false
    },
    {
        "source": "interopio.api.instrumentation.fetch",
        "canBeRoot": false
    },
    {
        "source": "interopio.api.instrumentation.xhr",
        "canBeRoot": false
    },
    {
        "source": "interopio.api.prefs",
        "canBeRoot": false
    },
    {
        "source": "interopio.api.layouts",
        "canBeRoot": false
    },
    {
        "source": "interopio.api.windows",
        "canBeRoot": false
    },
    {
        "source": "interopio.api.interop",
        "context": {
            "stream": "#^t42[.].*"
        },
        "canBeRoot": false,
        "enabled": false
    },
    {
        "source": "interopio.api.interop",
        "context": {
            "stream": "apps.event"
        },
        "canBeRoot": false,
        "enabled": false
    },
    {
        "source": "interopio.api.interop",
        "context": {
            "name": "#^t42[.].*"
        },
        "canBeRoot": false,
        "enabled": false
    },
    {
        "source": "interopio.api.interop",
        "context": {
            "name": "apps.event"
        },
        "canBeRoot": false,
        "enabled": false
    },
    {
        "source": "interopio.api.interop",
        "context": {
            "method": "apps.command"
        },
        "canBeRoot": false
    },
    {
        "source": "interopio.api.interop",
        "context": {
            "method": "#^t42[.].*"
        },
        "canBeRoot": false
    },
    {
        "source": "interopio.api.contexts",
        "context": {
            "context": "___insights_pi_storage___"
        },
        "enabled": false
    },
    {
        "source": "interopio.api.contexts",
        "context": {
            "context": "#^t42[.].*"
        },
        "canBeRoot": false
    },
    {
        "source": "interopio.api.contexts",
        "context": {
            "context": "#^__.*"
        },
        "canBeRoot": false
    },
    {
        "source": "interopio.api.appManager",
        "canBeRoot": false
    },
    {
        "source": "interopio.api.notifications",
        "canBeRoot": false
    }
]

To override a specific default filter, add a filter entry with the same "source" (and "context", if applicable) in the "filters" array and set "overrideDefaultFilters" to true:

{
    "otel": {
        "enabled": true,
        "traces": {
            "enabled": true,
            "url": "http://localhost:4318/v1/traces",
            "useDefaultFilters": true,
            "filters": [
                {
                    "source": "interopio.api.layouts",
                    "overrideDefaultFilters": true,
                    "canBeRoot": true
                }
            ]
        }
    }
}

To disable all default span filters entirely, set "useDefaultFilters" to false.

Sampling

You can use the "sampling" property of the "traces" object to control the sampling of completed spans before they are exported. While filters control whether a span is created, sampling rules control whether an already-created span is exported based on its name, attributes, or context. This is useful for reducing the volume of exported trace data without disabling tracing entirely.

The following example demonstrates how to sample only 10% of Interop invocation spans, while keeping all other spans:

{
    "otel": {
        "enabled": true,
        "traces": {
            "enabled": true,
            "url": "http://localhost:4318/v1/traces",
            "sampling": [
                {
                    "name": "#interopio\\.api\\.interop\\.invoke",
                    "sample": 0.1
                }
            ]
        }
    }
}

Each object in the "sampling" array has the following properties:

Property	Type	Description
"attributes"	object	Span attributes that determine if the span will match this sampling entry. Values are strings, numbers, or Boolean values. Start string values with # for case-insensitive regex matching.
"context"	object	Context values that determine if the span will match this sampling entry. Values are strings, numbers, or Boolean values. Start string values with # for case-insensitive regex matching.
"name"	string	Span name used to match this sampling entry. Start the string with # for case-insensitive regex matching.
"sample"	boolean | number	Required. Probability that the span will be sampled based on its trace ID. If true, the span will always be sampled. If false, it will never be sampled. If a number between 0 and 1, it represents the sampling probability.

User Journey

The User Journey trace tracks app focus changes across the platform, creating spans for each user navigation step. You can enable, disable, or configure this feature using the "userJourney" property of the "traces" object.

The "userJourney" property can be set to:

• true or false to enable or disable the User Journey trace.
• "nested" or "sibling" to control the span structure - "nested" creates child spans under a parent, "sibling" creates independent linked spans.
• An object with the following properties:

Property	Type	Description
"chainLength"	number	If specified, this number of previously focused apps and their focus times will be added as attributes to the User Journey span. Useful when your backend can't easily reconstruct the focus sequence from the trace structure. Defaults to 0.
"descriptiveName"	boolean	If true (default), the User Journey trace span names will include the name of the focused app (e.g., interopio.desktop.userJourney.<event>.<appName>). If false, span names will be interopio.api.userJourney.<event>.
"enabled"	boolean	Required. If true, the User Journey trace will be enabled.
"includeWorkspaceInfo"	boolean	If true (default), the focus spans for windows in a Workspace will include the workspaceId, workspaceName, and workspaceTitle attributes. These attributes are retrieved asynchronously and may be missing from a span if the focus changes again before they're available. Available since io.Connect Desktop 10.5.
"structure"	"nested" | "sibling"	Span structure of User Journey traces. Defaults to "sibling".

The following example demonstrates how to configure the User Journey trace to use a flat structure and to record the three previously focused apps as span attributes:

{
    "otel": {
        "enabled": true,
        "traces": {
            "enabled": true,
            "url": "http://localhost:4318/v1/traces",
            "userJourney": {
                "enabled": true,
                "structure": "sibling",
                "descriptiveName": true,
                "chainLength": 3
            }
        }
    }
}

Click Stream

The Click Stream trace tracks user interactions with DOM elements in web apps, creating spans for each captured event. You can enable, disable, or configure this feature using the "clickstream" property of the "traces" object.

The "clickstream" property can be set to:

• true or false to enable or disable the Click Stream trace.
• "nested" or "sibling" to control the span structure.
• An object with the following properties:

Property	Type	Description
"descriptiveName"	boolean	If true (default), the Click Stream trace span names will include the app name (e.g., interopio.api.clickstream.<appName>.<event>). If false, span names will be interopio.api.clickstream.<event>.
"enabled"	boolean	Required. If true, the Click Stream trace will be enabled.
"events"	string[]	List of DOM event names to capture as Click Stream trace spans. Defaults to ["click"].
"nestEventHandlersEagerly"	boolean	If true and the pre-initialization recorder is installed, the event listeners attached before io.Connect was initialized will also be nested under the Click Stream spans (when "nestEventListeners" is enabled). Defaults to false. Available since io.Connect Desktop 10.5.
"nestEventListeners"	boolean	If true (default), io.Insights will try to nest spans from other event listeners for the same event under the Click Stream span. This isn't guaranteed to always work due to the specifics of how browsers execute event listeners, and will only work for listeners attached after io.Connect was initialized.
"structure"	"nested" | "sibling"	Span structure of Click Stream traces. Defaults to "sibling".

The following example demonstrates how to configure the Click Stream trace to capture both click and double-click events:

{
    "otel": {
        "enabled": true,
        "traces": {
            "enabled": true,
            "url": "http://localhost:4318/v1/traces",
            "clickstream": {
                "enabled": true,
                "structure": "sibling",
                "events": ["click", "dblclick"],
                "nestEventListeners": true
            }
        }
    }
}

Auto Instrumentation

In addition to the instrumentation of the io.Connect APIs and the platform, io.Insights automatically instruments several common operations in web apps. You can control each of them individually using the following properties of the "traces" object:

Property	Type	Description
"instrumentAppStartup"	boolean	If true (default), the app startup will be traced automatically. The app startup span has child spans for the document loading phases, the slowest resource loads, paint marks, long tasks, and lifecycle transitions, and carries the FCP, LCP, and CLS Web Vitals as attributes. The operations traced during the interval specified in the "startupParentSpanTimeoutMs" property are nested under the app startup span. Available since io.Connect Desktop 10.5.
"instrumentErrors"	boolean | object	If true, uncaught errors and unhandled Promise rejections will be published as spans. Defaults to false. Available since io.Connect Desktop 10.5.
"instrumentEventLoop"	boolean | object	If true, slow input events and long tasks blocking the main thread will be published as spans. Defaults to false. Available since io.Connect Desktop 10.5.
"instrumentNavigation"	boolean	If true, in-page navigations (history.pushState(), history.replaceState(), popstate and hashchange events) will be published as spans. Defaults to false. Available since io.Connect Desktop 10.5.
"instrumentRequests"	boolean | object	If true, XMLHttpRequest and fetch() requests will be traced automatically. Defaults to false.
"instrumentResources"	boolean | object	If true, resource loads (scripts, stylesheets, images, fonts) will be published as spans. Defaults to false. Available since io.Connect Desktop 10.5.
"instrumentWebSockets"	boolean | object	If true, WebSocket connections, including the connection to the io.Connect Gateway, will be published as spans. Defaults to false. Available since io.Connect Desktop 10.5.
"instrumentWebVitals"	boolean | object	If true, the CLS, INP, and LCP Web Vitals for the session will be published as spans each time the page becomes hidden. Defaults to false. Available since io.Connect Desktop 10.5.

The spans produced by the auto instrumentation are subject to the span filters and the sampling rules, which you can use to control their volume.

The following example demonstrates how to enable the automatic tracing of HTTP requests, errors, and Web Vitals:

{
    "otel": {
        "enabled": true,
        "traces": {
            "enabled": true,
            "url": "http://localhost:4318/v1/traces",
            "instrumentRequests": true,
            "instrumentErrors": true,
            "instrumentWebVitals": true
        }
    }
}

The instrumentation properties that accept an object allow you to provide additional settings and to enable publishing instrumentation metrics. Each object has an "enabled" property for enabling the respective instrumentation. Most objects also have a "trace" property - set it to false to publish only the enabled metrics, without publishing spans. The properties for enabling histogram metrics have counterparts with a Buckets suffix (e.g., "requestTotalDurationMetricBuckets") that accept an array of explicit bucket boundaries.

ℹ️ For details on all available settings, see the otel.json configuration schema.

Requests

Available since io.Connect Desktop 10.5

The "instrumentRequests" object has the following properties:

Property	Type	Description
"canBeRoot"	boolean	If true, the request spans can be root spans of new traces. This allows you to trace requests without any instrumentation in your own code, but may create a large number of traces.
"enabled"	boolean	If true, will enable the request instrumentation.
"errorStatusCodes"	string[]	HTTP response status codes to consider as errors on request spans. Status code families can be described as "4xx", "5xx", etc. Defaults to ["4xx", "5xx"].
"ignorePattern"	string	Regular expression pattern for URLs to exclude from the instrumentation.
"ignoreTelemetryURLs"	boolean	If true (default), the requests to the telemetry endpoints won't be instrumented.
"matchPattern"	string	Regular expression pattern for URLs to include in the instrumentation.
"platform"	boolean	If true, the HTTP requests made by io.Connect Desktop itself will also be traced and the enabled metrics will be published for them. Defaults to false.
"preInit"	boolean	If true (default) and the pre-initialization recorder is installed, the requests made before the @interopio/desktop library has been initialized will also be recorded.
"requestBodyDownloadDurationMetric"	boolean | string	If true, the time from receiving the response headers until the response body is fully received will be published as the io.insights.http.client.response.download.duration histogram metric. Set to a string to use a custom metric name. Defaults to false.
"requestBodyDownloadThroughputMetric"	boolean | string	If true, the download throughput of the response body in bytes per second will be published as the io.insights.http.client.response.download.throughput histogram metric. Set to a string to use a custom metric name. Defaults to false.
"requestBytesMetric"	boolean | string	If true, the size of the request body will be published as the http.client.request.body.size histogram metric. Set to a string to use a custom metric name. Defaults to false.
"requestFirstByteDurationMetric"	boolean | string	If true, the time from sending the request until receiving the response headers will be published as the io.insights.http.client.request.ttfb.duration histogram metric. Set to a string to use a custom metric name. Defaults to false.
"requestTotalDurationMetric"	boolean | string	If true, the time from sending the request until the response body is fully received will be published as the http.client.request.duration histogram metric. Set to a string to use a custom metric name. Defaults to false.
"responseBytesMeasurement"	"content-length" | "raw" | "both"	Measurement used for the size of the response body. Set to "content-length" (default) to use the value of the Content-Length response header. Set to "raw" to count the bytes of the response body. Set to "both" to use the Content-Length header and fall back to counting the bytes when the header is missing.
"responseBytesMetric"	boolean | string	If true, the size of the response body will be published as the http.client.response.body.size histogram metric. Set to a string to use a custom metric name. Defaults to false.
"spanNames"	"semconv" | "product"	Naming of the request spans. Set to "semconv" (default) to name the spans by the HTTP request method (e.g., GET), according to the OpenTelemetry semantic conventions for HTTP client spans. Set to "product" to use the interopio.api.instrumentation.fetch and interopio.api.instrumentation.xhr span names. In both cases, the span filters match the request spans by the interopio.api.instrumentation.fetch and interopio.api.instrumentation.xhr sources.
"trace"	boolean	If false, no request spans will be published - only the enabled metrics. Defaults to true.

⚠️ Note that when the "requestTotalDurationMetric", "requestBodyDownloadDurationMetric", or "requestBodyDownloadThroughputMetric" metric is enabled, the response body of every non-streaming fetch() request is read in full in order to measure its delivery, including the responses that your app doesn't read.

The following example demonstrates how to enable the request instrumentation and publish metrics for the total request duration and the size of the response body:

{
    "otel": {
        "enabled": true,
        "traces": {
            "enabled": true,
            "instrumentRequests": {
                "enabled": true,
                "requestTotalDurationMetric": true,
                "responseBytesMetric": true
            }
        }
    }
}

Errors

Available since io.Connect Desktop 10.5

The "instrumentErrors" object has the following properties:

Property	Type	Description
"enabled"	boolean	If true, uncaught errors and unhandled Promise rejections will be published as spans.
"preInit"	boolean	If true (default) and the pre-initialization recorder is installed, the errors that occur before the @interopio/desktop library has been initialized will also be recorded.

Resources

Available since io.Connect Desktop 10.5

The "instrumentResources" object has the following properties:

Property	Type	Description
"cacheStateMetric"	boolean | string	If true, a counter of the resource loads by cache state will be published as the io.insights.resource.cache.state metric. Set to a string to use a custom metric name. Defaults to false.
"connectDurationMetric"	boolean | string	If true, the connection establishment durations will be published as the io.insights.resource.connect.duration histogram metric. Set to a string to use a custom metric name. Defaults to false.
"dnsDurationMetric"	boolean | string	If true, the DNS lookup durations will be published as the io.insights.resource.dns.duration histogram metric. Set to a string to use a custom metric name. Defaults to false.
"downloadThroughputMetric"	boolean | string	If true, the download throughput in bytes per second will be published as the io.insights.resource.download.throughput histogram metric. Set to a string to use a custom metric name. Defaults to false.
"downloadThroughputMinBytes"	number	Minimum size in bytes of a resource for which the download throughput will be measured. Defaults to 32768.
"enabled"	boolean	If true, resource loads will be published as spans.
"firstByteDurationMetric"	boolean | string	If true, the time from sending the request for a resource until receiving the first byte of the response will be published as the io.insights.resource.ttfb.duration histogram metric. Set to a string to use a custom metric name. Defaults to false.
"skipRequests"	boolean	If true (default), the XMLHttpRequest and fetch() requests will be skipped, because the request instrumentation covers them in more detail.
"tlsDurationMetric"	boolean | string	If true, the TLS handshake durations will be published as the io.insights.resource.tls.duration histogram metric. Set to a string to use a custom metric name. Defaults to false.
"trace"	boolean	If false, no resource spans will be published - only the enabled metrics. Defaults to true.

Event Loop

Available since io.Connect Desktop 10.5

The "instrumentEventLoop" object has the following properties:

Property	Type	Description
"enabled"	boolean	If true, will enable the event loop instrumentation.
"eventLoopBlockingMetric"	boolean | string	If true, the time for which long frames block the main thread will be published as the io.insights.event_loop.blocking.duration histogram metric. Set to a string to use a custom metric name. Defaults to false.
"eventLoopBlockingSpans"	boolean	If true (default), the long frames blocking the main thread will be published as spans.
"inputDelayDurationThresholdMs"	number	Minimum duration in milliseconds of an input event (from the event until the next paint) for it to be observed. Defaults to 16.
"inputDelayInteractionsOnly"	boolean	If true (default), only discrete user interactions (e.g., clicks and key presses) will be observed. If false, continuous events (e.g., pointermove) that reach the duration threshold will also be observed.
"inputDelayMetric"	boolean | string	If true, the time from an input event until its handlers start running will be published as the io.insights.event_loop.input.delay histogram metric. Set to a string to use a custom metric name. Defaults to false.
"inputDelaySpans"	boolean	If true (default), the slow input events will be published as spans.
"trace"	boolean	If false, no event loop spans will be published - only the enabled metrics. Defaults to true.

WebSockets

Available since io.Connect Desktop 10.5

The "instrumentWebSockets" object has the following properties:

Property	Type	Description
"bytesMetric"	boolean | string	If true, a counter of the sent and received WebSocket message bytes will be published as the io.insights.websocket.bytes metric. Set to a string to use a custom metric name. Defaults to false.
"connectDurationMetric"	boolean | string	If true, the time for establishing a WebSocket connection will be published as the io.insights.websocket.connect.duration histogram metric. Set to a string to use a custom metric name. Defaults to false.
"enabled"	boolean	If true, WebSocket connections will be published as spans.
"ignoreGateway"	boolean	If true, the connection to the io.Connect Gateway will be excluded from the instrumentation. Defaults to false.
"ignorePattern"	string	Regular expression pattern for WebSocket URLs to exclude from the instrumentation.
"matchPattern"	string	Regular expression pattern for WebSocket URLs to include in the instrumentation.
"messagesMetric"	boolean | string	If true, a counter of the sent and received WebSocket messages will be published as the io.insights.websocket.messages metric. Set to a string to use a custom metric name. Defaults to false.
"platform"	boolean	If true, the WebSocket connections of io.Connect Desktop itself, including its connection to the io.Connect Gateway, will also be tracked. Defaults to false.
"preInit"	boolean	If true (default) and the pre-initialization recorder is installed, the WebSocket connections opened before the @interopio/desktop library has been initialized will also be tracked.
"trace"	boolean	If false, no WebSocket spans will be published - only the enabled metrics. Defaults to true.

⚠️ Note that when the "messagesMetric" or the "bytesMetric" metric is enabled, the connection to the io.Connect Gateway contributes a measurement for every Gateway message. Set "ignoreGateway" to true to exclude it.

Web Vitals

Available since io.Connect Desktop 10.5

The "instrumentWebVitals" object has the following properties:

Property	Type	Description
"clsMetric"	boolean | string	If true, the cumulative layout shift for the session will be published as the io.insights.web_vitals.cls histogram metric. Set to a string to use a custom metric name. Defaults to false.
"enabled"	boolean	If true, will enable the Web Vitals instrumentation.
"inpMetric"	boolean | string	If true, the interaction to next paint for the session will be published as the io.insights.web_vitals.inp histogram metric. Set to a string to use a custom metric name. Defaults to false.
"lcpMetric"	boolean | string	If true, the final largest contentful paint will be published as the io.insights.web_vitals.lcp histogram metric. Set to a string to use a custom metric name. Defaults to false.
"trace"	boolean	If false, no Web Vitals spans will be published - only the enabled metrics. Defaults to true.

Tracking Events Before Initialization

Available since io.Connect Desktop 10.5

io.Insights can capture requests, errors, and WebSocket connections that occur in your app before the @interopio/desktop library has been initialized, and publish them after the initialization. To enable this, add the insights-early.js preload script distributed with io.Connect Desktop to the app definition and enable the respective instrumentation:

{
    "details": {
        "preloadScripts": [
            "file://%GDDIR%/assets/preloads/insights-early.js"
        ]
    }
}

The recorded events are published with their original timestamps. To exclude an instrumentation from the recording, set the "preInit" property of its configuration object to false.

Context Management

Asynchronous code presents challenges with respect to tracking which span is currently active, as a sequentially written piece of code may execute at several different moments in time. The "traces" object provides two properties that control how the library resolves the currently active context:

Property	Type	Description
"hybridContextMode"	boolean	If true, the library will use both the ContextManager provided by the OpenTelemetry SDK and the Traces.currentTracingState property to resolve the current context. Defaults to false.
"useOTELContextManager"	boolean	If true, the library will use the ContextManager provided by the active OpenTelemetry SDK to manage and derive propagation information, ensuring that spans created across asynchronous operations are properly nested. Defaults to false.

Using a context manager (e.g., Zone.js) generally requires a build step that converts await statements into Promises. If your apps can't use one, you can instead restore the tracing state manually or pass propagation info explicitly from your code.

The following example demonstrates how to enable the OpenTelemetry ContextManager together with the hybrid context resolution:

{
    "otel": {
        "enabled": true,
        "traces": {
            "enabled": true,
            "url": "http://localhost:4318/v1/traces",
            "useOTELContextManager": true,
            "hybridContextMode": true
        }
    }
}

ℹ️ For details on restoring the tracing state and passing propagation info from your code, see the Insights API > JavaScript section.

Traces as Metrics

Tracing spans can also be published as metrics, allowing any code instrumented with tracing to report how many times it was invoked and how long it took. The names of the derived metrics are controlled by the "countMetric", "resultMetric" and "durationMetric" properties of the "traces" object (set any of them to null to disable it entirely), while the span filters determine which spans are measured.

Use the following properties of a filter entry to enable the derived metrics for the matching spans:

Property	Metric	Description
"countMetric"	insights_trace_count	Counts how many times the span was hit.
"durationMetric"	insights_trace_duration	Measures how long the span took from start to completion.
"resultMetric"	insights_trace_result	Same as "countMetric", but includes the final span status (success or error) as an attribute.

Each of these properties has an "...OnDisabledSpans" counterpart ("countMetricOnDisabledSpans", "durationMetricOnDisabledSpans", "resultMetricOnDisabledSpans") which records the metric even when the span itself is disabled. This allows you to use the tracing instrumentation purely for generating metrics, without publishing any tracing data.

⚠️ Note that both the traces and the metrics modules must be enabled for this feature to work.

The following example demonstrates how to measure the duration and the result of all Interop invocations, and how to count app starts without publishing their spans:

{
    "otel": {
        "enabled": true,
        "metrics": {
            "enabled": true,
            "url": "http://localhost:4318/v1/metrics"
        },
        "traces": {
            "enabled": true,
            "url": "http://localhost:4318/v1/traces",
            "countMetric": "insights_trace_count",
            "durationMetric": "insights_trace_duration",
            "resultMetric": "insights_trace_result",
            "filters": [
                {
                    "source": "interopio.api.interop.invoke",
                    "enabled": true,
                    "durationMetric": true,
                    "resultMetric": true
                },
                {
                    "source": "interopio.desktop.app.start",
                    "enabled": false,
                    "countMetricOnDisabledSpans": true
                }
            ]
        }
    }
}

Traces as Logs

Tracing spans can also be published as log entries via the io.Connect logging API, which allows you to write them to a file or any other logging storage without needing a tracing backend. As the log entries are created in near real time, this also ensures that spans are recorded even if a crash prevents the regular OpenTelemetry export from completing.

Use the following properties of a span filter entry to control this behavior:

Property	Type	Description
"log"	boolean	If true, enabled spans matching the filter will also be published as log entries.
"logOnDisabledSpans"	boolean	If true, disabled spans matching the filter will also be published as log entries.

The logs module doesn't have to be enabled for this feature to work, as it uses the io.Connect logging API directly. Enable the logs module only if you also want the resulting log entries to be published over OpenTelemetry.

The following example demonstrates how to log all Workspace operations, and how to log app start operations without publishing their spans:

{
    "otel": {
        "enabled": true,
        "traces": {
            "enabled": true,
            "url": "http://localhost:4318/v1/traces",
            "filters": [
                {
                    "source": "interopio.desktop.workspaces",
                    "enabled": true,
                    "log": true
                },
                {
                    "source": "interopio.desktop.app.start",
                    "enabled": false,
                    "logOnDisabledSpans": true
                }
            ]
        }
    }
}

Exporter Settings

The traces exporter can be fine-tuned using the "compression", "timeoutMillis", "concurrencyLimit", "keepAlive" and "publishInterval" properties of the "traces" object. These settings control the HTTP transport behavior of the OTLP traces exporter.

The following example demonstrates how to configure the traces exporter with GZIP compression and a custom timeout:

{
    "otel": {
        "enabled": true,
        "traces": {
            "enabled": true,
            "url": "http://localhost:4318/v1/traces",
            "publishInterval": 30000,
            "compression": "gzip",
            "timeoutMillis": 15000,
            "keepAlive": true,
            "concurrencyLimit": 5
        }
    }
}

For advanced scenarios, you can pass options directly to the underlying OpenTelemetry SDK objects using the "exporterSettings", "tracerProviderSettings" and "processorSettings" properties of the "traces" object. The "processorSettings" property is particularly useful for tuning the batch span processor in high-volume environments:

{
    "otel": {
        "enabled": true,
        "traces": {
            "enabled": true,
            "url": "http://localhost:4318/v1/traces",
            "processorSettings": {
                "maxExportBatchSize": 512,
                "scheduledDelayMillis": 5000,
                "exportTimeoutMillis": 30000,
                "maxQueueSize": 2048
            }
        }
    }
}

Resource & Span Attributes

You can customize the OpenTelemetry resource-level attributes and the span attributes using the "additionalResourceAttributes" and "additionalAttributes" properties of the "traces" object. These are merged with (and take precedence over) the respective top-level settings.

If you set "addResourceAttributesToAttributes" to true, all resource-level attributes will be copied into every span, making them available for filtering and querying in your traces backend.

ℹ️ For details on the common resource-level attributes published by io.Connect Desktop, see the Signals > Overview > Common Resource Attributes section.

The following example demonstrates how to add custom resource and span attributes to traces:

{
    "otel": {
        "enabled": true,
        "traces": {
            "enabled": true,
            "url": "http://localhost:4318/v1/traces",
            "additionalResourceAttributes": {
                "deployment.environment": "production",
                "team": "platform-engineering"
            },
            "additionalAttributes": {
                "datacenter": "%DATACENTER_NAME%"
            },
            "addResourceAttributesToAttributes": true
        }
    }
}

Available since io.Connect Desktop 10.1

To provide custom settings for publishing logs, use the "logs" property of the "otel" object.

The "logs" object has the following properties:

Property	Type	Description
"additionalAttributes"	object	Additional log attributes to publish as part of each log entry, specified as key/value pairs. You can use environment variables as values. Environment variables must start and end with a percent sign (e.g., %MyEnvVar%), and can contain a fallback value (e.g., %MyEnvVar?DefaultValue%).
"additionalResourceAttributes"	object	Additional attributes to publish as part of the OpenTelemetry resource definition for log signals, specified as key/value pairs. You can use environment variables as values. Environment variables must start and end with a percent sign (e.g., %MyEnvVar%), and can contain a fallback value (e.g., %MyEnvVar?DefaultValue%).
"addResourceAttributesToAttributes"	boolean	Whether to add resource attributes to log record attributes. Defaults to false. Signal-level setting takes precedence over the top-level one.
"compression"	"none" | "gzip"	Compression algorithm to use for log export requests.
"concurrencyLimit"	number	Maximum number of concurrent log export requests.
"defaults"	object	Default log filter options used as a fallback when no matching filter entry is found.
"enabled"	boolean	If true, will enable publishing logs. Defaults to false.
"exporterSettings"	object	Options to use when creating the OTLP log exporter. Provides fine-grained control over the HTTP transport ("headers", "url", "concurrencyLimit", "timeoutMillis", "keepAlive", "compression", "httpAgentOptions").
"filters"	object[]	Array of filter entries used to determine whether a particular log entry will be emitted, and which attributes will be included. If no matching filter entry is found, the settings from "defaults" are used.
"headers"	object	Additional headers to send with log export HTTP requests, specified as key/value pairs where values are strings. Merged with and takes precedence over the top-level "headers" setting.
"keepAlive"	boolean	If true (default), the HTTP connection will be kept alive when sending logs.
"levelCountMetric"	string | null	Name of the log level counter metric. Set to null to disable. Defaults to "insights_log_level_count". See Logs as Metrics.
"loggerProviderSettings"	object	Options to use when creating the OpenTelemetry LoggerProvider. Accepts "resource", "forceFlushTimeoutMillis" (defaults to 30000) and "logRecordLimits".
"maxAttributeDepth"	number	Maximum depth for flattening nested objects into log attributes. Defaults to 5.
"processorSettings"	object	Options to use when creating the batch log record processor. Accepts "maxExportBatchSize" (defaults to 512), "scheduledDelayMillis" (defaults to 5000), "exportTimeoutMillis" (defaults to 30000), "maxQueueSize" (defaults to 2048) and "disableAutoFlushOnDocumentHide".
"publishInterval"	number	Interval in milliseconds between log export batches.
"startupTraceAssociationTimeoutMs"	number	How long in milliseconds after app startup any log entries will automatically be associated with the app startup trace.
"timeoutMillis"	number	Maximum time in milliseconds the OTLP exporter will wait for each batch export. Defaults to 10000.
"url"	string	URL pointing to an OpenTelemetry logs collector.
"useDefaultFilters"	boolean	If true (default), a predefined list of filters for well-known platform logs will be applied.
"useSSOAuth"	boolean	If true, the platform SSO login information will be used when making log export requests. Takes precedence over the top-level "useSSOAuth" setting. Defaults to false.
"useSSOAuthRawToken"	boolean	Used when the SSO login information contains a token property. If true (default), the token will be used as-is. If false, the token may be prepended with "Bearer ". Takes precedence over the top-level setting.

The following sections describe the configuration settings for the main features related to publishing logs with io.Insights.

ℹ️ For details on all available settings for configuring io.Insights, see the otel.json configuration schema.

Log Appender

io.Connect Desktop is bundled with the @interopio/log4js-otel appender, which bridges the log4js logging pipeline of the platform with the OpenTelemetry log exporter. The logs module doesn't capture log entries on its own - the appender is what feeds it, so enabling the logs module alone won't publish anything.

The appender isn't part of the default logging configuration and must be declared explicitly.

To publish logs over OpenTelemetry, execute the following steps:

1. Define the appender under the "appenders" property of the "configuration" object under the "logging" top-level key in the system.json file:

{
    "logging": {
        "configuration": {
            "appenders": {
                "otel": {
                    "type": "@interopio/log4js-otel",
                    "maxRecordsBeforeOTELActive": 10000,
                    "maxTimeBeforeOTELActiveMs": -1,
                    "logErrorsInConsole": true
                }
            }
        }
    }
}

2. Assign the appender to the categories whose log entries you want to forward. The following example forwards the platform logs (the "default" category), the logs published by your apps through the Logger API (the "app-own-log" category), and the io.Connect Gateway logs (the "gw" category):

{
    "logging": {
        "configuration": {
            "categories": {
                "default": {
                    "appenders": ["out", "app", "otel"],
                    "level": "info"
                },
                "app-own-log": {
                    "appenders": ["applications", "otel"],
                    "level": "trace"
                },
                "gw": {
                    "appenders": ["gateway", "otel"],
                    "level": "info"
                }
            }
        }
    }
}

3. Enable the logs module and specify the endpoint of your OpenTelemetry collector under the "otel" top-level key in the system.json file:

{
    "otel": {
        "enabled": true,
        "logs": {
            "enabled": true,
            "url": "http://localhost:4318/v1/logs"
        }
    }
}

The appender accepts the standard log4js appender properties, as well as the following ones:

Property	Type	Description
"layout"	object	The log4js layout to use for structuring the log entries. If not specified, the MessagePassThroughLayout layout will be used.
"logErrorsInConsole"	boolean	If true (default), errors in the appender itself will be logged to the console.
"maxRecordsBeforeOTELActive"	number	Maximum number of log records to store in memory before the OpenTelemetry SDK has finished initializing. Use -1 for an unlimited number. Defaults to 10000.
"maxTimeBeforeOTELActiveMs"	number	Maximum time in milliseconds to store log entries in memory before the OpenTelemetry SDK has finished initializing. Use -1 for an unlimited duration. Defaults to -1.
"type"	string	Required. Must be set to "@interopio/log4js-otel".

Log entries produced early in the platform startup sequence are emitted before the OpenTelemetry SDK is ready. The appender holds these entries in memory and flushes them once the SDK has been initialized. Use the "maxRecordsBeforeOTELActive" and "maxTimeBeforeOTELActiveMs" properties to limit how much is retained.

ℹ️ For details on configuring log appenders, see the Developers > Configuration > System > Logging section in the io.Connect Desktop documentation.

⚠️ Note that log entries may contain sensitive information such as authentication tokens, passwords, or other credentials. Review the categories and severity levels you forward, and use the "hideRegex" property of the log filters to mask sensitive patterns before the entries are published.

Log Filters

You can use the "filters" property of the "logs" object to control which log entries are published and which attributes are included. Each filter entry matches log records by category name, severity, and/or body content. When a log entry is emitted, the filter list is searched for a matching entry, and the settings from that entry are applied. If no match is found, the settings from "defaults" are used.

The following example demonstrates how to filter log entries by severity and category, and how to redact sensitive data:

{
    "otel": {
        "enabled": true,
        "logs": {
            "enabled": true,
            "url": "http://localhost:4318/v1/logs",
            "filters": [
                {
                    "severity": "DEBUG",
                    "enabled": false
                },
                {
                    "categoryName": "auth",
                    "hideRegex": "(password|secret|token)=[^&\\s]+"
                },
                {
                    "categoryName": "app-own-log",
                    "allowedAttributes": ["applicationName", "instanceId", "loggerName"]
                }
            ],
            "defaults": {
                "enabled": true
            }
        }
    }
}

Each object in the "filters" array has the following properties:

Property	Type	Description
"allowedAttributes"	string[]	List of allowed attributes for the log entry. If specified, any attributes missing from the list will be removed before publishing.
"bodyRegex"	string	Regex pattern used to match the text body of the log entry.
"categoryName"	string	Used to match the category of the log entry.
"enabled"	boolean	If true, the matching log entry will be published.
"hideRegex"	string	Regex pattern for redacting sensitive log data. Text matching this regex will be replaced with asterisks.
"severity"	"TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR" | "FATAL"	Used to match the severity of the log entry.

The "defaults" object accepts the same properties as a filter entry (except "categoryName", "severity", and "bodyRegex") and is used as a fallback when no matching filter is found.

The "useDefaultFilters" property controls whether the predefined filters for well-known platform logs are applied. To disable them entirely, set it to false.

Logs as Metrics

The logs module publishes a counter metric that tracks how many log entries were emitted at each severity level, which is useful for building alerts on error rates without having to query your logs backend. The name of the metric is controlled by the "levelCountMetric" property of the "logs" object and defaults to "insights_log_level_count". Set it to null to disable the metric.

⚠️ Note that both the logs and the metrics modules must be enabled for this feature to work.

{
    "otel": {
        "enabled": true,
        "metrics": {
            "enabled": true,
            "url": "http://localhost:4318/v1/metrics"
        },
        "logs": {
            "enabled": true,
            "url": "http://localhost:4318/v1/logs",
            "levelCountMetric": "insights_log_level_count"
        }
    }
}

Exporter Settings

The logs exporter can be fine-tuned using the "compression", "timeoutMillis", "concurrencyLimit", "keepAlive" and "publishInterval" properties of the "logs" object. These settings control the HTTP transport behavior of the OTLP logs exporter.

The following example demonstrates how to configure the logs exporter with GZIP compression and a custom timeout:

{
    "otel": {
        "enabled": true,
        "logs": {
            "enabled": true,
            "url": "http://localhost:4318/v1/logs",
            "publishInterval": 30000,
            "compression": "gzip",
            "timeoutMillis": 15000,
            "keepAlive": true,
            "concurrencyLimit": 5
        }
    }
}

For advanced scenarios, you can pass options directly to the underlying OpenTelemetry SDK objects using the "exporterSettings", "loggerProviderSettings" and "processorSettings" properties of the "logs" object.

You can also use the "startupTraceAssociationTimeoutMs" property to control how long after app startup any log entries will automatically be associated with the app startup trace.

Resource & Log Attributes

You can customize the OpenTelemetry resource-level attributes and the log record attributes using the "additionalResourceAttributes" and "additionalAttributes" properties of the "logs" object. These are merged with (and take precedence over) the respective top-level settings.

If you set "addResourceAttributesToAttributes" to true, all resource-level attributes will be copied into every log record, making them available for filtering and querying in your logs backend.

ℹ️ For details on the common resource-level attributes published by io.Connect Desktop, see the Signals > Overview > Common Resource Attributes section.

The following example demonstrates how to add custom resource and log record attributes:

{
    "otel": {
        "enabled": true,
        "logs": {
            "enabled": true,
            "url": "http://localhost:4318/v1/logs",
            "additionalResourceAttributes": {
                "deployment.environment": "production",
                "team": "platform-engineering"
            },
            "additionalAttributes": {
                "datacenter": "%DATACENTER_NAME%"
            },
            "addResourceAttributesToAttributes": true
        }
    }
}