---
module: agent.ejournal-db-monitor
title: EJournal DB Monitor — guards the Hyosung 2 GB journal write limit
tab: Internal
order: 20
audience: dev
---

# EJournal DB Monitor (Internal / Ops view)

## What it monitors and why

Hyosung MoniPlus2S ATMs store their electronic journal in a local database file
(Access `.mdb`, SQL Compact `.sdf`, or a plain `.db`/`.sqlite`). That engine has a
hard **2 GB** file-size limit — once the file reaches it, the ATM application
**stops writing journal data** and journal capture silently fails. There is no
customer-visible alarm on the machine itself.

The `ejournal-db-monitor` agent module watches that database file size on a timer
and raises HiveIQ incident events **before** the ATM hits the wall, so helpdesk can
schedule the journal-clear/maintenance while the ATM is still capturing.

Two thresholds (both grounded in `EJournalDbMonitorModule`):

| Level    | Default trigger | Event emitted           | Meaning |
|----------|-----------------|-------------------------|---------|
| Warning  | 1.5 GB (1536 MB)| `EJOURNAL_DB_WARNING`   | Early notice — plan maintenance |
| Critical | 2.0 GB (2048 MB)| `EJOURNAL_DB_CRITICAL`  | At/near the limit — journal writing may stop, act immediately |

The event `eventDetails` string reports the file name, current size in MB, and the
percentage of the 2 GB limit consumed. Events are tagged with `eventSource =
HIVEOPS_AGENT_EJDB` so they can be told apart from normal journal-parsed events.

### Alert de-duplication

Once an alert level fires it is **not** repeated until one of:

- The level **escalates** (Warning → Critical), or
- The **cooldown** window elapses (default 24 h), or
- The file drops back **below** the warning threshold (i.e. the DB was cleared) —
  this resets the alert state so the next growth cycle alerts fresh.

So a stuck-full ATM produces at most one Critical event per cooldown window, not a
flood.

## Config properties it registers

All read from the agent's main properties (`hiveops.properties`). Keys and defaults
come straight from `EJournalDbMonitorModule.initialize()`:

| Property | Default | Purpose |
|----------|---------|---------|
| `ejournal.db.monitor.enabled` | `true` | Master on/off. If `false`, module no-ops (never becomes ready). |
| `ejournal.db.monitor.dir` | `D:\EJOURNAL` | Directory to scan. |
| `ejournal.db.monitor.filename` | *(blank)* | Specific file to watch. If blank, auto-detects the **largest** file matching `.mdb` / `.sdf` / `.db` / `.sqlite`. |
| `ejournal.db.monitor.warn.mb` | `1536` | Warning threshold (MB). |
| `ejournal.db.monitor.critical.mb` | `2048` | Critical threshold (MB). |
| `ejournal.db.monitor.interval.min` | `15` | Check interval (minutes). First check runs immediately at start. |
| `ejournal.db.monitor.cooldown.hours` | `24` | Hours before re-alerting at the same level. |

The module also needs an event endpoint — it uses `agent.endpoint` if present
(preferred, agent-proxy), else falls back to `incident.endpoint`. HTTP settings are
loaded with the matching prefix (`agent.*` or `incident.*`). If **neither** endpoint
is set the module initializes to a no-op and never sends events.

## How it's enabled / deployed to ATMs

This is a **standalone drop-in module** (`pom.xml` `finalName =
hiveops-module-ejournal-db-monitor`, artifact `hiveops-module-ejournal-db-monitor.jar`,
module version `1.0.0`). It is not bundled in the fat JAR by default; it is discovered
at runtime via `ServiceLoader` from the agent's `modules/` directory.

Two ways to get it onto an ATM:

1. **Fleet `INSTALL_MODULE` task** (preferred) — delivers the module JAR to the
   ATM's `modules/` directory, then the agent restarts to pick it up. Supports both
   artifact-store delivery (chunked download, `task.paths`) and legacy URL delivery
   (`configPatch.url` + `filename`, must end in `.jar`). See
   `ProcessInstallModule` in `hiveops-file-collection`.
2. **Manual drop-in** — copy `hiveops-module-ejournal-db-monitor.jar` into the
   agent install's `modules/` folder and restart the agent.

To turn it off without removing the JAR: either set
`ejournal.db.monitor.enabled=false`, or add `ejournal-db-monitor` to the
`modules.disabled` property in `hiveops.properties`. Both are pushable via a
`CONFIG_UPDATE` fleet task.

## Common failure modes / what to check

- **No events ever arrive** — check that `agent.endpoint` (or `incident.endpoint`)
  is set; with neither, the module silently becomes a no-op. Also confirm the module
  is present in `modules/` and not listed in `modules.disabled`.
- **"No EJournal database file found"** (debug log) — `ejournal.db.monitor.dir`
  wrong for this box, or the DB uses an extension outside `.mdb/.sdf/.db/.sqlite`.
  Set `ejournal.db.monitor.filename` explicitly.
- **Wrong file watched** — with no `filename` set, the module picks the *largest*
  matching file in the directory. If backups or unrelated DBs share the dir, pin the
  exact filename.
- **Expected an alert but none came** — the level may be inside its cooldown (24 h
  default) and not yet escalated. Escalation Warning→Critical always fires
  immediately regardless of cooldown.
- **Alerts stopped after a clear** — expected: dropping below the warning threshold
  resets alert state; growth back up re-alerts.
- **Send failures** — `Failed to send EJournal DB ... event` in the log means the
  size check ran but the HTTP POST to `/api/journal-events` failed; check agent-proxy
  reachability. The check will retry on the next interval.

Log package for this module is `com.hiveops.ejournal` (thread name
`ejournal-db-monitor`).
