Configuring Debug Logging

Overview

OESIS includes a built-in diagnostic logging facility that can be enabled at initialization time. By default, the SDK does not produce any log output. This keeps runtime overhead minimal for normal operation. When you need to investigate an issue, you can turn on full diagnostic logging by using one of two approaches:

Approaches	Mechanism	Best for
`config_debug`	JSON object passed to `wa_api_setup` at initialization	Programmatic integrations where you control SDK startup parameters
`v4Debug.dat`	File placed in the SDK deployment directory	Quick enablement without code changes; field troubleshooting

Both methods share the same configuration parameters and produce the same log output.

When to Use This

Enable config_debug when:

You're troubleshooting unexpected SDK behavior
OESIS Support has asked you to collect diagnostic logs
You're validating a new integration and want visibility into what the SDK is doing under the hood

You do not need config_debug for normal production use, omitting it disables debug logging entirely.

How It Works

Approach 1: config_debug (Programmatic)

Add a config_debug object to the JSON payload passed to wa_api_setup. Place it at the top level, alongside config, not nested inside it. For example:

json_config
    
xxxxxxxxxx
 
{  "config": { ... },  "config_debug": {    "debug_log_output_path": "C:\\Logs\\OESIS",    "debug_log_file_size": 10,    "debug_log_folder_size": 100,    "debug_log_count": 5,    "debug_log_time": 24  }}
Copy

Simply including the config_debug key, even as an empty object "config_debug": {}, automatically activates debug logging using the SDK's defaults.

Approach 2: v4Debug.dat (File-Based)

Create a file named v4Debug.dat in the SDK deployment (working) directory. An empty file is sufficient to activate logging with defaults. To customize behavior, populate the file with a JSON object containing the desired parameters.

v4Debug.dat
    
xxxxxxxxxx
 
{  "debug_log_output_path": "C:\\Logs\\OESIS",  "debug_log_level": "ALL",  "debug_log_components": ["ALL"],  "debug_log_file_size": 5,  "debug_log_folder_size": 100,  "debug_log_time": 72,  "debug_log_count": 30}
Copy

The filename is case-insensitive (v4debug.dat, v4DEBUG.dat, etc. are all recognized).

If v4Debug.dat is present, the SDK uses that configuration instead, and it overrides whatever is passed in config_debug through wa_api_setup. If your config_debug settings don't seem to be taking effect, check whether v4Debug.dat file exists.

Recommended Configuration

For most troubleshooting scenarios, we recommend setting only these categories of options and leaving everything else at its default. This ensures the widest possible diagnostic coverage, nothing gets filtered out that might turn out to be relevant.

1. Output location

Key	Type	Description
`debug_log_output_path`	string	Directory where log files will be written. If omitted, logs are written in the directory containing `libwautils.dll`

2. Retention

Key	Type	Unit	Description
`debug_log_file_size`	number	MB	Maximum size of a single log file before it rotates
`debug_log_folder_size`	number	MB	Maximum total size of the log directory
`debug_log_count`	number	files	Maximum number of rotated log files to retain
`debug_log_time`	number	hours	Also rotate the log after this many hours, regardless of file size

3. Log format

Key	Type	Description
`log_mode`	string	Controls which log file(s) are produced: `encrypted`, `plaintext`, or `all`

If log_mode is omitted (or is set to an unrecognized value), it defaults to “encrypted". Encrypted logs are safe to leave on for extended periods but only OESIS team can decrypt them.

If you need to review the log contents yourself, set log_mode to "plaintext" or "all".

Plaintext logs omit some information that encrypted logs capture, which can make it harder to pinpoint the root cause of an issue. If you're sending logs to OPSWAT for investigation, encrypted (or all, which produces both) gives Support Team the most complete picture.

Optional: Narrowing the Scope

The following keys let you limit what gets logged.

Since the goal of debug logging is usually to capture a complete picture of an issue, we recommend leaving these keys below unset unless you already know exactly what you're looking for. Narrowing scope risks missing the very entry you need.

Key	Type	Description
`debug_log_level`	string	Limits verbosity. Accepts `OFF`, `DEBUG`, `ERROR`, `FATAL`, `INFO`, `WARNING`, `TRACE`, or `ALL`. Leave unset (or use `ALL`) to capture everything.
`debug_log_components`	array<string>	Limits logging to specific components: `CORE`, `SETUP`, `TEARDOWN`, `INVOKE`, or `ALL`.
`debug_log_signatures`	array<number>	Limits logging to specific signature IDs.
`debug_log_methods`	array<number>	Limits logging to specific method IDs.

Example: Minimal Recommended Setup

JSON
    
xxxxxxxxxx
 
{  "debug_log_output_path": "C:\\Logs\\OESIS",  "debug_log_file_size": 10,  "debug_log_folder_size": 100,  "debug_log_count": 5,  "debug_log_time": 24,  "log_mode": "plaintext"}
Copy

This configuration:

Writes logs to C:\Logs\OESIS
Rotates a log file once it reaches 10 MB, or every 24 hours, whichever comes first
Keeps up to 5 rotated files, and caps total folder size at 100 MB
Produces readable, plaintext log output
Captures all components, levels, signatures, and methods, since none of the narrowing options are set

What to Expect

Scenario	Exit Code	Output
All steps succeed	0	Setup output + "OESIS SDK initialized successfully." + invoke result + teardown confirmation
`wa_api_setup` fails	1	Error code + SDK error detail on stderr
`wa_api_invoke` fails	1	Error code + SDK error detail on stderr; teardown is still called
Teardown fails	1	Error code on stderr

If Further Assistance is required, please proceed to log a support case or chatting with our support engineer.

Last updated on

Was this page helpful?