Skip to content

reference-manual.adoc

Latest commit

 

History

History
85 lines (60 loc) · 3.94 KB

reference-manual.adoc

File metadata and controls

85 lines (60 loc) · 3.94 KB

Reference Manual

Author: Adam Leszczyński <aleszczynski@bersler.com>, version: 1.9.0, date: 2026-01-27

This reference manual describes runtime options, directory permissions and the main configuration for OpenLogReplicator. It is intended as a concise operational guide; detailed element descriptions are available in the referenced files.

Table of Contents

Quickstart

  • Place the configuration file OpenLogReplicator.json in the process working directory (or provide it with -f).

  • Ensure the process user can read and write directories referenced by the configuration (checkpoints, swap, dumps).

  • Start the program with appropriate CLI options (examples below).

Command line parameters

OpenLogReplicator is non-interactive. Supported command-line options:

  • -f|--file <config file> — path to configuration file (default: OpenLogReplicator.json).

  • -p <process name> — process name visible in system process lists (default: OpenLogReplicator).

  • -r|--root — disable the startup root-check (not recommended for production).

  • -v|--version — print version and exit.

Example invocation:

./OpenLogReplicator -f ./configs/OpenLogReplicator.json -p OLReplicator

Configuration

All runtime configuration is defined in OpenLogReplicator.json. Refer to the configuration reference for full details: OpenLogReplicator.json.

  • Configuration is a single JSON object containing top-level elements such as source, target, memory, format, filter, and debug.

  • Example configuration files and templates are available in the scripts directory in the repository.

Output and logging

  • All program diagnostic and error messages are written to stderr.

  • Some internal JSON output may be written to stdout when a test/debug option is enabled in the configuration.

  • Use conservative log-level and trace settings in production; enable higher verbosity only for troubleshooting.

Directory and file permissions

The process requires appropriate filesystem permissions for directories used by the configuration:

  • Checkpoint directory

    • The application periodically writes checkpoint files named like <database>-chkpt.json and <database>-chkpt-<scn>.json.

    • The process user must have read, write and execute permissions on the checkpoint directory.

  • Swap and dump paths

    • If swapping is enabled (swap-path) or dumps are produced (dump-path), ensure those directories are writable and have sufficient free space and I/O performance.

CAUTION: Insufficient permissions or lack of space may cause unexpected process termination.

Runtime behavior notes

  • The min-mb / max-mb memory settings in the memory element control resident allocations and buffer sizing. Verify buffer minima sum remains below max-mb.

  • When enabling swap, prefer fast local storage to avoid high latency and unpredictable throughput.

  • Changing configuration settings in production (especially source/target, filter or memory parameters) should be validated in a staging environment and may require resetting checkpoints.

Troubleshooting

  • Use debug element options sparingly; stop-* settings will terminate the process for diagnostic capture.

  • Use dump-redo-log and dump-raw-data only when diagnosing specific issues; dumps can be large and are intended for debugging.

  • Increase log-level or add trace flags to obtain more detailed runtime information when investigating problems.

See also