https://github.com/log-forge/unicron-storm
unicron-storm is an external testing harness that verifies whether a running Unicron deployment can ingest monitored container logs under load.
https://github.com/log-forge/unicron-storm
Last synced: 26 days ago
JSON representation
unicron-storm is an external testing harness that verifies whether a running Unicron deployment can ingest monitored container logs under load.
- Host: GitHub
- URL: https://github.com/log-forge/unicron-storm
- Owner: log-forge
- License: mit
- Created: 2026-05-23T00:45:05.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-23T04:49:53.000Z (about 1 month ago)
- Last Synced: 2026-05-23T06:36:57.039Z (about 1 month ago)
- Language: Python
- Size: 16.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# unicron-storm
`unicron-storm` is a standalone external quick-load harness for a running Unicron deployment. It does not start Unicron, include product source, package a Docker image, or run legacy harness suites.
## Purpose
The quick-load test verifies that a fresh Unicron deployment with the local agent running can ingest container logs under load. It starts temporary workload containers, enables monitoring for them, emits deterministic `quick_load ... seq=...` log lines, then compares the number of logs generated by the harness with the number of logs stored and counted by Unicron. The result helps distinguish harness-side generation limits from product-side ingestion drops.
## Prerequisites
- Python 3.
- Docker access on the machine where you run the harness.
- A reachable Unicron deployment.
- A local admin password for that deployment.
## Configure
Create a local environment file from the example:
```bash
cp .env.example .env
```
Set the quick-load knobs in `.env`:
```bash
QUICK_LOAD_CONTAINERS=1
QUICK_LOAD_LOGS_PER_SEC=1000
QUICK_LOAD_DURATION_SECONDS=30
QUICK_LOAD_RAMP_SECONDS=5
QUICK_LOAD_UNICRON_BASE_URL=https://localhost:8444
QUICK_LOAD_UNICRON_ADMIN_PASSWORD=replace-with-local-admin-password
```
`QUICK_LOAD_CONTAINERS` is the requested workload size. If Unicron accepts monitoring for only part of that set because of monitoring limits, the harness removes the unmonitored containers before signaling the workload, runs only the monitored subset, and reports the cap in the terminal summary.
Keep `.env` local. The harness also accepts `QUICK_LOAD_ADMIN_PASSWORD` or `UNICRON_ADMIN_PASSWORD`, but `QUICK_LOAD_UNICRON_ADMIN_PASSWORD` is the preferred public configuration name.
## Run
```bash
make quick-load
```
The command starts Docker workload containers, asks Unicron to monitor them, generates log lines from the monitored workload set, queries Unicron for consumed logs, prints a terminal summary, and removes the workload containers.
## Result Statuses
`passed` means the harness generated enough logs and Unicron consumed them within the allowed drop threshold.
`product_drop` means the harness generated enough monitored logs, but Unicron did not consume enough of them.
`harness_limited` means the workload containers did not generate enough logs or could not sustain the requested rate, so the run cannot prove a product-side drop.
`setup_failed` means configuration, Docker, authentication, reachability, inventory, or another setup step failed before the load result could be classified.
The terminal summary is the supported result surface.
## Methodology
`unicron-storm` measures quick-load delivery from outside an already-running Unicron deployment. It does not include or describe product internals. A run compares two counts for the same monitored workload containers: logs the harness successfully generated, and logs later found in stored logs. This separates harness-side generation limits from product-side ingestion drops.
- The harness starts Docker workload containers labeled with the quick-load scenario, workload role, and run id. Each container uses configured container log forwarding.
- Workloads wait for a coordinated start signal, emit deterministic `quick_load ... seq=...` lines at their assigned rate, and write their generated count to `/tmp/quick-load-count.json`.
- The harness waits for Unicron to list the containers, asks Unicron to monitor them, and then queries stored logs for the monitored containers. If Unicron reports a monitoring limit after accepting some containers, only the accepted monitored subset is signaled and run.
- Generated counts are read from the workload count files. Consumed counts come from a count aggregation over stored logs for each monitored container.
- Classification first checks generated count and generated rate against the configured tolerance. When generation is sufficient, it compares monitored generated logs with consumed stored logs to compute delivery and drop percentages.
- The terminal summary includes requested, generated, consumed, delivery, and drop metrics plus resource hints for the deployment and a runner host fingerprint.
- Cleanup disables monitoring where it was enabled and removes current-run quick-load containers plus stale exited quick-load workload containers.