Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/plugin-ci-workflow.yml
Original file line number Diff line number Diff line change
Expand Up @@ -274,6 +274,7 @@ jobs:
php tests/regression/threshold_recovery_database_test.php
php tests/regression/quality_must_fix_database_test.php
php tests/regression/incoming_preservation_database_test.php
php tests/regression/partition_rebuild_database_test.php
php tests/regression/review_fixes_database_test.php
php tests/regression/review_fixes_paths_database_test.php
working-directory: ${{ github.workspace }}/cacti/plugins/syslog
Expand Down
9 changes: 8 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,13 @@

--- develop ---

* bug: Keep log column resizing within the results area on both log tabs, preserve message ellipsis, and use an accessible Font Awesome export button
* feature: Standardize both schema and partition CLI help with Cacti-style version banners and options, separate maintenance warnings, and replace the unreleased millisecond converter with --convert-ms
* feature: Add a data-preserving partition rebuild CLI with optional --convert-ms, verified 10,000-row copies, interrupted-copy recovery, and database-size, extra-disk-space and several-hour maintenance warnings
* bug: Trim leading and trailing parentheses and square brackets from incoming program names before reference lookup and rule processing
* bug: Load grouped message details only on expansion, 50 at a time, preserving the displayed query's date range and filters instead of rendering every occurrence into hidden rows
* bug: Place Cancel before an active submit-type Save button in Save Search As, support Enter through a separate dialog form and the existing callback, and show a Font Awesome refresh glyph that spins only while results callbacks are running
* bug: Remove message-row and lightbulb hover tooltips, keep details in the click-open flyout, and fix the recommendation column at 20 pixels with a centered header
* bug: Remove recommendation callbacks on message hover, show a theme-aware lightbulb before messages with matching recommendations, and include the CSRF token in the details flyout's fallback POST

--- 5.0 ---
Expand Down Expand Up @@ -52,7 +59,7 @@

* issue#440: Avoid repeating successful schema operations and seed the default dashboard after schema setup, preventing duplicate table creation during installation and upgrade

* feature: Add an install-time timestamp precision choice for the logtime column (issue #325). New MariaDB installs default to millisecond TIMESTAMP(3), which preserves sub-second ordering and still RANGE partition-prunes; MySQL installs are fixed to second precision because MySQL cannot prune a fractional partitioned column, and an explicit millisecond request on MySQL is rejected. Upgrades never migrate the schema automatically; switch an existing MariaDB install with the destructive cli/updatedb_convert_ms.php utility during a maintenance window. README documents forwarder configuration (rsyslog, Cisco, Juniper, Arista, syslog-ng) for delivering sub-second timestamps
* feature: Add an install-time timestamp precision choice for the logtime column (issue #325). New MariaDB installs default to millisecond TIMESTAMP(3), which preserves sub-second ordering and still RANGE partition-prunes; MySQL installs are fixed to second precision because MySQL cannot prune a fractional partitioned column, and an explicit millisecond request on MySQL is rejected. Upgrades never migrate the schema automatically; switch an existing MariaDB install with cli/upgrade_partitioning.php --convert-ms during a maintenance window. README documents forwarder configuration (rsyslog, Cisco, Juniper, Arista, syslog-ng) for delivering sub-second timestamps
* feature: Add a manifest.json that drives upgrade-time "housecleaning": when genuinely upgrading from an older version, syslog_prune_files() (run from the shared syslog_check_upgrade() path so every version-aware entry point - the plugin upgrade hook, the re-enable path and cli/syslog_schema.php - cleans up) removes files and directories that older layouts shipped but that have since moved or been deleted (for example the old top-level database.php/functions.php now living under includes/), so a stale module can no longer redeclare a function and fatal the plugin on load after an upgrade. User-data paths (config.php, config_local.php) and VCS metadata (including .git/.md descendants nested under a tombstoned directory) are never touched, tombstones reached through a symlinked parent or that resolve outside the plugin are refused, a fresh install or same-version repair leaves the dev-only tests/ tree intact, and a CI check (tests/bin/validate-manifest.php) keeps the manifest's expected-file list from drifting
* bug: Stop partition recovery from wedging with MySQL error 1493 ('VALUES LESS THAN value must be strictly increasing') when an existing partition boundary already covers the day being created. Both syslog_partition_check() and syslog_partition_create() decided a daily partition was missing purely by name, so a table carried over from an older TO_DAYS schema, or left inconsistent by an interrupted 4.2-to-4.11 upgrade, would repeatedly emit a REORGANIZE of dMaxValue that MySQL rejected, leaving writes parked in the dMaxValue safety partition. Both now compare the target boundary against the highest existing concrete boundary, so already-covered days no longer count as missing, no longer consume the bounded per-run recovery budget, and are treated as a successful no-op, while genuine gaps are still created (issue #434)
* bug: Stop preloading every distinct program into the query-builder choice list; on a busy collector the unbounded SELECT over syslog_programs built a very large choice array that could exhaust the PHP memory limit and fatal (HTTP 503) when opening the Alert, Removal and Dashboard editors, while the Report editor (which does not use the filter builder) kept working. The program and program_id fields already resolve through the bounded AJAX suggestion endpoint, so only the small facility and priority enumerations are preloaded now
Expand Down
122 changes: 101 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@ Traps and Informs and convert them into Syslog messages on your log server.
These syslog messages can then be consumed by the syslog plugin. So, this tool
is quite handy.

Incoming program names have leading and trailing parentheses and square brackets
removed before reference lookup and rule processing. Interior punctuation is
preserved. This normalization does not rename programs in existing archived logs.

For log events that continue to be generated frequently on a device, such as
smartd's feature to notify every 15 minutes of an impending drive failure, can
be quieted using syslog's 'Re-Alert' setting.
Expand Down Expand Up @@ -142,25 +146,90 @@ MySQL installs always use second precision.
automatically, even if the configured precision changes. This avoids the
long, blocking table rewrite that an in-place precision change would require.
* **Existing production systems** – switch precision only with the CLI utility
below, during a maintenance window, after accepting that stored messages are
destroyed.
below, during a maintenance window. The unified utility preserves messages
by default.

### Converting an existing MariaDB install

```console
php plugins/syslog/cli/updatedb_convert_ms.php
php plugins/syslog/cli/upgrade_partitioning.php --convert-ms
```

The `--convert-ms` option is **MariaDB only**. It rebuilds the stored/removed
message tables and converts incoming messages to `TIMESTAMP(3)`, preserving
data in batches of at most **10,000 rows**. Already-converted incoming tables
are left alone. The replication outbox (`syslog_replication_output`) is widened
in place; undelivered rows are never discarded. Sequence high-water marks and
replication identities are preserved, including when sequence numbers repeat
at different timestamps. Existing second-resolution messages gain `.000`;
conversion cannot recover fractional timestamps that were never recorded.

The default is preservation. The explicit
`--discard-data` option deletes messages in rebuilt
tables. Rules and unrelated settings are not changed. The precision setting
is recorded only after the complete pipeline has converted.

### Rebuilding partition layouts

```console
php plugins/syslog/cli/upgrade_partitioning.php
```

The utility is **MariaDB only** and **destructive**: it truncates the
`syslog`, `syslog_incoming`, and `syslog_removed` tables (deleting all stored
messages) and changes their `logtime` column to `TIMESTAMP(3)`. The replication
outbox (`syslog_replication_output`) is widened in place so any undelivered rows
are preserved, and the sequence high-water marks of the truncated tables are kept
so remote replication identities are never reused. Alert, removal, and report
rules and all settings are preserved. The conversion is all-or-nothing and
re-runnable: the stored precision is only recorded once every target column is
`TIMESTAMP(3)`. It prompts for confirmation; pass `--confirm` to skip the prompt
in automation, and `--help` for usage. Take a database backup first.
Without `--convert-ms`, this rebuilds `syslog` and `syslog_removed` using the
configured storage engine (`syslog_install_engine`), message retention
(`syslog_retention`) and future-partition horizon
(`syslog_partition_ahead_days`), retaining their existing timestamp precision.
It preserves existing columns and indexes, adds `logtime` to a legacy
sequence-only primary key when necessary, and creates UTC daily
`UNIX_TIMESTAMP(logtime)` partitions with a final `dMaxValue` safety partition.
It does not offer weekly or monthly partitioning, since Syslog's maintenance
expects daily partitions.

Legacy `DATETIME` columns are converted to `TIMESTAMP` using the connection's
original session time zone; verify that this matches the zone used to write
those historical wall-clock values. Existing `TIMESTAMP` rows are copied in UTC
to preserve distinct events across daylight-saving clock changes.

Every existing message is copied, including older-than-retention messages;
those older rows fit in the earliest RANGE partition. Normal retention pruning
resumes when processing restarts. Indefinite retention creates daily partitions
back to the oldest valid timestamp, and future-dated messages extend the planned
horizon. Plans exceeding the server's 8192-partition limit are rejected rather
than dropping history. Custom triggers, foreign keys, or unique indexes that
exclude `logtime` require a manual migration.

`cli/syslog_schema.php --upgrade` and `--repair` repair and upgrade schema and
create missing tables; they do **not** rebuild an existing partition layout or
change its timestamp precision. Ordinary retention/horizon changes normally
need no rebuild: poller maintenance creates missing daily partitions,
reorganizes `dMaxValue` safely, and removes expired partitions. Use the explicit
rebuild utility for legacy layouts or engine changes, not routine daily rotation.

**Maintenance requirements for both commands:**

* Back up the database, stop Syslog processing, partition maintenance,
replication and **all external database writers**, and buffer new logs
upstream. The utility does not stop these services for you. Keep them stopped
until the rebuild or recovery finishes. Live log tables are temporarily absent
or incomplete; avoid using log views during the rebuild. DDL waits at most
30 seconds for metadata locks before reporting failure; let active queries
finish before retrying.
* Before confirmation, the utility reports the **estimated size of the current
Syslog database, including data and indexes**. Have **at least that much
additional free disk space on the database server** during transfer, plus
headroom for temporary files, indexes and binary logs. Database metadata is
an estimate; the utility cannot verify free space on a remote database server.
* Depending on table size and storage speed, copying and verification can take
**several hours**. `--confirm` skips the prompt but not these warnings.
* DDL is **not transactional**. Each original is renamed to `<table>_rebuild`;
a replacement is created and populated using bounded primary-key ranges.
Originals are dropped automatically only after row counts and column values
match and sequence high-water marks have been restored.
* A failure leaves originals in the live or `_rebuild` tables. Keep writers
stopped, fix the reported error, then retry with `--preserve-data` and the
same `--convert-ms` option, if used. Existing copied rows are checked rather
than overwritten; mismatches stop recovery without dropping the original.
Do not change settings or manually delete `_rebuild` tables during recovery.

### Delivering sub-second timestamps from your log forwarders

Expand Down Expand Up @@ -588,11 +657,17 @@ evaluates the rules, and records fired alerts in `syslog_logs`.
## Recommendations

Recommendations explain what a message means and what to do about it. A lightbulb
in the narrow column immediately before Message marks matching messages on the
System Logs and Alert Logs tabs, including grouped messages. Availability is
checked in batches when the page is rendered, not through hover callbacks.
Hovering shows the full message already present in the row's title without any
network requests. Click the message or row to read recommendations in the flyout.
in the fixed 20-pixel column immediately before Message marks matching messages
on the System Logs and Alert Logs tabs, including grouped messages. Availability
is checked in batches when the page is rendered, not through hover callbacks.
Message rows and lightbulbs have no hover tooltips or hover-triggered requests.
Click the message or row to read the full message and recommendations in the flyout.

Grouped Messages initially renders summaries only. Expand a group to load 50
matching occurrences at a time; Previous and Next replace that detail page.
Expansion preserves the displayed search filters and date range, including the
original bounds of relative time presets. It does not load every duplicate into
hidden rows. Refresh the results if an older grouped view has expired.

Clicking a row on the System Logs or Alert Logs tab opens a **Message details**
flyout on the right. The flyout fetches the record from the server and shows
Expand Down Expand Up @@ -747,9 +822,14 @@ master process for its workers.
`cli/syslog_schema.php` takes `--audit`, `--repair`, or `--upgrade`, as
described under Installation.

`cli/updatedb_convert_ms.php` converts an existing MariaDB install to
millisecond (`TIMESTAMP(3)`) timestamps. It is destructive (it truncates the
message tables) and takes `--confirm` and `--help`; see
`cli/upgrade_partitioning.php` rebuilds daily partitions to match the configured
engine, retention and future horizon, preserving messages by default.
`--convert-ms` also converts the message pipeline to millisecond timestamps on
MariaDB. It reports database size and warns about additional disk space and
potential several-hour duration before confirmation.

Both utilities provide Cacti-style `--help` and `--version` output.
The partition utility also takes `--confirm`; see
[Millisecond Timestamps](#millisecond-timestamps).

## Development and Testing
Expand Down
29 changes: 24 additions & 5 deletions cli/syslog_schema.php
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,11 @@
$upgrade = true;

break;
case '--version':
case '-V':
case '-v':
syslog_schema_display_version();
exit(0);
case '--help':
case '-H':
case '-h':
Expand Down Expand Up @@ -173,15 +178,29 @@ function syslog_schema_report_audit_results(bool $audit = true): bool {
return true;
}

/**
* Display the Syslog schema utility version.
*/
function syslog_schema_display_version(): void {
$version = plugin_syslog_version();
print 'Syslog Schema Utility, Version ' . trim($version['version']) . ', ' . COPYRIGHT_YEARS . PHP_EOL;
}

/**
* Display the Syslog schema utility usage and options.
*
* @return void
*/
function syslog_schema_display_help(): void {
print 'Usage: php syslog_schema.php --audit|--repair|--upgrade' . PHP_EOL;
print ' --audit Report missing tables without changing the schema.' . PHP_EOL;
print ' --repair Repair missing tables and rerun schema migrations.' . PHP_EOL;
print ' --upgrade Upgrade the schema, including missing-table repair.' . PHP_EOL;
print 'Repair and upgrade preserve existing data and preferences.' . PHP_EOL;
syslog_schema_display_version();

print PHP_EOL . 'usage: syslog_schema.php --audit | --repair | --upgrade' . PHP_EOL . PHP_EOL;
print 'Cacti utility for auditing and repairing the Syslog database schema.' . PHP_EOL;
print 'Repair and upgrade preserve existing data and preferences.' . PHP_EOL . PHP_EOL;
print 'Options:' . PHP_EOL;
print ' --audit - Report missing tables without changing the schema.' . PHP_EOL;
print ' --repair - Repair missing tables and rerun schema migrations.' . PHP_EOL;
print ' --upgrade - Upgrade the schema, including missing-table repair.' . PHP_EOL;
print ' --version - Display version information.' . PHP_EOL;
print ' --help - Display this help.' . PHP_EOL . PHP_EOL;
}
Loading
Loading