How to monitor VICIdial SFTP pushes with append-only JSONL

01 / 07

How this guide watches the push script

Fast answer: confirm the push script's JSONL log exists and is root-owned, learn its one-line-per-phase schema, prove the file can be read but not appended by another account, add a narrow logrotate policy, and prove that reading the log never changes it.

JSONL means JSON Lines: a plain text file where each line is one complete, self-contained JSON record, so a script can append a new event without rewriting the file and you can read it with ordinary line tools. Each line here records one phase of one push attempt: a timestamp, the profile alias, the phase name and its result.

Every command below only reads. Nothing here appends a line, forces a rotation or changes the script that writes the log; a clean pass proves the log is trustworthy to monitor, not that any external recipient received a file.

• Confirm which push script's log you are watching before you begin (see `vicidial-sales-recordings-sftp`).
• Keep aggregate counts and the profile alias non-sensitive; never paste a raw JSONL line into a ticket.
• Grant read access narrowly; never widen the log's mode just to make it easier to view.
• Test a normal read and an attempted write from the same non-root account.

02 / 07

Step 1 — Confirm the log exists

There is nothing to install here. The log is a side effect of the push script's own `log_event` function in `vicidial-sales-recordings-sftp`, not a separate package; this guide only reads what that script already writes.

A missing log almost always means the script has not completed a phase yet, not that monitoring itself is broken. Confirm the script's CONFIG block and its last check-only run before assuming this path is wrong.

ls -l /var/log/vicidial-sales-sftp/push.jsonl 2>/dev/null || echo 'no runs yet'

03 / 07

Step 2 — Read the one-line-per-phase schema

Every line is one complete JSON object with exactly four fields: `ts` (an ISO-8601 timestamp), `profile` (the alias set in the push script's CONFIG block), `phase` (`check-only`, `export`, `validate`, `upload-report`, `upload-audio` or `complete`) and `result` (`pass`, `done` or `fail`). Treat any tool or habit that would add a fifth field, such as a filename or a recording ID, as a bug to fix in the script, not a feature to keep.

Because the file is append-only, read it with ordinary line tools instead of opening it in an editor that could resave the whole file.

python3 -c 'import json,sys; print(sum(1 for l in sys.stdin if l.strip() and json.loads(l) is not None), "valid JSON lines")' < /var/log/vicidial-sales-sftp/push.jsonl

04 / 07

Step 3 — Confirm the log's owner and mode

Prove who can write this file before you trust it as evidence. The push script creates the log itself the first time it logs a phase, inheriting root ownership from the script that runs as root; confirm the result rather than assuming a mode.

If you add a dedicated read-only monitoring account later, test it the same way: confirmed read access, and a confirmed, tested absence of write access. Never solve a failed read by loosening the file's mode.

stat -c '%U %a %n' /var/log/vicidial-sales-sftp/push.jsonl 2>/dev/null || echo 'not created yet'

05 / 07

Step 4 — Add a narrow log-rotation policy

The push script only appends; nothing trims or rotates the log automatically. Add one logrotate policy scoped to this exact filename, the same tool this build already uses for its other logs, so the file cannot grow without bound.

Match only the current filename and plain numeric `.N` (or `.N.gz`) rotations. A wildcard broad enough to reach another package's log — or a distribution default that adds a date suffix instead — can silently break every read command in this guide.

/var/log/vicidial-sales-sftp/push.jsonl {  weekly  rotate 12  missingok  notifempty  compress  delaycompress}

06 / 07

Step 5 — Prove that reading the log changes nothing

Record the log's hash and line count, read it once with the Step 2 command or any viewer you plan to use, then run the same two commands again. The values must match, because a read never appends a line or changes push-script state.

Hold any future dashboard or scheduled reader to the same standard before trusting it: a view must never be able to write to this file.

sha256sum /var/log/vicidial-sales-sftp/push.jsonl 2>/dev/null || echo 'no log yet'wc -l /var/log/vicidial-sales-sftp/push.jsonl 2>/dev/null || echo 'no log yet' # Read the log with whatever viewer you plan to use, then run both commands again.

07 / 07

Step 6 — Dry-run rotation and know the rollback

Dry-run the policy before trusting it, and confirm it reaches only the one path you intended.

To stop watching this log, remove only `/etc/logrotate.d/vicidial-sales-sftp`; that never touches the push script, its cron entry or any already-rotated history. To stop the exports themselves, follow the rollback in `vicidial-sales-recordings-sftp` instead — this guide only ever reads.

logrotate --debug /etc/logrotate.d/vicidial-sales-sftp 2>/dev/null || echo 'policy not created yet'