Logging

io.Connect Desktop offers a Logger API which enables web apps to create a hierarchy of sub-loggers mapped to app components where you can control the level of logging for each component. You can also route the output of log messages (depending on the logging level) to a variety of targets - the developer console or an external output.

Adding logging to files to your web apps can be helpful in a variety of ways. Having a well-designed and meaningful logging structure in your apps and their components can save a lot of time when debugging an app during development or troubleshooting problems with an app in production.

ℹ️ For details on how to configure and customize the logging mechanisms of io.Connect Desktop, see the Developers > Configuration > System > Logging section.

ℹ️ For details on how to enable logging the stdout and stderr stream outputs of native apps, see the Developers > Configuration > System > Logging section.

Logging for apps via the io.Connect APIs is disabled by default. To allow it, use the "allowLogging" top-level key in the app definition file:

{
    "allowLogging": true
}

User apps will log in the respective <app-name>.log file where <app-name> represents the name of your app as specified in its app definition. A separate log file is created for each app that has logging enabled. All instances of an app log to the same file. The app log file will be located in the %LocalAppData%/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/logs/applications folder on Windows and in the ~Library/Application Support/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/logs/applications folder on macOS where <ENV>-<REG> represents the environment and region of io.Connect Desktop (e.g., DEMO-INTEROP.IO).

The log file entries are in the following format:

[<date>T<time>] [<logging_level>] [<instance_id>] [<logger_name>] - <log_message>

The following example demonstrates an actual log entry:

[2020-03-11T14:27:58.087] [ERROR] [30760_11] [client-list.test-logger] - test-error
    at t.error (http://localhost:22080/client-list/desktop-4.8.0.js:1:39269)
    at <anonymous>:1:8

Available since io.Connect Desktop 9.9

Child windows of web apps opened via the browser native window.open() method can also use the Logger API to create log entries.

The log entries created by child windows are located in the parent app log file. Each log entry by a child app contains specific details about the child app (indication that the log entry was made by a child app, instance ID and URL of the child app) allowing you to easily find and extract the relevant information. The following example demonstrates the shape of an actual log entry by a child app:

[2025-06-16T10:12:12.476] [INFO] [15308_13] [child:15308_14|https://interop.io/] - Log entry by a child app.

Streaming & Consuming

You can configure io.Connect Desktop to stream the system logs so that they can be consumed by your apps. You can specify the log level and the interval at which the logs to be streamed. Use the "streaming" property of the "logging" top-level key in the system.json system configuration file of io.Connect Desktop to specify the log streaming configuration:

{
    "logging": {
        "streaming": {
            "enabled": true,
            "minLevel": "warn",
            "interval": 60
        }
    }
}

The "streaming" object has the following properties:

To consume the log entries in your apps, you must implement and register an Interop method named "T42.Logs.Listen". This method will be invoked whenever io.Connect Desktop streams the system logs. The method handler will receive an object with an entries property as an argument which holds an array of objects each describing the individual log entries:

const name = "T42.Logs.Listen";
const handler = logs => logs.entries.forEach(e => console.log(e.source, e.logEntry));

await io.interop.register(name, handler);

Each log entry has the following properties:

Log Files

Available since io.Connect Desktop 9.3

To specify settings for handling the system log files, use the "files" property of the "logging" top-level key in the system.json system configuration file of io.Connect Desktop:

{
    "logging": {
        "files": {
            "onStartup": "archive",
            "moveOldTo": "%LocalAppData%/my-org/logs"
        }
    }
}

The "files" object has the following properties:

Available since io.Connect Desktop 9.9

To instruct io.Connect Desktop to capture console messages, network request errors, and any unhandled errors originating from your web app, use the "logging" property of the "details" top-level key in the app definition:

{
    "details": {
        "logging": {
            "consoleMessages": {
                "enabled": true,
                "level": "info"
            },
            "networkRequestErrors": {
                "enabled": true
            },
            "unhandledErrors": {
                "enabled": false
            }
        }
    }
}

The captured errors will be logged in the respective <app-name>.log file where <app-name> represents the name of your app as specified in its app definition. The app log file will be located in the %LocalAppData%/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/logs/applications folder on Windows and in the ~Library/Application Support/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/logs/applications folder on macOS where <ENV>-<REG> represents the environment and region of io.Connect Desktop (e.g., DEMO-INTEROP.IO).

Capturing these errors is disabled by default. The "logging" property accepts a Boolean or an object as a value. If set to true, all console messages, networks request errors, and unhandled errors will be logged. You can use an object as a value to provide settings for the types of errors you want to capture.

The "logging" object has the following properties:

The "consoleMessages" object has the following properties:

The "networkRequestErrors" object has the following properties:

The "unhandledErrors" object has the following properties: