# On-prem agent logs

The on-prem agent (OPA) logs a variety of events. The log file contains OPA activity, warnings, and traces. The most common use of log files is for troubleshooting, but there are other scenarios, such as audit and compliance.

# Logging schedule

The OPA logger creates a new log file at the start of each day, based to the on-premise system time. It also creates a new log file after the file size exceeds 20 MB. To identify the multiple log files of the same day, the system numbers them sequentially.

You can access the OPA log files in the agent folder. The OPA retains logs for a maximum of 60 days, or at most 20 GB of files.

# Scenario 1: logging up to 20 MB

Date: 01-NOV-2019
Total file size:: 15 MB
Log file: /agent-2019-11-01.0.log
A log file starts at the beginning of the day.

# Scenario 2; logging over 20 MB

Date: 02-NOV-2019
Total file size: 25 MB
Log file: /agent-2019-11-02.0.log
A log file is starts at the beginning of the day. The system stores the first 20 MB in this file.

/agent-2019-11-02.1.log
A new log file starts when the system reaches the limit of 20 MB. It contains the remaining 5 MB.

# OPA log properties

OPA logs contain the following properties:

Date: OPA dates each log file to improve its findability.
Numbered logs: If there are multiple log files on the same day, OPA numbers them sequentially.
File size limit: The logger enforces a 20 MB size limit to make it easier to query file content.
Storage limit: The folder limit reduces the storage load on the server.

# Logging OPA activity

At the top level of your config.yml file, add the logging definition to record the various level of activity logs.

logging:
  cloud: true
  logger: logging_level
  workato: debug
  sql: trace

OPA uses the cloud property to send the logs to Workato cloud, to the Workato support team can efficiently access these logs when you require assistance in solving technical issues. This option is enabled by default in the config file. If you don't want to send your agent logs and performance data to Workato, set this value to false.

TROUBLESHOOT COMMON LOG ERRORS

Some log entries point to configuration issues or runtime errors. Refer to the following guides to troubleshoot these errors:

# Workato loggers

These are the loggers that Workato uses:

workato: This will include logs from all parts of the OPA.
sql: This will only log database-related parts of the OPA.
custom: See Using a custom logger for more information.

# Workato logging levels

These are the supported logging levels:

trace: Information for identifying steps that lead to the error. Typically used for diagnosis in the engineering support group.
We recommend that you use this *temporarily*, because this exposes a large amount debugging information, including *confidential data*.
Example: Starting secure tunnel
debug: Information for troubleshooting or diagnosis, and readable/understandable by users.
Example: Failure due to an unknown exception.
info: Information logged under normal conditions.
Example: agent starting or stopping.
warn: Information about a potential problem that does not require immediate attention from the user.
Example: transient network interruption.
error: Information about an error that needs investigation.
Example: Agent failed to start.

# Logging for specific profiles

You can also choose to selectively enable logs for specific profiles. All you have to do is add the debug: true definition to the profile:

database:
  sql:
    adapter: mysql
    database: workato
    username: user
    password: password
    timeout: 30
    debug: true

# Using a custom logger

You can also use a custom logger instead of the native Workato loggers. Simply replace the logger name with the name of the class or the package of your custom logger.

logging:
  "com.workato.agent.file": debug

# Where to find OPA logs

The location OPA logs are stored in varies based on your agent configuration and operating system.

Refer to the following sections for more information:

Windows
Linux
Workato Logging Service

# Windows

Log files are stored in %SYSTEMROOT%\System32\LogFiles\Workato by default for on-prem agents operating as a Windows service. You can navigate to this file manually or use the shortcut in the Start menu under All apps > Workato.

Complete the following steps to change the log storage location:

Open the Windows Start menu.

Go to All apps > Workato.

Click Service Wrapper Configuration to open the configuration menu.

Go to the Logging tab.

Enter a new log storage location in the Log path field.

Click Apply, then OK.

OPA LOG CONTENTS

The level of detail included in your OPA logs depends on your agent configuration. Refer to the Workato logging levels section for more information.

# Linux

Log files are stored in /var/log/messages by default for on-prem agents operating as a Linux service through systemd. Because this file also contains logs from other Linux services, you must use the journalctl command to access OPA specific logs.

journalctl -u [name of the OPA service].service

The -u switch filters the logs returned by the service that created them. Replace [name of the OPA service] with the name you set for the OPA during installation.

You can further refine your log search using the following commands:

> [output-file]: Exports the result of journalctl to a file.
--since: Limits the generated logs to after a specific date and time.
--until: Limits the generated logs to before a specific date and time.

For example:

journalctl -u workato.service --since "2020-07-26 23:15:00" --until "2020-08-5 23:20:00" > OPALogs.txt

Refer to Loggly's Using journalctl (opens new window) guide for additional journalctl information.

OPA LOG CONTENTS

The level of detail included in your OPA logs depends on your agent configuration. Refer to the Workato logging levels section for more information.

# Workato Logging Service

If you are using OPA version 23.0 or newer, you can send your on-prem agent logs to Workato Logging Service.

Enable logging service

In your on-prem group's Settings tab, select Send to Workato logs to start sending OPA logs to the Workato Logging Service. This allows you to see a more detailed flow of your jobs being processed with Workato on-prem agent usage. By default, this option is disabled.

Note that the Workato Logging Service does not currently include trace level OPA logs.

ENABLE LOGGING SERVICE

If you do not see this option, you do not have the Workato Logging Service enabled in your workspace. Contact your Customer Success representative to enable the Logging Service.

OPA logs in the Workato Logging Service

You can filter logs by each column on the Logs page. Refer to Logging service for instructions.

For example, in the following image, the Logs page only displays entries with log level ERROR:

OPA logs in the Workato Logging Service

Last updated: 5/29/2025, 10:25:55 PM