Signals
Overview
io.Insights publishes a wide array of default platform metrics that provide information about the system, platform and app performance, as well as data related to loading Workspaces and Global Layouts.
All published metrics have common resource attributes.
Each metric may have additional attributes described in the respective metric sub-section.
It's possible to enable or disable all default platform metrics, and also to provide custom settings for each default platform metric individually.
ℹ️ For details on configuring the default platform metrics in io.Connect Desktop and io.Connect Browser, see the Configuration > io.Connect Desktop and Configuration > io.Connect Browser sections respectively.
⚠️ Note that some of the metrics aren't supported in io.Connect Browser due to limitations of modern browsers.
Metrics Payload Structure
Metrics are published as standard OpenTelemetry metrics payloads.
ℹ️ For more details on the standard structure of OpenTelemetry signals, see the OpenTelemetry examples in GitHub.
The following example demonstrates the basic structure of a metrics payload:
{
"resourceMetrics": [
{
"resource": {
"attributes": [
// Attributes describing the resource publishing the metrics -
// e.g., `"service.name"`, `"service.instance.id"`, and other standard OpenTelemetry attributes.
]
},
"scopeMetrics": [
{
"scope": {
"name": "io.Connect Desktop",
"version": ""
},
"metrics": [
// List of objects describing the published metrics.
]
}
]
}
]
}The following is an example metrics object in the "metrics" array. The example uses the "app_startup" metric:
{
"metrics": [
{
"name": "app_startup",
"description": "Time to load an application",
"unit": "ms",
// Type of the metrics point - e.g., `"sum"`, `"gauge"`, `"histogram"`.
"histogram": {
"aggregationTemporality": 2,
// Metric data points.
"dataPoints": [
{
// Metrics attributes.
"attributes": [
{
"key": "api",
"value": {
"stringValue": "6.6.0"
}
},
{
"key": "user",
"value": {
"stringValue": "user_42"
}
},
{
"key": "platformVersion",
"value": {
"stringValue": "9.4.0.34"
}
},
{
"key": "application",
"value": {
"stringValue": "my-app"
}
}
],
"bucketCounts": [
0,
1,
0,
0,
0,
0
],
"explicitBounds": [
100,
1000,
10000,
30000,
60000
],
"count": 1,
"sum": 483,
"min": 483,
"max": 483,
"startTimeUnixNano": "1723555102580000000",
"timeUnixNano": "1723556246869000000"
}
]
}
}
]
}Common Metrics Attributes
All metrics data points have the following common attributes:
| Attribute | Description |
|---|---|
"platformVersion" |
The version of the platform (e.g., "10.1.0"). |
"sid" |
The impersonated (SSO) user identity, set after authentication. This may differ from "user" when one person authenticates as another. Available since io.Connect Desktop 10.1. |
"user" |
The io.Connect user identity (e.g., "user_42"). |
All additional data point attributes provided via the platform configuration or dynamically via the Insights API will also be included in the respective data points. If the resource-level attributes are configured to be merged with the data point attributes, all resource-level attributes will also be included in every data point.
ℹ️ For details on the resource-level attributes common to all signals (metrics, traces, logs), see the Signals > Overview > Common Resource Attributes section.
Platform Metrics
The following sections describe all default platform metrics, the type of Instrument used for their implementation, and any additional attributes they may have in their data points.
System
The following table lists the available metrics related to system performance:
| Metric | Instrument Type | Unit | Description |
|---|---|---|---|
"system_cpu" |
ObservableGauge |
percent | The current and average system CPU and average platform CPU usage. Available only in io.Connect Desktop. |
"system_memory" |
ObservableGauge |
gigabytes | The free system memory, used system memory, and used platform memory. Available only in io.Connect Desktop. |
The "system_cpu" metric has the following additional attributes:
| Attribute | Description |
|---|---|
"type" |
Determines whether the metric value reflects the current system CPU usage, the average system CPU usage, or the average platform CPU usage. Possible values for this attribute are "current_system_cpu", "average_system_cpu" and "average_platform_cpu". |
The "system_memory" metric has the following additional attributes:
| Attribute | Description |
|---|---|
"type" |
Determines whether the metric value reflects the free system memory, the used system memory, or the used platform memory. Possible values for this attribute are "free_system_memory", "used_system_memory" and "used_platform_memory". |
Platform
The following table lists the available metrics related to platform performance:
| Metric | Instrument Type | Unit | Description |
|---|---|---|---|
"platform_error" |
Counter |
number | The number of times a platform error was received during each platform session. |
"platform_startup" |
Gauge |
milliseconds | The time it took to load the io.Connect platform. For io.Connect Desktop, this is the moment from starting the actual executable file (not the gilding executable) and includes the entire platform startup sequence until the moment the shell app starts loading. For io.Connect Browser, this is the time it takes for the @interopio/browser-platform library to initialize. Can be configured as a Histogram. |
The "platform_startup" metric has the following additional attributes:
| Attribute | Description |
|---|---|
"api" |
Version string of the @interopio/desktop or the @interopio/browser-platform library depending on whether the metric was published by the io.Connect Desktop or the io.Connect Browser platform. |
Apps
The following table lists the available metrics related to app performance:
| Metric | Instrument Type | Unit | Description |
|---|---|---|---|
"app_count" |
UpDownCounter |
number | The number of app instances during each platform session. |
"app_cpu" |
ObservableGauge |
percent | The average percentage of CPU used for the last measured interval. Available only in io.Connect Desktop. |
"app_crash" |
Counter |
number | The number of times an app crashed during each platform session. For web apps, this metric is published when the process renderer is gone. For native apps, this metric is published when the process is killed, when the process exits with a non-zero exit code, or when the process is terminated due to a fatal error. You can use the "reason" attribute to determine the cause for the crash. Available only in io.Connect Desktop. |
"app_duration" |
Gauge |
milliseconds | The time an app has been on focus during each platform session. Can be configured as a Histogram. |
"app_error" |
Counter |
number | The number of times an app error was received during each platform session. This metric reports only errors received in the handlers for the "error" and "unhandledrejection" events in web apps. |
"app_memory" |
ObservableGauge |
kilobytes | The current app memory usage. Available only in io.Connect Desktop. |
"app_started" |
Counter |
number | The number of times an app has been started during each platform session. |
"app_startup" |
Gauge |
milliseconds | The time it took to start an app. For web apps running in the Electron container of io.Connect Desktop, this metric measures the interval from receiving the request for starting the app until the "did-finish-load" Electron event is fired, which ensures that the web page has been fully loaded. For native apps running in io.Connect Desktop and using the io.Connect libraries, this metric measures the interval from receiving the request for starting the app until the Interop instance of the app is ready. This metric isn't published for native apps that don't use the io.Connect libraries, as in this case, a reliable signal for completing the app initialization process isn't available. For web apps running in io.Connect Browser, this metric measures the interval from receiving the request for starting the app until the io.Connect API has been initialized in it. Can be configured as a Histogram. |
"app_stopped" |
Counter |
number | The number of times an app has been stopped during each platform session. |
The "app_count" metric has the following additional attributes:
| Attribute | Description |
|---|---|
"application" |
The name of the app within the io.Connect framework for which the "app_count" metric was published. |
The "app_cpu" metric has the following additional attributes:
| Attribute | Description |
|---|---|
"application" |
The name of the app within the io.Connect framework for which the "app_cpu" metric was published. |
"applicationInstance" |
The unique ID of the app instance within the io.Connect framework. |
The "app_crash" metric has the following additional attributes:
| Attribute | Description |
|---|---|
"application" |
The name of the app within the io.Connect framework for which the "app_crash" metric was published. |
"reason" |
Describes the reason for the app crash. For web apps, the value of this attribute is derived from the value of the reason property of the RenderProcessGoneDetails Electron object.For native apps, the value of this attribute can be: - "crashed" - when the process exited with a non-zero exit code;- the signal sent to the process - when the process was terminated or killed and the exit event includes a signal; - the message from the error event - when the process couldn't be started or controlled due to a fatal OS-level error; |
The "app_duration" metric has the following additional attributes:
| Attribute | Description |
|---|---|
"application" |
The name of the app within the io.Connect framework for which the "app_duration" metric was published. |
The "app_error" metric has the following additional attributes:
| Attribute | Description |
|---|---|
"application" |
The name of the app within the io.Connect framework for which the "app_error" metric was published. |
The "app_memory" metric has the following additional attributes:
| Attribute | Description |
|---|---|
"application" |
The name of the app within the io.Connect framework for which the "app_memory" metric was published. |
"applicationInstance" |
The unique ID of the app instance within the io.Connect framework. |
The "app_started" metric has the following additional attributes:
| Attribute | Description |
|---|---|
"application" |
The name of the app within the io.Connect framework for which the "app_started" metric was published. |
The "app_startup" metric has the following additional attributes:
| Attribute | Description |
|---|---|
"application" |
The name of the app within the io.Connect framework for which the "app_startup" metric was published. |
"api" |
Version string of the @interopio/desktop or the @interopio/browser library depending on whether the app is running within the io.Connect Desktop or the io.Connect Browser platform. |
The "app_stopped" metric has the following additional attributes:
| Attribute | Description |
|---|---|
"application" |
The name of the app within the io.Connect framework for which the "app_stopped" metric was published. |
Workspaces
The following table lists the available metrics related to Workspaces performance:
| Metric | Instrument Type | Unit | Description |
|---|---|---|---|
"workspace_count" |
UpDownCounter |
number | The number of Workspaces running during each platform session. |
"workspace_selected" |
Counter |
number | The number of times a Workspace has been selected during each platform session. |
"workspace_started" |
Counter |
number | The number of times a Workspace has been started during each platform session. |
"workspace_startup" |
Gauge |
milliseconds | The total time it took to load a Workspace. Measures the interval from initiating the request for creating or restoring the Workspace until all visible apps in it have been loaded. For web apps, this means that the DOMContentLoaded event has been fired. For native apps (io.Connect Desktop only), this means that the app has completed its window registration within the io.Connect framework. For io.Connect Browser, this metric doesn't measure the time for initializing a Workspaces App instance, only the time for loading the actual Workspace in it. For io.Connect Desktop, this is the root metric for measuring Workspace startup times and it's published in parallel with several sub-metrics that measure the separate intervals for completing the consecutive stages of loading a Workspace. You can use the "includesFrameCreation" attribute to determine whether the measurement includes the time for initializing a Workspaces App instance. If the Workspace is created or restored in a new Workspaces App instance, the "workspace_startup_frame" metric and its sub-metrics will also be published in parallel with "workspace_startup". The "workspace_startup_component" and the "workspace_startup_apps" metrics are always published in parallel with "workspace_startup" regardless of whether a new Workspaces App instance has been created. Can be configured as a Histogram. |
"workspace_startup_apps" |
Gauge |
milliseconds | The time it took to load all apps in the Workspace. For web apps, this means that the DOMContentLoaded event has been fired. For native apps, this means that the app has completed its window registration within the io.Connect framework. Measures the interval from initiating the loading of the first app in the Workspace until all apps have been loaded. You can use the "complexLoad" attribute to determine whether all apps in the Workspace have been started as new app instances, or one or more of them has been included in the Workspace as an already existing window. Can be configured as a Histogram. Available only in io.Connect Desktop. Available since io.Connect Desktop 9.10. |
"workspace_startup_component" |
Gauge |
milliseconds | The time it took to create and render the <Workspaces /> component within an already existing Workspaces App instance (i.e., when the Workspace is created or restored in an already existing Workspaces App instance). Measures the interval from initiating the initialization of the <Workspaces /> component inside the Workspaces App instance until the component is fully rendered and interactive. Can be configured as a Histogram. Available only in io.Connect Desktop. Available since io.Connect Desktop 9.10. |
"workspace_startup_frame" |
Gauge |
milliseconds | The total time it took to load the Workspace App instance. This is measured from initiating the request for creating or restoring the Workspace until the Workspaces App instance has been fully loaded and the <Workspaces /> component has been rendered. This metric is published only when a new Workspaces App instance is being created and is published in parallel with the following sub-metrics that measure the separate intervals for completing the consecutive stages of initializing a Workspaces App instance: "workspace_startup_frame_init", "workspace_startup_frame_page_load", and "workspace_startup_frame_workspace_render". Can be configured as a Histogram. Available only in io.Connect Desktop. Available since io.Connect Desktop 9.10. |
"workspace_startup_frame_init" |
Gauge |
milliseconds | Published in parallel with the "workspace_startup_frame" metric. Measures the interval from initiating the creation of the underlying browser window until the browser window is ready for loading the web page of the Workspaces App instance. Can be configured as a Histogram. Available only in io.Connect Desktop. Available since io.Connect Desktop 9.10. |
"workspace_startup_frame_page_load" |
Gauge |
milliseconds | Published in parallel with the "workspace_startup_frame" metric. Measures the interval from initiating the navigation to the web page of the Workspaces App instance (after the underlying browser window has been created) until the DOMContentLoaded event is fired for the web page. Can be configured as a Histogram. Available only in io.Connect Desktop. Available since io.Connect Desktop 9.10. |
"workspace_startup_frame_workspace_render" |
Gauge |
milliseconds | Published in parallel with the "workspace_startup_frame" metric. Measures the interval from initiating the initialization of the <Workspaces /> component inside the Workspaces App instance (after the web page of the Workspaces App instance has already been loaded) until the component is fully rendered and interactive. Can be configured as a Histogram. Available only in io.Connect Desktop. Available since io.Connect Desktop 9.10. |
"workspace_stopped" |
Counter |
number | The number of times a Workspace has been stopped during each platform session. |
⚠️ Note that the platform doesn't publish metrics related to Workspaces that are dragged out of existing Workspaces App instances or metrics related to Workspaces App instances that are still part of the Frame pool (the configurable pool of cached Workspaces App instances that is used by the platform for improving Workspaces performance and user experience).
⚠️ Note that if more than one instance of the same Workspace has been loaded (regardless of whether in a new Workspaces App instance or in an already existing one), the
"workspace_startup","workspace_startup_component", and"workspace_startup_apps"metrics will show information only about the last loaded instance of the Workspace.
The "workspace_count", "workspace_selected", "workspace_started", and "workspace_stopped" metrics have the following additional attributes:
| Attribute | Description |
|---|---|
"layout" |
The name of the Workspace for which the respective metric was published. The value will be "unknown" if not tied to a specific Workspace Layout - e.g., in case of creating a new Workspace, or initialization of a Workspaces App instance with multiple Workspaces in it. |
The "workspace_startup" metric and all its sub-metrics have the following additional attributes:
| Attribute | Description |
|---|---|
"complexLoad" |
Differentiates between launching Workspaces in which all apps are loaded as new instances (this is the normal loading scenario, i.e. the value of "complexLoad" will be "false"), and Workspaces in which one or more of the app windows are already existing windows that have been included in the Workspace (this is the complex loading scenario, i.e. the value of "complexLoad" will be "true"). If "complexLoad" is "true", the time for loading the Workspace may be slightly or significantly decreased and it's important to keep in mind that this won't be due to performance optimizations, but due to loading one or more already existing app instances into the Workspace which is a faster procedure than starting new app instances. Available only in io.Connect Desktop. Available since io.Connect Desktop 9.10. |
"includesFrameCreation" |
If the value of this attribute is "true", this means that the measurement includes the time it took to initialize a Workspaces App instance (e.g., if the Workspace has been loaded into an already existing Workspaces App instance, the value of this attribute will be "false"). Available only in io.Connect Desktop. Available since io.Connect Desktop 9.10. |
"layout" |
The name of the Workspace for which the respective metric was published. The value will be "unknown" if not tied to a specific Workspace Layout - e.g., in case of creating a new Workspace, or initialization of a Workspaces App instance with multiple Workspaces in it. |
Layouts
The following table lists the available metrics related to Global Layouts performance:
| Metric | Instrument Type | Unit | Description |
|---|---|---|---|
"layout_startup" |
Gauge |
milliseconds | The time it took to restore a Global Layout. Measures the interval from initiating the operation for restoring the Global Layout until all its components (individual windows, window groups, Workspaces) have been loaded. Can be configured as a Histogram. |
The "layout_startup" metric has the following additional attributes:
| Attribute | Description |
|---|---|
"layout" |
The name of the Global Layout for which the "layout_startup" metric was published. |
Custom Metrics
Available since io.Connect Desktop 10.1
⚠️ Note that custom metrics are currently available only in io.Connect Desktop.
The following table lists the available custom metrics that can be published via the Insights API:
| Metric | Instrument Type | Description |
|---|---|---|
"custom_counter" |
Counter |
A monotonically increasing counter that tracks cumulative totals. Use the add() method to increment the metric value by a given amount. |
"custom_gauge" |
Gauge |
A point-in-time measurement that records the current value. Use the record() method to report the current measurement. |
"custom_histogram" |
Histogram |
A distribution of measurements aggregated into configurable buckets. Use the record() method to capture individual measurements. |
"custom_observable_counter" |
ObservableCounter |
Asynchronous monotonically increasing counter. The OpenTelemetry SDK periodically invokes a provided callback to collect the current cumulative total. |
"custom_observable_gauge" |
ObservableGauge |
Asynchronous point-in-time measurement. The OpenTelemetry SDK periodically invokes a provided callback to collect the current value. |
"custom_observable_up_down_counter" |
ObservableUpDownCounter |
Asynchronous bidirectional counter. The OpenTelemetry SDK periodically invokes a provided callback to collect a cumulative value that can increase or decrease. |
"custom_up_down_counter" |
UpDownCounter |
A bidirectional counter that tracks quantities which can go up and down. Use the add() method with positive or negative values. |