{ "$id": "http://glue42.com/gd/otelApplication.json", "$schema": "http://json-schema.org/draft-06/schema#", "title": "IO.Insights Configuration Schema", "description": "JSON schema for IO.Insights", "type": "object", "$comment": "Created after commit 73b0cbcc78c8eb5c657508c58b101b1ade8dfbe6", "properties": { "enabled": { "type": "boolean", "description": "Whether library is enabled. If disabled, API is still usable, but methods are no-ops." }, "addHardwareDataToAttributes": { "type": "boolean", "description": "If `true`, the platform will add CPU, memory, and OS information to the resource attributes of the published signals." }, "definitiveInstance": { "type": "boolean", "description": "Internal library property." }, "platformInstance": { "type": "boolean", "description": "Internal library property." }, "registerControlMethods": { "type": "boolean", "description": "Internal library property." }, "requestSettings": { "type": "boolean", "description": "For Node applications: whether to attempt to request io.Insights settings from the platform when initializing." }, "applicationName": { "type": "string", "description": "Application name to use in telemetry information. By default, it's populated by io.Connect." }, "registerGlobalOTELObjects": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "force" ] } ], "description": "Whether the library should register its own instances of the OTEL SDK global objects, e.g. MeterProvider. This is useful for controlling which instance of the SDK is used, in applications that initialize their own SDK. If `true`, the io.Insights library will register its own OTEL SDK global object instances if none are already registered - an already initialized SDK is used in preference to the one initialized by io.Insights. If `\"force\"`, the library registers its own instances unconditionally, regardless of any existing registrations. If `false`, the library will not register its own instances and requires an already initialized OTEL SDK instance." }, "ssoAuth": { "type": "object", "description": "Settings for injecting the io.Connect SSO login information into OpenTelemetry export requests when the platform is configured to use the Electron networking stack.", "properties": { "enabled": { "type": "boolean", "description": "If `true`, will instruct the platform to use the io.Connect SSO login information when making OpenTelemetry export requests. This only applies to OpenTelemetry exports performed after SSO completes." }, "useAuthHeader": { "type": "boolean", "description": "If `true`, will use a custom `auth` header to send the entire io.Connect SSO authorization object as a JSON string." }, "useRawToken": { "type": "boolean", "description": "If `true`, will use the io.Connect SSO token as-is. If `false`, \"Bearer \" will be prepended to the token if it lacks the prefix." } }, "additionalProperties": true }, "finalExportTimeoutMs": { "description": "Interval in milliseconds to wait for any remaining telemetry data to be exported during shutdown of the platform. This is the maximum awaiting interval and the platform may shutdown before it expires if all telemetry data has already been published.", "type": "number" }, "finalExportGracePeriodMs": { "description": "Interval in milliseconds to wait for any remaining telemetry data to be published by any apps before proceeding with the platform shutdown.", "type": "number" }, "errorlessMode": { "type": "boolean", "description": "Enable errorless mode operation. If `true`, the library will swallow all errors, instead of propagating them." }, "logSettingsOnStartup": { "type": "boolean", "description": "If the library should log the settings used to initialize it." }, "failOnInitError": { "type": "boolean", "description": "If failure to initialize library will throw upstream error." }, "platformVersion": { "type": "string", "description": "If provided, this value will be added to the metrics and span attributes and to the span filtering context." }, "suppressDoubleInitializationWarnings": { "type": "boolean", "description": "Suppress double initialization warnings from the OTEL SDK." }, "serviceName": { "type": "string", "description": "If provided, this value will be added to the metrics and traces service.name attribute, unless an OTEL service object has been provided to the library with a different setting." }, "serviceId": { "type": "string", "description": "If provided, this value will be added to the metrics and traces service.instance.id attribute." }, "serviceVersion": { "type": "string", "description": "If provided, this value will be added to the metrics and traces service.version attribute." }, "userId": { "type": "string", "description": "If provided, this value will be added to the metrics and traces user.id attribute." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional headers to send in HTTP requests, e.g. when using HTTP exporters." }, "additionalAttributes": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "object", "array", "null" ] }, "description": "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%`)." }, "additionalResourceAttributes": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "object", "array", "null" ] }, "description": "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%`)." }, "addResourceAttributesToAttributes": { "type": "boolean", "description": "Whether to add resource attributes to signal attributes." }, "traces": { "$ref": "#/definitions/TracesSettings", "description": "Configuration for traces." }, "metrics": { "$ref": "#/definitions/MetricsSettings", "description": "Configuration for metrics." }, "logs": { "$ref": "#/definitions/LogsSettings", "description": "Configuration for logs." } }, "additionalProperties": true, "definitions": { "TracesSettings": { "type": "object", "description": "Configuration settings for traces.", "properties": { "enabled": { "type": "boolean", "description": "Whether tracing functionality is enabled. If disabled, API is still usable, but methods are no-ops." }, "rootPropagationInfo": { "$ref": "#/definitions/PropagationInfo", "description": "Property for internal use." }, "countMetric": { "type": [ "string", "null" ], "description": "Name of span hit counter metric, set to null to disable." }, "durationMetric": { "type": [ "string", "null" ], "description": "Name of span duration histogram metric, set to null to disable." }, "resultMetric": { "type": [ "string", "null" ], "description": "Name of span result counter metric, set to null to disable." }, "instrumentRequests": { "oneOf": [ { "type": "boolean" }, { "$ref": "#/definitions/InstrumentRequestsConfig" } ], "description": "If `true`, or `enabled` is `true`, io.Insights will instrument and trace XMLHttpRequest and fetch() requests automatically. When enabled, the pre-init recorder (when installed) also captures requests from page start - opt out of that with the configuration object's `preInit: false`." }, "instrumentAppLoad": { "type": "boolean", "description": "Deprecated - use `instrumentAppStartup` instead. If `true`, io.Insights will instrument and trace the application loading process automatically." }, "instrumentDocumentLoad": { "type": "boolean", "description": "Deprecated - use `instrumentAppStartup` instead. If `true`, io.Insights will instrument and trace the steps of the document load and initialization process automatically." }, "instrumentAppStartup": { "type": "boolean", "description": "If `true`, io.Insights will trace the application startup automatically: a root `interopio.api.appStartup` span starting at the runtime's time origin, with child spans for the navigation phases (DNS, connect, TLS, request, response, DOM parsing, event handlers), the slowest resource loads, paint marks, long tasks and lifecycle transitions (visibility changes, back/forward-cache restores, freezes), plus web vitals (FCP, LCP, CLS) and navigation KPIs as attributes. Spans created during the startup window are nested under this root. Also works in NodeJS: the root span opens at process start and the startup-window nesting applies, but the browser performance-timeline children are not produced; the window closes on `startupParentSpanTimeoutMs` or an explicit `startupTraceFinished()` call." }, "instrumentErrors": { "oneOf": [ { "type": "boolean" }, { "$ref": "#/definitions/ErrorInstrumentationConfig" } ], "description": "If `true` (or a configuration object), uncaught errors and unhandled promise rejections will be published as error spans (`interopio.api.instrumentation.error` / `.unhandledRejection`), including errors captured before initialization by the pre-init recorder. Capped per session to guard against error storms. When enabled, the app startup trace defers its own error capture to this instrumentation, and the pre-init recorder (when installed) captures errors from page start - opt out of that with the configuration object's `preInit: false`. Also works in NodeJS via `process.uncaughtExceptionMonitor`, a behavior-preserving hook: the process still crashes exactly as it would have. The span processors are force-flushed immediately, so the crash span is exported whenever anything keeps the process alive past the crash (an application `uncaughtException` handler, a graceful shutdown); on a hard crash the export cannot complete and the span is lost with the process. Crash-grade unhandled rejections are reported under Node's default `unhandled-rejections=throw` mode; non-crashing rejections are deliberately not observed in Node, because subscribing to them would suppress Node's default crash semantics." }, "instrumentResources": { "oneOf": [ { "type": "boolean" }, { "$ref": "#/definitions/ResourceInstrumentationConfig" } ], "description": "If `true` (or a configuration object), resource loads (scripts, stylesheets, images, fonts, etc.) will be published as spans (`interopio.api.instrumentation.resource`) with their real timings from the resource timing buffer, including resources loaded before initialization, a `cacheState` attribute (`hit`, `revalidated`, `network`, or `unknown` - cross-origin resources without a Timing-Allow-Origin header withhold cache provenance), and the nonzero connection-phase timings (dns/connect/tls/ttfb). By default fetch/XHR resources are excluded (the request instrumentation covers them in more detail; see `skipRequests`), as are telemetry uploads. Optional histogram/counter metrics can be enabled via the configuration object. When enabled, the app startup trace defers its slowest-resource child spans to this instrumentation." }, "instrumentNavigation": { "type": "boolean", "description": "If `true`, in-page (SPA) navigations - history pushState/replaceState, popstate and hashchange - will be published as spans (`interopio.api.instrumentation.navigation`) with the sanitized from/to URLs. Same-URL state updates are not reported." }, "instrumentEventLoop": { "oneOf": [ { "type": "boolean" }, { "$ref": "#/definitions/EventLoopInstrumentationConfig" } ], "description": "If `true` (or a configuration object), event loop responsiveness is instrumented: slow input events (Event Timing API) and main-thread-blocking long frames (Long Animation Frames API, falling back to Long Tasks) are published as spans (`interopio.api.instrumentation.inputDelay` / `.eventLoopBlocking`), with the input-delay spans carrying the same element-describing attributes as the clickstream spans. Optional histogram metrics can be enabled via the configuration object. Entries recorded before initialization are replayed from the performance buffers." }, "instrumentWebSockets": { "oneOf": [ { "type": "boolean" }, { "$ref": "#/definitions/WebSocketInstrumentationConfig" } ], "description": "If `true` (or a configuration object), WebSocket connections are instrumented: each connection is published as a span (`interopio.api.instrumentation.webSocket`) covering its whole lifetime - construction until close - with the connect duration, negotiated protocol, close code/reason/wasClean, and message/byte totals in both directions. Abnormal closures (code 1006) and connection failures mark the span as ERROR. Optional message/byte counters and a connect-duration histogram can be enabled via the configuration object. The io.Connect gateway connection is tracked by default (its lifecycle is platform-health telemetry - exclude it with `ignoreGateway`); use `ignorePattern` for other infrastructure sockets. When the pre-init module is loaded, sockets are tracked from page start (opt out with `preInit: false`): connections closed before initialization become retroactive spans, and still-open ones are adopted with spans starting at their true construction time." }, "instrumentWebVitals": { "oneOf": [ { "type": "boolean" }, { "$ref": "#/definitions/WebVitalsInstrumentationConfig" } ], "description": "If `true` (or a configuration object), session-level Web Vitals are tracked: CLS (cumulative layout shift, session-window algorithm), INP (interaction to next paint, the web-vitals estimation over Event Timing entries) and the final LCP. A `interopio.api.instrumentation.webVitals` span with the current values is published each time the page becomes hidden (when the values changed), and optional histogram metrics record one terminal sample per page at pagehide. Complements the startup trace's perf.vitals, which cover only the startup window." }, "filters": { "type": "array", "items": { "$ref": "#/definitions/SpanFilter" }, "description": "Array of filter entries used to determine whether a particular operation will create a tracing span." }, "useDefaultFilters": { "type": "boolean", "description": "If true, use a predefined list of filters for well-known platform traces." }, "defaultFilters": { "type": "array", "description": "This property is for internal use only.", "items": { "$ref": "#/definitions/SpanFilter" } }, "sampling": { "type": "array", "items": { "$ref": "#/definitions/SamplingSettings" }, "description": "Array of sampling setting entries used to determine whether a span will be sampled." }, "defaults": { "$ref": "#/definitions/SpanCreationOptions", "description": "Default settings if appropriate entries aren't found in 'filters' and 'sampling' collections." }, "hybridContextMode": { "type": "boolean", "description": "If `true`, the library will use both the ContextManager provided by the OTEL SDK and the `Traces.currentTracingState` property to resolve the current context. See the documentation of the `useOTELContextManager` property for more details." }, "useOTELContextManager": { "type": "boolean", "description": "If `true`, the library will use the ContextManager provided by the active OTEL SDK to manage and derive propagation information to ensure spans created across asynchronous operations are properly nested." }, "url": { "type": "string", "format": "uri", "description": "If an OTEL TraceProvider isn't provided to the library, it will initialize its own. If 'url' is specified, TracerProvider will have an OTLPTraceExporter using this destination URL." }, "keepAlive": { "type": "boolean", "description": "Whether to keep the connection alive when sending traces." }, "publishInterval": { "type": "number", "description": "Interval in milliseconds between trace export batches." }, "compression": { "type": "string", "description": "Compression algorithm to use when exporting (none or gzip)." }, "concurrencyLimit": { "type": "integer", "minimum": 1, "description": "Maximum number of concurrent trace export requests." }, "timeoutMillis": { "type": "number", "minimum": 0, "description": "Maximum time the OTLP exporter will wait for each batch export." }, "clickstream": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "nested", "sibling" ] }, { "$ref": "#/definitions/ClickstreamTraceConfig" } ], "description": "Whether the clickstream trace will be enabled. false - clickstream trace is disabled. true - same as sibling. nested - clickstream trace is enabled and each subsequent span is a child span of the previous one. sibling - clickstream trace is enabled and each subsequent span is a child of the same initial span." }, "userJourney": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "nested", "sibling" ] }, { "$ref": "#/definitions/UserJourneyTraceConfig" } ], "description": "Whether the user journey trace will be enabled." }, "startupParentSpanTimeoutMs": { "description": "How long after application startup will any traced operations automatically be nested under the application startup trace. Without a timeout the startup window only closes on an explicit `startupTraceFinished()` call (or the window's loader signal) - the root span stays open, and unexported, until then.", "type": "number" }, "closeTrace": { "description": "If `true`, the application will create a span with the name `interopio.api.application.close` when it's being closed. This functionality requires close handlers to be enabled in the application configuration.", "type": "boolean" }, "exporterSettings": { "$ref": "#/definitions/OTLPExporterNodeConfigBase", "description": "If an OTEL TraceProvider isn't provided to the library, it will initialize its own. If 'url' is specified, TracerProvider will have an OTLPTraceExporter with 'url' as destination URL and 'exporterSettings' as additional config." }, "otlpExporterConfig": { "$ref": "#/definitions/OTLPExporterNodeConfigBase", "description": "Deprecated. Use exporterSettings." }, "tracerProviderSettings": { "$ref": "#/definitions/TracerConfig", "description": "OTEL TracerConfig - provides an interface for configuring a Basic Tracer." }, "processorSettings": { "$ref": "#/definitions/BufferConfig", "description": "Configuration for the batch span processor buffer settings." }, "parentNameLimit": { "type": "number", "description": "Maximum length for parent operation names in span hierarchies." }, "console": { "type": "boolean", "description": "If true, TracerProvider will have a ConsoleTraceExporter." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional headers to send in HTTP requests, e.g. when using HTTP exporters." }, "addResourceAttributesToAttributes": { "type": "boolean", "description": "Whether to add resource attributes to span attributes." }, "additionalAttributes": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "object", "array", "null" ] }, "description": "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?literalDefaultValue%`)." }, "additionalResourceAttributes": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "object", "array", "null" ] }, "description": "Additional attributes to publish as part of the OTEL resource definition, 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?literalDefaultValue%`)." } }, "additionalProperties": true }, "PropagationInfo": { "type": "object", "properties": { "traceparent": { "type": "string" }, "tracestate": { "type": "string" }, "forceTracing": { "type": "boolean" } }, "additionalProperties": false, "description": "Span and trace information that can be used to manually control the nesting of a newly created span." }, "SpanCreationOptionsShape": { "type": "object", "description": "Options that can be used when creating a span.", "properties": { "enabled": { "type": "boolean", "description": "Whether the span will be created or will be a no-op." }, "otelSpanOptions": { "$ref": "#/definitions/SpanOptions", "description": "OTEL span options" }, "stopPropagationIfSpanIsDisabled": { "type": "boolean", "description": "If a tracing span is disabled by filter, setting this to true will stop the propagation of trace nesting info across it." }, "level": { "type": "string", "enum": [ "OFF", "LOWEST", "DIAGNOSTIC", "DEBUG", "INFO", "WARN", "HIGHEST" ], "description": "Default span attribute verbosity level." }, "addContextToTrace": { "type": "boolean", "description": "Whether the filtering context will be added as span attributes to the span." }, "autoSetSuccessStatus": { "type": "boolean", "description": "Whether the span's status will be set to OK on completion, if it's still UNSET." }, "sample": { "oneOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "boolean" } ], "description": "Default sampling setting/probability." }, "disablePropagation": { "type": "boolean", "description": "Whether the span will not inject its propagation info into data transfer objects for span nesting across system boundaries." }, "disableNesting": { "type": "boolean", "description": "Forces the span to create a new trace." }, "log": { "description": "If true, enabled spans will also be published as log entries using the `traceLogger` passed to the builder instance when building the Traces module.", "type": "boolean" }, "logOnDisabledSpans": { "type": "boolean", "description": "If true, disabled spans will also be published as log entries using the `traceLogger` passed to the builder instance when building the Traces module." }, "countMetric": { "type": "boolean", "description": "Whether the span will be counted in the insights_trace_count metric." }, "countMetricOnDisabledSpans": { "type": "boolean", "description": "Whether the span will be counted in the insights_trace_count metric if disabled. See TracesSettings.countMetric." }, "resultMetric": { "type": "boolean", "description": "Whether the span will be recorded in the insights_trace_result metric." }, "resultMetricOnDisabledSpans": { "type": "boolean", "description": "Whether the span will be recorded in the insights_trace_result metric if disabled. See TracesSettings.resultMetric." }, "durationMetric": { "type": "boolean", "description": "Whether the span will be measured in the insights_trace_duration metric." }, "durationMetricOnDisabledSpans": { "type": "boolean", "description": "Whether the span will be measured in the insights_trace_duration metric if disabled. See TracesSettings.durationMetric." }, "canBeRoot": { "type": "boolean", "description": "Whether the span will be able to start a new trace." }, "maxAttributeDepth": { "type": "integer", "minimum": 0, "description": "How deep addData method should recurse into objects when adding attributes to spans." }, "forceChildTracing": { "type": "boolean", "description": "If true, any child spans will be forced to be traced, even if their span filter configuration is set to not enabled." }, "minDurationMs": { "type": "number", "minimum": 0, "description": "If specified, spans whose duration is lower than this will not be sampled." }, "overrideDefaultFilters": { "type": "boolean", "description": "If `true`, this filter rule will be matched before any default filters provided by io.Connect. The default filters are usually meant to reduce verbosity by not tracing some internal operations by default, but you can use this property to force them to be traced.If `false`, default filters will be matched before this filtering rule." } }, "additionalProperties": true }, "SpanCreationOptions": { "description": "Options that can be used when creating a span, with default values applied.", "allOf": [ { "$ref": "#/definitions/SpanCreationOptionsShape" }, { "properties": { "enabled": { "default": true }, "stopPropagationIfSpanIsDisabled": { "default": false }, "level": { "default": "INFO" }, "addContextToTrace": { "default": true }, "autoSetSuccessStatus": { "default": false }, "sample": { "default": true }, "disablePropagation": { "default": false }, "log": { "default": false }, "logOnDisabledSpans": { "default": false }, "countMetric": { "default": false }, "countMetricOnDisabledSpans": { "default": false }, "resultMetric": { "default": false }, "resultMetricOnDisabledSpans": { "default": false }, "durationMetric": { "default": false }, "durationMetricOnDisabledSpans": { "default": false }, "canBeRoot": { "default": true }, "maxAttributeDepth": { "default": 5 }, "forceChildTracing": { "default": false }, "minDurationMs": { "default": 0 }, "overrideDefaultFilters": { "default": false } } } ] }, "SpanFilter": { "type": "object", "description": "Filter entry that can match a span to control its settings.", "allOf": [ { "$ref": "#/definitions/SpanCreationOptionsShape" }, { "type": "object", "properties": { "source": { "type": "string", "description": "Specifies the source string used for matching spans. Start string with '#' for case-insensitive regex match." }, "context": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean" ] }, "description": "Specifies the filtering context values used for matching spans. Start strings with '#' for case-insensitive regex match." }, "injectOTELHeaders": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "same-origin", "all-origins" ] } ], "description": "For spans instrumenting HTTP requests, controls automatic injection of the trace context headers (produced by the configured propagator - W3C `traceparent`/`tracestate` by default). `same-origin` injects into same-origin requests only: adding a custom header to a cross-origin request triggers a CORS preflight, and a server that does not allow the header would fail the request itself. `all-origins` injects into every request this filter matches, including cross-origin ones - use it in filters whose `context.url` matches origins known to accept the headers. The legacy value `true` is treated as `same-origin`. Applies to the fetch/XHR instrumentation and to the platform's Electron net.request instrumentation; the main process has no origin, so `same-origin` never matches there - opt platform backends in with `all-origins` filters scoped by `context.url` (there is no CORS preflight risk for main-process requests)." }, "forceStatus": { "type": "number", "enum": [ 0, 1, 2 ], "description": "If set, forces the span to have this status code (0 - UNSET, 1 - OK, 2 - ERROR), regardless of anything set explicitly or any errors caught automatically." } }, "additionalProperties": true } ] }, "SamplingSettings": { "type": "object", "description": "Settings used to control the sampling probability of spans.", "properties": { "name": { "type": "string", "description": "Span name to determine if span will match this sampling setting entry. Start string with '#' for case-insensitive regex match." }, "attributes": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean" ] }, "description": "Span attributes that determine if span will match this sampling setting entry. Start strings with '#' for case-insensitive regex match." }, "context": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean" ] }, "description": "Context values that determine if span will match this sampling setting entry. Start strings with '#' for case-insensitive regex match." }, "sample": { "oneOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "boolean" } ], "description": "Probability that span will be sampled, based on its traceId. If true: will be sampled. If false: will not be sampled. If number between 0 and 1: has this probability of being sampled." } }, "additionalProperties": true }, "MetricsSettings": { "type": "object", "description": "Configuration settings for metrics.", "properties": { "enabled": { "type": "boolean", "description": "Whether metrics functionality is enabled. If disabled, API is still usable, but methods are no-ops." }, "defaultMetricsEnabled": { "type": "boolean", "description": "Deprecated. Use platformMetricsEnabled." }, "platformMetricsEnabled": { "oneOf": [ { "type": "string", "enum": [ "only-explicit" ] }, { "type": "boolean" } ], "description": "Whether to enable automatic collection of platform-level metrics (CPU, memory, etc.). A value of 'only-explicit' means only metrics listed explicitly in the configuration will be enabled." }, "defaultPublishingSettings": { "$ref": "#/definitions/MetricPublishingSettings", "description": "Default publishing settings for metrics." }, "maxAttributeDepth": { "type": "integer", "minimum": 0, "description": "How deep the library should recurse into objects when adding labels to metrics." }, "metrics": { "type": "array", "items": { "$ref": "#/definitions/MetricSettings" }, "description": "Array of individual metric configurations to collect." }, "url": { "type": "string", "format": "uri", "description": "The destination URL for exporting metrics via OTLP." }, "publishInterval": { "type": "number", "minimum": 0, "description": "Interval in milliseconds between metric export batches." }, "compression": { "type": "string", "description": "Compression algorithm to use when exporting (none or gzip)." }, "hostname": { "type": "string", "description": "Hostname to include in exported metrics." }, "keepAlive": { "type": "boolean", "description": "Whether to use HTTP keep-alive connections for metric exports." }, "concurrencyLimit": { "type": "integer", "minimum": 1, "description": "Maximum number of concurrent metric export requests." }, "timeoutMillis": { "type": "number", "minimum": 0, "description": "Maximum time the OTLP exporter will wait for each batch export." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional headers to send in HTTP requests." }, "addResourceAttributesToAttributes": { "type": "boolean", "description": "Whether to add resource attributes to metric data point attributes." }, "additionalAttributes": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "object", "array", "null" ] }, "description": "Additional metrics 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?literalDefaultValue%`)." }, "additionalResourceAttributes": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "object", "array", "null" ] }, "description": "Additional attributes to publish as part of the OTEL resource definition, 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?literalDefaultValue%`)." }, "meter": { "type": "object", "description": "Partial MetricsSettings for meter configuration." }, "filters": { "type": "array", "items": { "$ref": "#/definitions/MetricFilter" }, "description": "Array of filter rules to determine which metrics should be collected and exported." }, "useDefaultFilters": { "type": "boolean", "description": "Whether to apply predefined default filters for platform metrics." }, "defaultFilters": { "type": "array", "description": "This property is for internal use only.", "items": { "$ref": "#/definitions/MetricDefaultFilter" } }, "useLegacyWorkspaceStartupMetric": { "type": "boolean", "description": "If `true`, workspace_startup will be published as the legacy histogram metric from the io.Insights beta releases." }, "meterProviderSettings": { "type": "object", "description": "Options to use when creating the MeterProvider for exporting metrics.", "additionalProperties": true }, "readerSettings": { "type": "object", "description": "Options to use when creating the PeriodicExportingMetricReader for exporting metrics.", "additionalProperties": true }, "exporterSettings": { "allOf": [ { "$ref": "#/definitions/OTLPExporterNodeConfigBase" }, { "$ref": "#/definitions/OTLPMetricExporterOptions" } ], "description": "Options to use when creating the OTLPMetricExporter for exporting metrics." } }, "additionalProperties": true }, "MetricSettings": { "type": "object", "description": "Configuration for an individual metric.", "properties": { "enabled": { "type": "boolean", "description": "Whether this metric is enabled for collection." }, "type": { "$ref": "#/definitions/MetricType", "description": "The type of metric to collect." }, "name": { "type": "string", "description": "The name of the metric." }, "description": { "type": "string", "description": "A human-readable description of the metric." }, "platformVersion": { "type": "string", "description": "The platform version to associate with this metric." }, "user": { "type": "string", "description": "The user identifier to associate with this metric." }, "unit": { "type": "string", "description": "The unit of measurement for this metric (e.g., 'ms', 'bytes')." }, "buckets": { "type": "array", "items": { "type": "number" }, "description": "Histogram bucket boundaries for histogram-type metrics." }, "baseMetricType": { "type": "string", "enum": [ "histogram", "gauge" ], "description": "The base OpenTelemetry metric type to use." }, "additionalAttributes": { "description": "Additional attributes to add to this metric.", "type": "object", "additionalProperties": true }, "publishingSettings": { "$ref": "#/definitions/MetricPublishingSettings", "description": "Controls the publishing of the metric." } }, "additionalProperties": true }, "MetricPublishingSettings": { "type": "object", "description": "Controls the publishing of the metric.", "properties": { "sample": { "oneOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "boolean" } ], "description": "Defines sampling probability for the metric." }, "attributeSettings": { "type": "object", "description": "Controls the publishing of specific attributes.", "additionalProperties": { "$ref": "#/definitions/MetricAttributeSettings" } } }, "additionalProperties": false }, "MetricAttributeSettings": { "type": "object", "description": "Controls the publishing of specific attributes.", "properties": { "reduceModality": { "type": "number", "description": "If specified, the attribute value will be hashed and truncated to this length to reduce the modality of the published metrics. Set to 0 to drop the attribute entirely. Set to -1 to override any defaults." } }, "additionalProperties": false }, "MetricDefaultFilter": { "description": "Default filter configuration for metrics.", "allOf": [ { "$ref": "#/definitions/MetricPublishingSettings" }, { "type": "object", "properties": { "type": { "$ref": "#/definitions/MetricType", "description": "The type of metrics this filter applies to." }, "enabled": { "type": "boolean", "description": "Whether metrics matching this filter are enabled." }, "sample": { "oneOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "boolean" } ], "description": "Sampling probability for the metric." }, "overrideDefaultFilters": { "type": "boolean", "description": "If `true`, this filter rule will be matched before any default filters provided by io.Connect. The default filters are usually meant filter out non-representative operations (e.g. partial workspace loads), but you can use this property to force them to be measured. If `false`, default filters will be matched before this filtering rule." }, "attributes": { "type": "object", "description": "Matches the attributes attached to a metric value. Not all metrics have all attribute values.", "properties": { "complexLoad": { "type": "boolean", "description": "Indicates whether the workspace loading involved a complex operation where existing apps are added to a new workspace. This attribute can be used to filter out metrics." }, "includesFrameCreation": { "type": "boolean", "description": "Indicates whether the metric includes the time to create and load the Workspace Frame App when the workspace is opened in a new frame." } }, "additionalProperties": true } } } ] }, "MetricFilter": { "description": "Metric filters that can be specified as part of a specific metric.", "allOf": [ { "$ref": "#/definitions/MetricDefaultFilter" }, { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the matched metric." }, "type": { "$ref": "#/definitions/MetricType", "description": "The type of the matched metric." } }, "additionalProperties": true } ] }, "MetricType": { "type": "string", "description": "Enumeration of supported metric types for collection.", "enum": [ "app_count", "app_cpu", "app_crash", "app_duration", "app_duration_soft", "app_error", "app_memory", "app_started", "app_startup", "app_stopped", "layout_startup", "workspace_count", "workspace_selected", "workspace_started", "workspace_stopped", "workspace_startup_legacy", "workspace_startup", "workspace_startup_frame", "workspace_startup_frame_init", "workspace_startup_frame_page_load", "workspace_startup_frame_workspace_render", "workspace_startup_component", "workspace_startup_apps", "platform_error", "platform_startup", "system_cpu", "system_memory", "custom_gauge", "custom_observable_gauge", "custom_observable_counter", "custom_observable_up_down_counter", "custom_counter", "custom_histogram", "custom_up_down_counter", "null" ] }, "LogsSettings": { "type": "object", "description": "Configuration settings for logs.", "properties": { "enabled": { "type": "boolean", "description": "Whether logging functionality is enabled. If disabled, API is still usable, but methods are no-ops." }, "url": { "type": "string", "format": "uri", "description": "OTLP logs exporter endpoint URL." }, "keepAlive": { "type": "boolean", "description": "Whether to keep the connection alive when sending logs." }, "publishInterval": { "type": "number", "description": "Interval in milliseconds between logs export batches." }, "compression": { "type": "string", "description": "Compression algorithm to use when exporting (none or gzip)." }, "concurrencyLimit": { "type": "integer", "minimum": 1, "description": "Maximum number of concurrent logs export requests." }, "timeoutMillis": { "type": "number", "minimum": 0, "description": "Maximum time the OTLP exporter will wait for each batch export." }, "exporterSettings": { "$ref": "#/definitions/OTLPExporterNodeConfigBase", "description": "Settings for the OTLP exporter used to send logs." }, "processorSettings": { "$ref": "#/definitions/BatchLogRecordProcessorBrowserConfig", "description": "Settings for batching log records before export." }, "loggerProviderSettings": { "$ref": "#/definitions/LoggerProviderConfig", "description": "Configuration for the logger provider." }, "levelCountMetric": { "type": [ "string", "null" ], "description": "Name of log level counter metric, set to null to disable." }, "startupTraceAssociationTimeoutMs": { "type": "number", "description": "How long after application startup will any log entries automatically be associated with the application startup trace." }, "useDefaultFilters": { "type": "boolean", "description": "If true, use a predefined list of filters for well-known platform logs." }, "maxAttributeDepth": { "type": "integer", "minimum": 0, "description": "How deep the library should recurse into objects when adding labels to logs." }, "filters": { "type": "array", "items": { "$ref": "#/definitions/LogFilter" }, "description": "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." }, "defaults": { "$ref": "#/definitions/LogOptions", "description": "Default settings if appropriate entries aren't found in 'filters' collection." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional headers to send in HTTP requests, e.g. when using HTTP exporters." }, "addResourceAttributesToAttributes": { "type": "boolean", "description": "Whether to add resource attributes to log entry attributes." }, "additionalAttributes": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "object", "array", "null" ] }, "description": "Additional logs 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?literalDefaultValue%`)." }, "additionalResourceAttributes": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "object", "array", "null" ] }, "description": "Additional attributes to publish as part of the OTEL resource definition, 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?literalDefaultValue%`)." } }, "additionalProperties": true }, "LogOptions": { "type": "object", "description": "Options for controlling log entry publishing and attribute filtering.", "properties": { "allowedAttributes": { "type": "array", "items": { "type": "string" }, "description": "List of allowed attributes for logging. If specified, any attributes missing from the list will be removed from the log entry before publishing it." }, "hideRegex": { "type": "string", "description": "Regex pattern for hiding sensitive log data. If specified, the log entry will have text matching this regex replaced with asterisks." }, "enabled": { "type": "boolean", "description": "Whether this log option is enabled. If `false`, the log entry will not be published." } }, "additionalProperties": true }, "LogFilter": { "type": "object", "description": "Used to match and control publishing of log entries.", "allOf": [ { "$ref": "#/definitions/LogOptions" }, { "type": "object", "properties": { "categoryName": { "type": "string", "description": "Used to match the category of the log entry." }, "severity": { "type": "string", "enum": [ "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL" ], "description": "Used to match the severity of the log entry." }, "bodyRegex": { "type": "string", "description": "Regex pattern used to match the text of the log entry." } }, "additionalProperties": true } ] }, "BufferConfig": { "type": "object", "description": "Interface configuration for a buffer used by batch processors", "properties": { "maxExportBatchSize": { "type": "number", "minimum": 1, "description": "The maximum batch size of every export. It must be smaller or equal to maxQueueSize." }, "scheduledDelayMillis": { "type": "number", "minimum": 0, "description": "The delay interval in milliseconds between two consecutive exports." }, "exportTimeoutMillis": { "type": "number", "minimum": 0, "description": "How long the export can run before it is cancelled." }, "maxQueueSize": { "type": "number", "minimum": 1, "description": "The maximum queue size. After the size is reached spans are dropped." } }, "additionalProperties": true }, "BatchLogRecordProcessorBrowserConfig": { "type": "object", "description": "Configuration for the batch log record processor, including browser-specific flush behaviour.", "allOf": [ { "$ref": "#/definitions/BufferConfig" }, { "type": "object", "properties": { "disableAutoFlushOnDocumentHide": { "type": "boolean", "description": "Disable flush when a user navigates to a new page, closes the tab or the browser, or, on mobile, switches to a different app. Auto flush is enabled by default." } }, "additionalProperties": true } ] }, "LoggerProviderConfig": { "type": "object", "description": "Configuration for OpenTelemetry Logger Provider", "properties": { "resource": { "type": "object", "description": "Resource associated with log telemetry" }, "forceFlushTimeoutMillis": { "type": "number", "minimum": 0, "description": "How long the forceFlush can run before it is cancelled." }, "logRecordLimits": { "$ref": "#/definitions/LogRecordLimits", "description": "Log record limits configuration" } }, "additionalProperties": true }, "LogRecordLimits": { "type": "object", "description": "Limits configuration for log records", "properties": { "attributeValueLengthLimit": { "type": "number", "minimum": 0, "description": "Maximum allowed attribute value size" }, "attributeCountLimit": { "type": "number", "minimum": 0, "description": "Number of attributes per LogRecord" } }, "additionalProperties": true }, "OTLPMetricExporterOptions": { "description": "Configuration options for the OTLP metric exporter.", "allOf": [ { "$ref": "#/definitions/OTLPExporterConfig" }, { "type": "object", "properties": { "temporalityPreference": { "type": "integer", "tsConstEnum": false, "description": "Preferred aggregation temporality for the OTLP metric exporter. DELTA (0) - prefer delta temporality. CUMULATIVE (1) - prefer cumulative temporality. LOWMEMORY (2) - use delta for most instruments, cumulative for up-down counters and observable up-down counters." } }, "additionalProperties": true } ] }, "OTLPExporterNodeConfigBase": { "type": "object", "description": "Node.js-specific base configuration for OTLP exporters.", "allOf": [ { "$ref": "#/definitions/OTLPExporterConfig" }, { "type": "object", "properties": { "keepAlive": { "type": "boolean", "description": "Whether to keep HTTP connections alive." }, "compression": { "type": "string", "description": "Compression algorithm to use when exporting (none or gzip)." }, "httpAgentOptions": { "type": "object", "description": "Options for the Node.js HTTP/HTTPS agent (http.AgentOptions | https.AgentOptions).", "additionalProperties": true } }, "additionalProperties": true } ] }, "OTLPExporterConfig": { "type": "object", "description": "Base configuration for OTLP exporters", "properties": { "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional headers to send with requests" }, "url": { "type": "string", "format": "uri", "description": "OTLP endpoint URL" }, "concurrencyLimit": { "type": "number", "minimum": 1, "description": "Maximum number of concurrent requests" }, "timeoutMillis": { "type": "number", "minimum": 0, "description": "Maximum time the OTLP exporter will wait for each batch export" } }, "additionalProperties": true }, "TracerConfig": { "type": "object", "description": "OTEL TracerConfig - provides an interface for configuring a Basic Tracer.", "properties": { "sampler": { "description": "Sampler to use for trace sampling decisions." }, "generalLimits": { "$ref": "#/definitions/GeneralLimits", "description": "General limits configuration" }, "spanLimits": { "$ref": "#/definitions/SpanLimits", "description": "Span limits configuration" }, "resource": { "description": "Resource to associate with traces." }, "idGenerator": { "description": "ID generator to use for generating trace and span IDs." }, "forceFlushTimeoutMillis": { "type": "number", "minimum": 0, "description": "How long the forceFlush can run before it is cancelled" }, "spanProcessors": { "type": "array", "items": true, "description": "List of SpanProcessor for the tracer" } }, "additionalProperties": true }, "GeneralLimits": { "type": "object", "description": "Global configuration limits of trace service", "properties": { "attributeValueLengthLimit": { "type": "number", "minimum": 0, "description": "Maximum allowed attribute value size" }, "attributeCountLimit": { "type": "number", "minimum": 0, "description": "Number of attributes per trace" } }, "additionalProperties": true }, "SpanLimits": { "type": "object", "description": "Global configuration of trace service", "properties": { "attributeValueLengthLimit": { "type": "number", "minimum": 0, "description": "Maximum allowed attribute value size" }, "attributeCountLimit": { "type": "number", "minimum": 0, "description": "Number of attributes per span" }, "linkCountLimit": { "type": "number", "minimum": 0, "description": "Number of links per span" }, "eventCountLimit": { "type": "number", "minimum": 0, "description": "Number of message events per span" }, "attributePerEventCountLimit": { "type": "number", "minimum": 0, "description": "Maximum number of attributes allowed per span event" }, "attributePerLinkCountLimit": { "type": "number", "minimum": 0, "description": "Maximum number of attributes allowed per span link" } }, "additionalProperties": true }, "SpanOptions": { "type": "object", "description": "Options needed for span creation", "properties": { "kind": { "title": "SpanKind", "type": "integer", "description": "Specifies the kind of span in OpenTelemetry traces. 0 = INTERNAL, 1 = SERVER, 2 = CLIENT, 3 = PRODUCER, 4 = CONSUMER." }, "attributes": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "array" ] }, "description": "A span's attributes" }, "links": { "type": "array", "items": { "type": "object", "properties": { "context": { "type": "object", "description": "Span context to link to", "properties": { "traceId": { "type": "string", "description": "32 lowercase hex chars (128-bit) identifying the trace.", "pattern": "^[0-9a-f]{32}$", "$comment": "If you want to disallow the all-zeros ID per W3C, add: { \"not\": { \"pattern\": \"^0{32}$\" } }" }, "spanId": { "type": "string", "description": "16 lowercase hex chars (64-bit) identifying the span.", "pattern": "^[0-9a-f]{16}$", "$comment": "To disallow all-zeros span ID: add { \"not\": { \"pattern\": \"^0{16}$\" } }" }, "isRemote": { "type": "boolean", "description": "True only if the SpanContext was propagated from a remote parent." }, "traceFlags": { "type": "integer", "description": "1-byte bitmap of trace flags (e.g., least-significant bit is sampling).", "minimum": 0, "maximum": 255, "$comment": "Use bit 0 (LSB) as 'sampled' if following W3C TraceFlags." }, "traceState": { "type": "object", "additionalProperties": true, "description": "Tracing-system-specific info to propagate. More Info: https://www.w3.org/TR/trace-context/#tracestate-field" } } }, "attributes": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "array" ] }, "description": "Link attributes" } } }, "description": "Links span to other spans" }, "startTime": { "anyOf": [ { "type": "array", "items": [ { "type": "number" }, { "type": "number" } ], "minItems": 2, "maxItems": 2, "description": "Tuple of two numbers" }, { "type": "number" }, { "type": "string", "format": "date-time", "tsType": "Date", "description": "ISO 8601 date-time string (represents Date)" } ], "description": "A manually specified start time for the created Span object" }, "root": { "type": "boolean", "description": "The new span should be a root span (ignore parent from context)" } }, "additionalProperties": true }, "ErrorInstrumentationConfig": { "type": "object", "description": "Configuration for the error instrumentation.", "properties": { "enabled": { "type": "boolean", "description": "Whether uncaught errors and unhandled promise rejections are published as error spans." }, "preInit": { "type": "boolean", "description": "Unless `false`, the pre-init recorder (installed by a window preload script or inline snippet before the SDK loads) also captures uncaught errors and unhandled promise rejections from page start while this instrumentation is enabled. The buffered records are drained into this instrumentation's retroactive error spans (with their real timestamps) at initialization." } } }, "InstrumentRequestsConfig": { "type": "object", "description": "Configuration for request instrumentation behavior.", "properties": { "enabled": { "type": "boolean", "description": "Whether requests instrumentation is enabled." }, "preInit": { "type": "boolean", "description": "Unless `false`, the pre-init recorder (installed by a window preload script or inline snippet before the SDK loads) also patches fetch and XMLHttpRequest while this instrumentation is enabled, so requests issued before the SDK initializes are recorded and drained into retroactive spans and metric samples at initialization. The recorder derives its measurement settings from this same configuration object (`requestBytesMetric` turns on request body sizing, `responseBytesMeasurement` carries over, and the total/download duration metrics turn on download-completion observation), so pre-init and live records measure identically." }, "platform": { "type": "boolean", "description": "If `true`, the io.Connect Desktop platform also instruments its OWN main-process HTTP traffic - Electron's net module (net.request and net.fetch) - at bootstrap, publishing through the platform's io.Insights instance with the same span and metric shapes as the renderer fetch/XHR instrumentation (spans under `interopio.api.instrumentation.electronNet`). Has no effect outside the platform process." }, "trace": { "type": "boolean", "description": "If `false`, no request spans are published - metrics-only mode. The instrumentation flow otherwise runs unchanged: measurement, the duration/size metrics, error classification, and the pre-init drain (metric samples, no retroactive spans). Applies to fetch, XHR and the platform's Electron net instrumentation alike. Trace header injection requires a span context, so `injectOTELHeaders` has no effect in metrics-only mode. A hard switch - span filters cannot re-enable the spans." }, "canBeRoot": { "type": "boolean", "description": "Whether request instrumentation 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. This will not affect metrics." }, "ignoreTelemetryURLs": { "type": "boolean", "description": "If `true`, requests to telemetry endpoints will not be instrumented." }, "ignorePattern": { "type": "string", "description": "Optional regex pattern of URLs to exclude from instrumentation." }, "matchPattern": { "type": "string", "description": "Optional regex pattern of URLs to include in instrumentation." }, "errorStatusCodes": { "type": "array", "items": { "type": [ "string", "number" ] }, "description": "HTTP response status codes to consider as errors on request spans. Status code families can be described as `4xx`, `5xx`, etc." }, "spanNames": { "type": "string", "enum": [ "semconv", "product" ], "description": "Controls only the naming of the fetch/XHR request spans. `semconv` (default) names the spans by the normalized HTTP request method (e.g. `GET`), per the OpenTelemetry semantic conventions for HTTP client spans; `product` keeps the product span names (`interopio.api.instrumentation.fetch` / `.xhr`). Everything else is identical in both modes: the spans always carry the semantic convention attributes, span kind CLIENT and the semantic convention status rules, and span filters always match on source `interopio.api.instrumentation.fetch`/`.xhr` and on `context.url` / `context.method`." }, "responseBytesMeasurement": { "type": "string", "enum": [ "content-length", "raw", "both" ], "description": "Which measurement the response size metric and span data report. `content-length` (default): only the value of the content-length response header (the actual transfer size, after content-encoding) - cheap, but responses without the header (e.g. chunked transfer encoding) contribute no sample. `raw`: only bytes counted by fully reading a clone of every fetch response body (the size after the browser removed any content-encoding) - always available, but every non-streaming response body is downloaded in full, including ones the application abandons. `both`: prefers content-length and falls back to the raw count - maximizes coverage but mixes the two measurement kinds in one histogram (use the `sizeKind` metric attribute to separate them)." }, "requestFirstByteDurationMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true`, the request's time to first byte (request issued until the response headers were received) will be recorded in a `io.insights.http.client.request.ttfb.duration` histogram metric. If a string is provided, it will be recorded in a histogram metric with the given name. Cheap and always available: measured for every request, including failures (until the failure), with no response body observation required. Deliberately not named after the semantic convention - samples other instrumentations publish under `http.client.request.duration` cover the full operation; that name is the default of `requestTotalDurationMetric` instead." }, "requestTotalDurationMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true`, the end-to-end request time (request issued until the response body was fully delivered) will be recorded in a `http.client.request.duration` histogram metric (the semantic convention name - the end-to-end measurement matches what other instrumentations publish under it). If a string is provided, it will be recorded in a histogram metric with the given name. Successful requests with an observable body completion only, so this metric's sample count is expected to be lower than `requestFirstByteDurationMetric`'s. Cost caveat: when this or `requestBodyDownloadDurationMetric` is enabled, body delivery of every non-streaming fetch response is observed by fully reading a clone of the body - responses the application abandons without reading are downloaded in full. Streaming content types (server-sent events etc.) are exempt." }, "requestBodyDownloadDurationMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true`, the download phase (response headers received until the response body was fully delivered) will be recorded in a `io.insights.http.client.response.download.duration` histogram metric. If a string is provided, it will be recorded in a histogram metric with the given name. Same population and cost caveats as `requestTotalDurationMetric`." }, "requestFirstByteDurationMetricBuckets": { "type": "array", "items": { "type": "number" }, "description": "Explicit histogram bucket boundaries for `requestFirstByteDurationMetric`, in seconds, ascending. The default is the semantic-convention-recommended set for HTTP client durations, which suits time-to-first-byte distributions well." }, "requestTotalDurationMetricBuckets": { "type": "array", "items": { "type": "number" }, "description": "Explicit histogram bucket boundaries for `requestTotalDurationMetric`, in seconds, ascending. The default is the semantic-convention-recommended set (this metric carries the semantic convention name by default), extended upward to cover long transfers of large payloads; overriding the sub-10s boundaries trades away comparability with other instrumentations." }, "requestBodyDownloadDurationMetricBuckets": { "type": "array", "items": { "type": "number" }, "description": "Explicit histogram bucket boundaries for `requestBodyDownloadDurationMetric`, in seconds, ascending." }, "requestBodyDownloadThroughputMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true` or a string, effective response download throughput (response body bytes over the download window, in bytes per second) is published as a histogram metric. If a string value is specified, this will be the name of the metric. Otherwise, the default `io.insights.http.client.response.download.throughput` is used. Derived from the same observation as `requestBodyDownloadDurationMetric` (same population and cost caveats), so it contributes samples only for successful requests with an observable body completion - and only bodies of at least 32KB: smaller transfers complete within the initial congestion window and would measure round-trip time, not bandwidth. Per-stream effective throughput: concurrent transfers share the link." }, "requestBodyDownloadThroughputMetricBuckets": { "type": "array", "items": { "type": "number" }, "description": "Explicit histogram bucket boundaries for `requestBodyDownloadThroughputMetric`, in bytes per second, ascending." }, "requestBytesMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true`, the request body size will be recorded in a `http.client.request.body.size` histogram metric. If a string is provided, the request body size will be recorded in a histogram metric with the given name. If `false`, no metric will be recorded. Body-less requests (e.g. GETs) contribute no sample." }, "responseBytesMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true`, the response body size will be recorded in a `http.client.response.body.size` histogram metric, measured according to `responseBytesMeasurement`. If a string is provided, the response body size will be recorded in a histogram metric with the given name. If `false`, no metric will be recorded." } } }, "UserJourneyTraceConfig": { "type": "object", "description": "Configuration for User Journey trace behavior. Controls how significant User Journey milestones are tracked throughout the platform session.", "properties": { "enabled": { "type": "boolean", "description": "Whether the User Journey trace is enabled." }, "structure": { "type": "string", "enum": [ "sibling", "nested" ], "description": "If `sibling`, all spans in the User Journey trace will be nested under the same root span. This is useful when working with visualization interfaces that do not handle arbitrarily nested spans. If `nested`, every span in the User Journey trace will be nested under the previous span. This is useful for some kinds of querying." }, "descriptiveName": { "type": "boolean", "description": "If `true`, the User Journey trace spans will be named interopio.desktop.userJourney... If `false`, the User Journey trace spans will be named interopio.api.userJourney." }, "chainLength": { "type": "number", "description": "If specified, this number of previously focused applications and their focus times will be added as attributes to the User Journey span. This is useful for some kinds of querying." }, "includeWorkspaceInfo": { "type": "boolean", "description": "Unless `false`, focus spans for windows that sit in a workspace also carry the workspace context - `workspaceId`, `workspaceName` and `workspaceTitle`. Only workspace membership is resolvable synchronously; the id/name/title are fetched from the workspaces frame asynchronously (two round trips per focus change into a workspace window) and added to the still-open focus span when they arrive - a focus change racing the lookup loses only these attributes." } }, "additionalProperties": true }, "ClickstreamTraceConfig": { "type": "object", "description": "Configuration for Clickstream trace behavior. Controls how user interaction events are tracked and organized in traces.", "properties": { "enabled": { "type": "boolean", "description": "Whether the Clickstream trace is enabled." }, "structure": { "type": "string", "enum": [ "sibling", "nested" ], "description": "If `sibling`, all spans in the Clickstream trace will be nested under the same root span. This is useful when working with visualization interfaces that do not handle arbitrarily nested spans. If `nested`, every span in the Clickstream trace will be nested under the previous span. This is useful for some kinds of querying." }, "descriptiveName": { "type": "boolean", "description": "If `true`, the Clickstream trace spans will be named interopio.api.clickstream... If `false`, the Clickstream trace spans will be named interopio.api.clickstream." }, "events": { "type": "array", "items": { "type": "string" }, "description": "List of DOM event names to capture as Clickstream trace spans." }, "nestEventListeners": { "type": "boolean", "description": "If `true`, io.Insights will try to nest spans from other event listeners for the same event under the Clickstream span. This is not guaranteed to always work due to specifics of how browsers execute event listeners, and will only work for listeners attached after io.Connect was initialized - unless `nestEventHandlersEagerly` is also enabled." }, "nestEventHandlersEagerly": { "type": "boolean", "description": "If `true`, the io.Insights pre-init module eagerly patches addEventListener at page start, so that listeners registered before io.Connect initialized also participate in `nestEventListeners` nesting. The flag is read by the pre-init module itself from the platform-provided configuration at `window.glue42gd.insights`, so it has no effect when the pre-init module is not installed. The eager wrappers are inert pass-throughs until the SDK initializes, and remain inert if the SDK loads with clickstream or `nestEventListeners` disabled." } }, "additionalProperties": true }, "ResourceInstrumentationConfig": { "type": "object", "description": "Configuration for the resource load instrumentation. The phase metrics record nonzero samples only: with connection reuse most requests have no DNS/TCP/TLS phase at all, and recording those zeros would drown the distributions - each histogram answers \"when this phase happened, what did it cost\". Cross-origin resources without a Timing-Allow-Origin header withhold the detailed timings and sizes and contribute no phase/throughput samples.", "properties": { "enabled": { "type": "boolean", "description": "Whether the resource instrumentation is enabled." }, "skipRequests": { "type": "boolean", "description": "If `true`, resource timing entries produced by fetch/XMLHttpRequest are skipped entirely (the request instrumentation covers those requests in more detail). Set to `false` to also publish resource spans and metric samples for them - e.g. to include API backends in the connection-phase and throughput metrics. Beacon entries and telemetry uploads are always skipped." }, "trace": { "type": "boolean", "description": "If `false`, no resource spans are published - metrics-only mode: the phase/TTFB/throughput histograms and the cache-state counter keep reporting." }, "dnsDurationMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true` or a string, DNS lookup durations are published as a histogram metric (`io.insights.resource.dns.duration` unless a string names it). Nonzero lookups only. Tagged with `server.address`/`server.port` and the ALPN protocol." }, "dnsDurationMetricBuckets": { "type": "array", "items": { "type": "number" }, "description": "Explicit histogram bucket boundaries for `dnsDurationMetric`, in seconds, ascending." }, "connectDurationMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true` or a string, connection establishment durations (connectStart until connectEnd - includes the TLS handshake when one happened) are published as a histogram metric (`io.insights.resource.connect.duration` unless a string names it). Nonzero connects only." }, "connectDurationMetricBuckets": { "type": "array", "items": { "type": "number" }, "description": "Explicit histogram bucket boundaries for `connectDurationMetric`, in seconds, ascending." }, "tlsDurationMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true` or a string, TLS handshake durations (secureConnectionStart until connectEnd - a subset of the connect duration) are published as a histogram metric (`io.insights.resource.tls.duration` unless a string names it). Secure connections only." }, "tlsDurationMetricBuckets": { "type": "array", "items": { "type": "number" }, "description": "Explicit histogram bucket boundaries for `tlsDurationMetric`, in seconds, ascending." }, "firstByteDurationMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true` or a string, resource time-to-first-byte (requestStart until responseStart) is published as a histogram metric (`io.insights.resource.ttfb.duration` unless a string names it). Measures the asset-serving infrastructure, distinct from the request instrumentation's TTFB metric which covers fetch/XHR API traffic. Samples only resources that actually hit the network (`network` and `revalidated` cache states) - cache hits would contribute disk latency, not server latency." }, "firstByteDurationMetricBuckets": { "type": "array", "items": { "type": "number" }, "description": "Explicit histogram bucket boundaries for `firstByteDurationMetric`, in seconds, ascending." }, "downloadThroughputMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true` or a string, effective download throughput (encodedBodySize over the responseStart-responseEnd window, in bytes per second) is published as a histogram metric (`io.insights.resource.download.throughput` unless a string names it). `network` cache state only, and only bodies of at least `downloadThroughputMinBytes` - smaller transfers complete within the initial congestion window and would measure round-trip time, not bandwidth. Per-stream effective throughput: concurrent downloads share the link, so it reflects what a transfer experienced, not link capacity." }, "downloadThroughputMetricBuckets": { "type": "array", "items": { "type": "number" }, "description": "Explicit histogram bucket boundaries for `downloadThroughputMetric`, in bytes per second, ascending." }, "downloadThroughputMinBytes": { "type": "number", "description": "Minimum encodedBodySize, in bytes, for a resource to contribute a `downloadThroughputMetric` sample." }, "cacheStateMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true` or a string, a counter of observed resource loads by cache state is published (`io.insights.resource.cache.state` unless a string names it), tagged with `cacheState` (`hit` / `revalidated` / `network` / `unknown`) and `server.address`/`server.port` - the cache hit ratio falls out at query time." } }, "additionalProperties": true }, "EventLoopInstrumentationConfig": { "type": "object", "description": "Configuration for the event loop responsiveness instrumentation. Both measurements are event-driven (no polling): samples record only when the browser delivers a performance entry, so an idle or smooth application produces none. Metric export follows the meter's publish interval as usual.", "properties": { "enabled": { "type": "boolean", "description": "Whether the event loop instrumentation is enabled." }, "trace": { "type": "boolean", "description": "If `false`, no spans are published - metrics-only mode: the input-delay and blocking histograms keep reporting. The master switch over `inputDelaySpans`/`eventLoopBlockingSpans`, which refine it per kind." }, "inputDelaySpans": { "type": "boolean", "description": "If `true`, slow input events are published as spans (`interopio.api.instrumentation.inputDelay`) spanning the event's timestamp until its next paint, with the input delay / processing / presentation phases and the same element-describing attributes as the clickstream spans." }, "inputDelayMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true` or a string, the input event queueing delay (event timestamp until its handlers started running - the event loop latency a user experienced) is published as a histogram metric. If a string value is specified, this will be the name of the metric. Otherwise, the default `io.insights.event_loop.input.delay` is used. Only events whose total duration reaches `inputDelayDurationThresholdMs` are surfaced by the browser, so the distribution describes slow-ish interactions, not all input." }, "inputDelayMetricBuckets": { "type": "array", "items": { "type": "number" }, "description": "Explicit histogram bucket boundaries for `inputDelayMetric`, in seconds, ascending. The default brackets the INP \"good\" (0.2s) and \"poor\" (0.5s) thresholds." }, "inputDelayDurationThresholdMs": { "type": "number", "description": "The Event Timing API durationThreshold, in milliseconds: only input events whose total duration (event timestamp until next paint) reaches this value are observed. The browser floor is 16ms." }, "inputDelayInteractionsOnly": { "type": "boolean", "description": "If `true`, only interaction-eligible events (Event Timing entries with a non-zero interactionId - discrete interactions like clicks and key presses, the population INP is computed over) are observed. Disabling it also surfaces continuous events (pointermoves etc.) that meet the duration threshold." }, "eventLoopBlockingSpans": { "type": "boolean", "description": "If `true`, main-thread-blocking long frames are published as spans (`interopio.api.instrumentation.eventLoopBlocking`) spanning the frame, with the blocking duration and (where the Long Animation Frames API is available) the attribution of the longest script in the frame." }, "eventLoopBlockingMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true` or a string, the main-thread blocking time per long frame (the time beyond the 50ms threshold, per the Long Animation Frames API's blockingDuration; where only Long Tasks are available, task duration minus 50ms) is published as a histogram metric. If a string value is specified, this will be the name of the metric. Otherwise, the default `io.insights.event_loop.blocking.duration` is used. Zero-blocking frames contribute no sample. The `measurement` attribute says which API produced each sample." }, "eventLoopBlockingMetricBuckets": { "type": "array", "items": { "type": "number" }, "description": "Explicit histogram bucket boundaries for `eventLoopBlockingMetric`, in seconds, ascending." } }, "additionalProperties": true }, "WebSocketInstrumentationConfig": { "type": "object", "description": "Configuration for the WebSocket instrumentation.", "properties": { "enabled": { "type": "boolean", "description": "Whether the WebSocket instrumentation is enabled." }, "platform": { "type": "boolean", "description": "If `true`, the io.Connect Desktop platform also tracks its OWN main-process WebSocket connections - most importantly its gateway connection, which is created before the platform's io.Insights initializes: the platform's bootstrap installs the pre-init recorder (with WebSocket tracking enabled) early enough that the connection is observed from construction, and the platform's io.Insights instance adopts it at initialization. Has no effect outside the platform process." }, "preInit": { "type": "boolean", "description": "Unless `false`, the pre-init recorder (installed by a window preload script or inline snippet before the SDK loads) tracks WebSocket connections from page start while this instrumentation is enabled: connections closed before initialization become retroactive spans, still-open ones are adopted with spans starting at their true construction time. Opting out restricts the instrumentation to sockets constructed after initialization - a socket opened pre-init (the io.Connect gateway connection, bootstrap-time data feeds) is then unobservable for its whole lifetime, since WebSockets can only be intercepted at construction." }, "trace": { "type": "boolean", "description": "If `true` (the default), each WebSocket connection is published as a span (`interopio.api.instrumentation.webSocket`) covering construction until close, with `connectMs`, the negotiated protocol, close code/reason/wasClean, message and byte totals in both directions, and the connection duration. Abnormal closures (1006) and connection failures mark the span as ERROR. If `false`, no connection spans are published - metrics-only mode: the message/byte counters and the connect-duration histogram keep reporting." }, "ignoreGateway": { "type": "boolean", "description": "If `true`, the io.Connect gateway connection is excluded from instrumentation. By default the gateway socket IS tracked: its connection lifecycle (connects, drops, close codes, reconnect attempts) is core platform-health telemetry. The gateway is recognized via the platform-provided connection URL (`window.glue42gd.gwURL`, compared by origin and path); where that is unavailable the flag has no effect - use `ignorePattern` to exclude infrastructure sockets explicitly. Cost note: with the message/byte metrics enabled, the gateway socket contributes a sample per gateway message - enable those metrics deliberately, or set this flag to exclude the gateway. Sockets explicitly handed to the pre-init recorder via its trackWebSocket hook (e.g. the core-js gateway transport handing over its own connection) bypass this flag even when set; `ignorePattern` still applies to them and remains the veto." }, "ignorePattern": { "type": "string", "description": "Optional regex pattern for WebSocket URLs that should be excluded from instrumentation - e.g. infrastructure sockets beyond the gateway connection (which `ignoreGateway` can exclude)." }, "matchPattern": { "type": "string", "description": "Optional regex pattern; if specified, only matching WebSocket URLs are instrumented." }, "messagesMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true` or a string, a counter of WebSocket messages is published (`io.insights.websocket.messages` unless a string names it), tagged with `direction` (`send` / `receive`) and `server.address`/`server.port`." }, "bytesMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true` or a string, a counter summing WebSocket payload bytes is published (`io.insights.websocket.bytes` unless a string names it), tagged with `direction` (`send` / `receive`) and `server.address`/`server.port`." }, "connectDurationMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true` or a string, the connection establishment time (construction until the open event) is published as a histogram metric (`io.insights.websocket.connect.duration` unless a string names it). Successful connections only." }, "connectDurationMetricBuckets": { "type": "array", "items": { "type": "number" }, "description": "Explicit histogram bucket boundaries for `connectDurationMetric`, in seconds, ascending." } }, "additionalProperties": true }, "WebVitalsInstrumentationConfig": { "type": "object", "description": "Configuration for the session-level Web Vitals instrumentation. Values are reported when the page becomes hidden: a span with the current values on each hidden transition where they changed, and (for the metrics) one terminal sample per page at pagehide - so each session contributes a single sample per histogram.", "properties": { "enabled": { "type": "boolean", "description": "Whether the Web Vitals instrumentation is enabled." }, "trace": { "type": "boolean", "description": "If `true` (the default), a `interopio.api.instrumentation.webVitals` span carrying the current CLS/INP/LCP values and the interaction count is published on each transition to hidden where the values changed since the last report. If `false`, no webVitals spans are published - metrics-only mode: the terminal CLS/INP/LCP samples at pagehide keep reporting." }, "clsMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true` or a string, the session's cumulative layout shift is published as a histogram metric (`io.insights.web_vitals.cls` unless a string names it). Unitless score, session-window algorithm (shifts without recent input, windowed at 5s max / 1s gap, the worst window wins)." }, "clsMetricBuckets": { "type": "array", "items": { "type": "number" }, "description": "Explicit histogram bucket boundaries for `clsMetric` (unitless score), ascending. The default brackets the CLS \"good\" (0.1) and \"poor\" (0.25) thresholds." }, "inpMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true` or a string, the session's INP (interaction to next paint) is published as a histogram metric (`io.insights.web_vitals.inp` unless a string names it) - the worst interaction latency, moving to a high percentile as the interaction count grows, per the web-vitals estimation." }, "inpMetricBuckets": { "type": "array", "items": { "type": "number" }, "description": "Explicit histogram bucket boundaries for `inpMetric`, in seconds, ascending. The default brackets the INP \"good\" (0.2s) and \"poor\" (0.5s) thresholds." }, "lcpMetric": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ], "description": "If `true` or a string, the final largest contentful paint is published as a histogram metric (`io.insights.web_vitals.lcp` unless a string names it), in seconds from navigation start." }, "lcpMetricBuckets": { "type": "array", "items": { "type": "number" }, "description": "Explicit histogram bucket boundaries for `lcpMetric`, in seconds, ascending. The default brackets the LCP \"good\" (2.5s) and \"poor\" (4s) thresholds." } }, "additionalProperties": true }, "Log4JSToOTELAppenderConfig": { "type": "object", "description": "This interface describes the log4js appender configuration that controls the @interopio/log4js-otel bridge appender.", "properties": { "layout": { "type": "object", "additionalProperties": true, "description": "log4js layout to use for structuring the log entries. If not specified, uses MessagePassThroughLayout." }, "maxRecordsBeforeOTELActive": { "type": "number", "description": "Maximum number of log records to store in memory before the OTEL SDK has finished initializing. Use -1 for an infinite number." }, "maxTimeBeforeOTELActiveMs": { "type": "number", "description": "Maximum duration of time to store log entries in memory before the OTEL SDK has finished initializing. Use -1 for an infinite duration." }, "logErrorsInConsole": { "type": "boolean", "description": "Whether errors in the @interopio/log4js-otel bridge appender will be logged to the console." } }, "additionalProperties": false } } }