monit-docker 0.0.77__tar.gz → 0.0.78__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {monit_docker-0.0.77/monit_docker.egg-info → monit_docker-0.0.78}/PKG-INFO +19 -9
- {monit_docker-0.0.77 → monit_docker-0.0.78}/README.md +14 -2
- monit_docker-0.0.78/RELEASE +1 -0
- monit_docker-0.0.78/VERSION +1 -0
- monit_docker-0.0.78/docs/audit-migration.md +118 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/audit.md +9 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/config-cli-contract.md +1 -0
- monit_docker-0.0.78/docs/http-api-contract.md +359 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/index.rst +4 -0
- monit_docker-0.0.78/docs/journal-compatibility.md +147 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/metrics.md +15 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/roadmap.md +19 -3
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/serve.md +9 -4
- monit_docker-0.0.78/docs/supported-environments.md +97 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/__init__.py +1 -1
- monit_docker-0.0.78/monit_docker/audit_migrate.py +185 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/cli.py +40 -1
- {monit_docker-0.0.77 → monit_docker-0.0.78/monit_docker.egg-info}/PKG-INFO +19 -9
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker.egg-info/SOURCES.txt +8 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/setup.yml +6 -13
- monit_docker-0.0.78/tests/test_api_contract.py +381 -0
- monit_docker-0.0.78/tests/test_audit_migrate.py +204 -0
- monit_docker-0.0.78/tests/test_journal_compatibility.py +139 -0
- monit_docker-0.0.77/RELEASE +0 -1
- monit_docker-0.0.77/VERSION +0 -1
- {monit_docker-0.0.77 → monit_docker-0.0.78}/LICENSE +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/MANIFEST.in +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/bin/monit-docker +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/access-checks.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/alerts.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/architecture.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/check-config.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/compose.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/cron.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/dockerhub.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/dwho-http-notifications.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/filesystems.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/grafana.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/healthchecks.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/images/grafana-cpu.png +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/images/grafana-network.png +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/images/grafana-overview.png +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/maintenance.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/notifications.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/pypi.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/redis-notifications.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/restart-limit.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/runtime-checks.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/scenarios.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/simple.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/trigger-delay.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/troubleshooting.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/ui.md +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/grafana/monit-docker.json +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/alertmanager.email-slack.yml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/alertmanager.email.yml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/alertmanager.redis.yml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/alertmanager.slack.yml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/alerts.runtime.test.yml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/alerts.runtime.yml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/alerts.test.yml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/alerts.yml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/compose.audit.yaml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/compose.notifications.yaml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/compose.redis.yaml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/compose.yaml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/dwho-http/http.json +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/dwho-http/http.yml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/dwho-http/payload.json +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/dwho-http/send.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/grafana/dashboards.yml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/grafana/datasources.yml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/prometheus-notifications.yml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/prometheus.yml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/redis-webhook/Dockerfile +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/redis-webhook/bridge.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/redis-webhook/requirements.txt +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/start.sh +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/scenarios.yml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/ui/compose.actions.yaml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/ui/compose.journal.yaml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/ui/compose.yaml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/ui/prepare.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/__main__.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/__init__.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/access.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/configuration.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/docker.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/events.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/filesystems.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/http.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/http_routes.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/rules.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/scenarios.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/selection.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/state.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/syntax.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/validation.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/audit.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/audit_forward.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/audit_query.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/core/__init__.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/core/engine.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/core/manual.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/core/metrics.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/core/policy.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/core/rules.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/domain/__init__.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/domain/errors.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/domain/filesystems.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/domain/maintenance.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/domain/models.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/domain/rules.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/domain/runtime.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/manual_actions.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/notification_audit.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/outputs/__init__.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/outputs/formatting.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/outputs/prometheus.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/service.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker.egg-info/dependency_links.txt +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker.egg-info/requires.txt +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker.egg-info/top_level.txt +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/pyproject.toml +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/requirements.txt +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/setup.cfg +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/setup.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_access.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_access_docker.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_adapters.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_audit.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_audit_query.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_check_config.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_cli_contract.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_core.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_cron.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_docker_integration.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_engine.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_filesystem_mode.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_filesystems.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_health.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_httpdis_transport.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_maintenance.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_manual_actions.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_monit_docker.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_packaging.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_restart_limit.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_runtime_checks.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_runtime_docker.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_scenarios.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_service.py +0 -0
- {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_trigger_delay.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: monit-docker
|
|
3
|
-
Version: 0.0.
|
|
3
|
+
Version: 0.0.78
|
|
4
4
|
Summary: monit-docker
|
|
5
5
|
Home-page: https://github.com/decryptus/monit-docker
|
|
6
6
|
Author: Adrien Delle Cave
|
|
@@ -10,16 +10,14 @@ Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
|
|
|
10
10
|
Classifier: Natural Language :: English
|
|
11
11
|
Classifier: Operating System :: Unix
|
|
12
12
|
Classifier: Programming Language :: Python
|
|
13
|
-
Classifier: Programming Language :: Python :: 2
|
|
14
|
-
Classifier: Programming Language :: Python :: 2.7
|
|
15
13
|
Classifier: Programming Language :: Python :: 3
|
|
16
|
-
Classifier: Programming Language :: Python :: 3
|
|
17
|
-
Classifier: Programming Language :: Python :: 3.
|
|
18
|
-
Classifier: Programming Language :: Python :: 3.
|
|
14
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
17
|
Classifier: Topic :: System :: Monitoring
|
|
20
18
|
Classifier: Topic :: Terminals
|
|
21
19
|
Classifier: Topic :: Utilities
|
|
22
|
-
Requires-Python: >=
|
|
20
|
+
Requires-Python: >=3.10
|
|
23
21
|
Description-Content-Type: text/markdown
|
|
24
22
|
License-File: LICENSE
|
|
25
23
|
Requires-Dist: cryptography>=3.2.1
|
|
@@ -58,12 +56,22 @@ Dynamic: summary
|
|
|
58
56
|
[Documentation (FR)](https://www.monit-docker.com/docs/fr/) ·
|
|
59
57
|
[Documentation (EN)](https://www.monit-docker.com/docs/en/) ·
|
|
60
58
|
[Live demo](https://demo.monit-docker.com/) ·
|
|
61
|
-
[Roadmap to 1.0](docs/roadmap.md)
|
|
59
|
+
[Roadmap to 1.0](docs/roadmap.md) ·
|
|
60
|
+
[Logos and icons](ui/branding/README.md)
|
|
62
61
|
|
|
63
62
|
The [configuration and CLI compatibility baseline](docs/config-cli-contract.md)
|
|
64
63
|
records current option precedence, selectors, scenario fields and exit codes,
|
|
65
64
|
with the open decisions to resolve before 1.0.
|
|
66
65
|
|
|
66
|
+
The [journal compatibility baseline](docs/journal-compatibility.md) covers retained
|
|
67
|
+
schemas, exports and upgrade/rollback limits without rewriting archives.
|
|
68
|
+
Since **0.0.78**, the optional [audit-migrate command](docs/audit-migration.md)
|
|
69
|
+
provides a dry run and explicit conversion to a new directory with verified backups.
|
|
70
|
+
|
|
71
|
+
The [HTTP API and metrics baseline](docs/http-api-contract.md) documents response
|
|
72
|
+
fields, authentication, errors, freshness, journal pagination and metric
|
|
73
|
+
compatibility, with private-agent `curl` examples and wire-level regression tests.
|
|
74
|
+
|
|
67
75
|
For persistent action and notification history, available since **0.0.65**, see
|
|
68
76
|
the [audit journal guide](docs/audit.md). Since **0.0.66**, it also includes an optional
|
|
69
77
|
authenticated journal page with filters, bounded reads and page exports.
|
|
@@ -118,7 +126,9 @@ server, Prometheus or Grafana. Its commands are `stats`, `monit`, and optionally
|
|
|
118
126
|
|
|
119
127
|
## <a name="installation"></a>Installation
|
|
120
128
|
|
|
121
|
-
The
|
|
129
|
+
The agent requires Python **3.10+** (CI tests 3.10 and 3.12) on Linux. See the
|
|
130
|
+
[supported environments and check prerequisites](docs/supported-environments.md).
|
|
131
|
+
You need a Docker
|
|
122
132
|
daemon accessible to the account running monit-docker. For a local installation:
|
|
123
133
|
|
|
124
134
|
```sh
|
|
@@ -13,12 +13,22 @@
|
|
|
13
13
|
[Documentation (FR)](https://www.monit-docker.com/docs/fr/) ·
|
|
14
14
|
[Documentation (EN)](https://www.monit-docker.com/docs/en/) ·
|
|
15
15
|
[Live demo](https://demo.monit-docker.com/) ·
|
|
16
|
-
[Roadmap to 1.0](docs/roadmap.md)
|
|
16
|
+
[Roadmap to 1.0](docs/roadmap.md) ·
|
|
17
|
+
[Logos and icons](ui/branding/README.md)
|
|
17
18
|
|
|
18
19
|
The [configuration and CLI compatibility baseline](docs/config-cli-contract.md)
|
|
19
20
|
records current option precedence, selectors, scenario fields and exit codes,
|
|
20
21
|
with the open decisions to resolve before 1.0.
|
|
21
22
|
|
|
23
|
+
The [journal compatibility baseline](docs/journal-compatibility.md) covers retained
|
|
24
|
+
schemas, exports and upgrade/rollback limits without rewriting archives.
|
|
25
|
+
Since **0.0.78**, the optional [audit-migrate command](docs/audit-migration.md)
|
|
26
|
+
provides a dry run and explicit conversion to a new directory with verified backups.
|
|
27
|
+
|
|
28
|
+
The [HTTP API and metrics baseline](docs/http-api-contract.md) documents response
|
|
29
|
+
fields, authentication, errors, freshness, journal pagination and metric
|
|
30
|
+
compatibility, with private-agent `curl` examples and wire-level regression tests.
|
|
31
|
+
|
|
22
32
|
For persistent action and notification history, available since **0.0.65**, see
|
|
23
33
|
the [audit journal guide](docs/audit.md). Since **0.0.66**, it also includes an optional
|
|
24
34
|
authenticated journal page with filters, bounded reads and page exports.
|
|
@@ -73,7 +83,9 @@ server, Prometheus or Grafana. Its commands are `stats`, `monit`, and optionally
|
|
|
73
83
|
|
|
74
84
|
## <a name="installation"></a>Installation
|
|
75
85
|
|
|
76
|
-
The
|
|
86
|
+
The agent requires Python **3.10+** (CI tests 3.10 and 3.12) on Linux. See the
|
|
87
|
+
[supported environments and check prerequisites](docs/supported-environments.md).
|
|
88
|
+
You need a Docker
|
|
77
89
|
daemon accessible to the account running monit-docker. For a local installation:
|
|
78
90
|
|
|
79
91
|
```sh
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
0.0.78
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
0.0.78
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# Convert a retained journal to schema 2
|
|
2
|
+
|
|
3
|
+
Available since **0.0.78**. `audit-migrate` is an offline administrative command:
|
|
4
|
+
it validates existing journals and can create a **separate conversion bundle**
|
|
5
|
+
with byte-for-byte backups. It does not connect to Docker or execute actions.
|
|
6
|
+
Normal reads already support schemas 1 and 2, so conversion remains optional.
|
|
7
|
+
|
|
8
|
+
## Preview, then create the bundle
|
|
9
|
+
|
|
10
|
+
Stop **all writers** using this journal before applying a conversion, including
|
|
11
|
+
notification adapters. Use the original retention settings. Global audit options
|
|
12
|
+
go before the subcommand; migration options go after it.
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
# Default: validation and a JSON report, without creating output files.
|
|
16
|
+
monit-docker --audit-file /var/lib/monit-docker/events.jsonl \
|
|
17
|
+
--audit-max-bytes 5242880 --audit-files 5 audit-migrate
|
|
18
|
+
|
|
19
|
+
# Explicit simulation; the planned destination must not already exist.
|
|
20
|
+
monit-docker --audit-file /var/lib/monit-docker/events.jsonl \
|
|
21
|
+
--audit-max-bytes 5242880 --audit-files 5 \
|
|
22
|
+
audit-migrate --dry-run --output-dir /srv/monit-migration-001
|
|
23
|
+
|
|
24
|
+
# Explicit write, after reviewing the simulation.
|
|
25
|
+
monit-docker --audit-file /var/lib/monit-docker/events.jsonl \
|
|
26
|
+
--audit-max-bytes 5242880 --audit-files 5 \
|
|
27
|
+
audit-migrate --apply --output-dir /srv/monit-migration-001
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The destination's parent must exist and be writable. No existing file or directory
|
|
31
|
+
is replaced, including an earlier conversion bundle. Files are mode 0600 and
|
|
32
|
+
directories 0700, owned by the user running the command. Reserve disk space for
|
|
33
|
+
both the original-byte backup and converted copy; escaped text can grow.
|
|
34
|
+
|
|
35
|
+
Both modes take the journal lock for a consistent view. A busy lock fails
|
|
36
|
+
immediately; the command does not wait indefinitely. Simulation may create the
|
|
37
|
+
companion `.lock` file but never changes journal data. Holding the lock protects
|
|
38
|
+
against cooperating agent writers; it does not make unrelated administrative file
|
|
39
|
+
edits safe. Keep writers stopped until any operator-controlled switch is complete.
|
|
40
|
+
|
|
41
|
+
## Bundle and verification
|
|
42
|
+
|
|
43
|
+
| Path in the new directory | Contents |
|
|
44
|
+
| --- | --- |
|
|
45
|
+
| `backup/events.jsonl` and retained suffixes | Original bytes, including original schema versions |
|
|
46
|
+
| `converted/events.jsonl` and retained suffixes | Schema 2 JSONL, preserving file layout and record order |
|
|
47
|
+
| `manifest.json` | Final completion marker, counts, settings and SHA-256 checksums |
|
|
48
|
+
|
|
49
|
+
The command processes only the configured journal and its numbered archives, not
|
|
50
|
+
all files in its parent directory. Higher-numbered archives outside `--audit-files`
|
|
51
|
+
cause an explicit error rather than a silently incomplete conversion. Adjust the
|
|
52
|
+
setting or separately archive those files before proceeding. The maximum supported
|
|
53
|
+
retention count remains 100.
|
|
54
|
+
|
|
55
|
+
The JSON report has `status: "dry_run"` or `"complete"`, `target_schema: 2`, total
|
|
56
|
+
`records`, `legacy_records` and a per-file inventory. Each entry reports original
|
|
57
|
+
and converted sizes/checksums, schema counts and an ordered identity/correlation
|
|
58
|
+
checksum. The manifest has its own `manifest_version: 1`, unrelated to event or
|
|
59
|
+
HTTP schema versions. It contains paths and checksums, not event text; protect it
|
|
60
|
+
along with the private history.
|
|
61
|
+
|
|
62
|
+
Validation runs before destination creation. During conversion the source is
|
|
63
|
+
checked against that inventory, the original-byte backup is reread, and converted
|
|
64
|
+
data is reread to verify schema, count, ordered identities/correlations and the
|
|
65
|
+
expected full-content checksum. Only then is the manifest finalized. Additional
|
|
66
|
+
scalar fields and null/numeric values are retained. Text follows the existing
|
|
67
|
+
[canonical escaping rules](audit.md#text-encoding-shared-by-all-outputs); already
|
|
68
|
+
valid schema 2 values are not escaped again. Converting the output again preserves
|
|
69
|
+
its normalized bytes. Neither deduplication nor sorting is performed.
|
|
70
|
+
|
|
71
|
+
The tool streams records; it does not accumulate the full retained history in
|
|
72
|
+
memory. Each source/converted record must fit the 64 KiB event limit. Both original
|
|
73
|
+
and converted files must fit the configured full-read bound (`--audit-max-bytes`
|
|
74
|
+
plus one maximum-size event). Conversion can require a larger limit than the
|
|
75
|
+
source because visible escapes expand text. Use that same limit when reading the
|
|
76
|
+
converted archive. Published 0.0.65 defaulted to 10 MiB per file, versus 5 MiB since
|
|
77
|
+
0.0.66; do not accidentally reduce the limit during this operation.
|
|
78
|
+
|
|
79
|
+
## Errors and interruption
|
|
80
|
+
|
|
81
|
+
Exit status is **0** for a successful simulation or completed bundle, **2** for
|
|
82
|
+
invalid CLI arguments and **119** for a migration failure. An English diagnostic
|
|
83
|
+
is written to stderr on failure; successful reports are JSON on stdout.
|
|
84
|
+
|
|
85
|
+
Unsupported versions, invalid/noncanonical text, nested fields, truncated or
|
|
86
|
+
oversized records, duplicate JSON keys and non-finite numbers are rejected.
|
|
87
|
+
Duplicate-key/number checks are deliberately stricter than ordinary historical
|
|
88
|
+
reads to avoid silently losing information during physical conversion. Symlink
|
|
89
|
+
data/lock files and non-regular files are refused. A nonexistent journal fails;
|
|
90
|
+
an existing empty journal is valid and produces an empty converted file.
|
|
91
|
+
|
|
92
|
+
If a write or verification fails, the original journal remains untouched. The
|
|
93
|
+
partial destination is retained for inspection, without a completed manifest.
|
|
94
|
+
A process interruption may leave `manifest.json.tmp`. **Do not use a bundle that
|
|
95
|
+
has no final `manifest.json` with `status: "complete"`.** Resolve the cause, preserve
|
|
96
|
+
the partial output if needed, and rerun with a new destination. There is no
|
|
97
|
+
automatic resume, deletion or overwrite of previous attempts. Check exit status
|
|
98
|
+
even if files are present; filesystem sync failures are still failures.
|
|
99
|
+
|
|
100
|
+
## Optional activation and rollback
|
|
101
|
+
|
|
102
|
+
Creating a bundle does not change the agent's configured path. After verifying
|
|
103
|
+
the report and keeping all writers stopped, an operator can point `--audit-file`
|
|
104
|
+
to the converted directory or copy the converted set to a prepared persistent
|
|
105
|
+
directory. Match retention settings and ownership to the service user. Preserve
|
|
106
|
+
the original directory and backup outside the rotation path. Switching paths
|
|
107
|
+
invalidates existing journal browsing cursors; reload the first page.
|
|
108
|
+
|
|
109
|
+
Restart writers only after checking a full export from the chosen path. Do not
|
|
110
|
+
concatenate original and converted copies: they contain the same event IDs.
|
|
111
|
+
For rollback, stop writers, preserve any events appended after activation and
|
|
112
|
+
restore a verified backup with appropriate ownership. Restoring an older backup
|
|
113
|
+
does not include those later events and must not replay their actions. This
|
|
114
|
+
command converts journal files only, not configuration or action state.
|
|
115
|
+
|
|
116
|
+
See [journal compatibility](journal-compatibility.md) for the broader upgrade
|
|
117
|
+
procedure and [supported environments](supported-environments.md) for platform
|
|
118
|
+
and storage requirements.
|
|
@@ -68,6 +68,11 @@ escaping required by a destination.
|
|
|
68
68
|
|
|
69
69
|
## Storage and recovery
|
|
70
70
|
|
|
71
|
+
See [journal schema compatibility](journal-compatibility.md) for mixed historical
|
|
72
|
+
events, export limits, upgrade/rollback steps and rules for future schema changes.
|
|
73
|
+
The optional [audit-migrate command](audit-migration.md), available since 0.0.78,
|
|
74
|
+
creates verified schema 2 copies with original-byte backups and defaults to simulation.
|
|
75
|
+
|
|
71
76
|
The agent enables its journal when configured with rules, manual actions or the
|
|
72
77
|
notification webhook. Use a persistent mount and an explicit path:
|
|
73
78
|
|
|
@@ -273,6 +278,10 @@ An ID groups recorded events; it does not invent missing lifecycle stages.
|
|
|
273
278
|
|
|
274
279
|
### Bounded reads and downloads
|
|
275
280
|
|
|
281
|
+
See the [HTTP API contract](http-api-contract.md#journal-pages-and-exports) for
|
|
282
|
+
page fields, filter syntax, authentication, cursor error codes and a complete
|
|
283
|
+
`curl` example exporting the displayed page.
|
|
284
|
+
|
|
276
285
|
`GET /v1/audit` returns up to 100 events, newest first, with a signed continuation
|
|
277
286
|
cursor. Each request reads at most 1 MiB of journal bytes and retains at most
|
|
278
287
|
512 KiB of serialized event data, plus bounded parsing/response overhead. At most
|
|
@@ -173,6 +173,7 @@ when converting long commands into scenarios.
|
|
|
173
173
|
| `restart-reset` | `--state-file` and exact lowercase 64-hex `--container-id` required; JSON `{container_id, status: "rearmed"}`; requires recorded attempts |
|
|
174
174
|
| `audit-export` | `--format jsonl` (default) or `csv`; optional `--category action\|notification` and `--since` with timezone |
|
|
175
175
|
| `audit-send` | Export filters plus required `--url` HTTPS receiver and optional `--token-file`; forwards JSON events and reports acknowledgements on stderr |
|
|
176
|
+
| `audit-migrate` (0.0.78+) | Simulation by default or `--dry-run`; `--apply --output-dir NEW_DIRECTORY` creates original-byte backups, converted journals and a verified manifest without connecting to Docker |
|
|
176
177
|
|
|
177
178
|
`stats --output json` emits one JSON object per container, not a single array.
|
|
178
179
|
Each maps the container name to requested resource values. Memory, disk and I/O
|
|
@@ -0,0 +1,359 @@
|
|
|
1
|
+
# HTTP API and metrics compatibility baseline
|
|
2
|
+
|
|
3
|
+
This reference describes the **0.0.77 behavior** of the private agent listener.
|
|
4
|
+
It is a tested 0.0.x baseline, not an approved 1.0 stability promise. The
|
|
5
|
+
[roadmap](roadmap.md) tracks the remaining compatibility decisions. See the
|
|
6
|
+
[configuration and CLI baseline](config-cli-contract.md) for startup options.
|
|
7
|
+
|
|
8
|
+
## Scope and transport
|
|
9
|
+
|
|
10
|
+
`serve` listens on `127.0.0.1:9808` by default. HTTPdis handles routing and
|
|
11
|
+
serialization; Sonicprobe bounds the worker pool. These routes describe the
|
|
12
|
+
agent directly. The [optional Nginx UI proxy](ui.md) exposes a smaller set of
|
|
13
|
+
routes, adds authentication and may return its own error responses. In
|
|
14
|
+
particular, the public demo does not forward `/metrics`, `/healthz`, `/readyz`
|
|
15
|
+
or the notification receiver. Use the private agent address in the examples.
|
|
16
|
+
|
|
17
|
+
Agent JSON responses use `application/json; charset=utf-8`, a trailing newline,
|
|
18
|
+
and finite JSON numbers. Normal route responses and adapter errors include:
|
|
19
|
+
|
|
20
|
+
```text
|
|
21
|
+
Cache-Control: no-store
|
|
22
|
+
X-Content-Type-Options: nosniff
|
|
23
|
+
Referrer-Policy: no-referrer
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
`HEAD` on read routes has the corresponding status, content type and
|
|
27
|
+
representation length, but no body. A separate GET may differ as time, queued
|
|
28
|
+
actions or the journal advance. There is no CORS preflight endpoint: `OPTIONS`
|
|
29
|
+
returns 405 without `Access-Control-Allow-Origin`. No route changes configuration
|
|
30
|
+
or explicitly starts a monitoring cycle. Reads never execute Docker actions.
|
|
31
|
+
|
|
32
|
+
| Route | Methods | Availability / authentication | Normal response |
|
|
33
|
+
| --- | --- | --- | --- |
|
|
34
|
+
| `/healthz` | GET, HEAD | Always, no agent credential | 200 `{"alive":true}` |
|
|
35
|
+
| `/readyz` | GET, HEAD | Always, no agent credential | 200 `{"ready":true}` or 503 `{"ready":false}` |
|
|
36
|
+
| `/v1/status` | GET, HEAD | Always, no agent credential | 200 cached status, including degraded states |
|
|
37
|
+
| `/metrics` | GET, HEAD | Always, no agent credential | 200 Prometheus text, including degraded states |
|
|
38
|
+
| `/v1/actions` | POST | Manual actions enabled; action token and exact Origin | 202 request record |
|
|
39
|
+
| `/v1/audit` | GET, HEAD | Journal reader enabled; audit token and actor | 200 bounded event page |
|
|
40
|
+
| `/v1/audit/export` | GET, HEAD | Same journal authentication | 200 JSONL or CSV attachment |
|
|
41
|
+
| `/v1/notifications` | POST | Notification audit receiver enabled; separate bearer token | 202 receipt count |
|
|
42
|
+
|
|
43
|
+
Use the canonical paths above, without trailing slashes. Unknown reads return
|
|
44
|
+
404. POST/PUT/PATCH/DELETE/OPTIONS on read-only routes return 405. A GET on the
|
|
45
|
+
POST-only action route currently returns 404, not 405. Disabled actions and
|
|
46
|
+
notifications return 405; a disabled journal reader returns 404. A 405 response
|
|
47
|
+
has an `Allow` header based on the declared route, even if its capability is
|
|
48
|
+
disabled. Arbitrary unsupported HTTP verbs are not part of this baseline.
|
|
49
|
+
Unexpected handler failures return 500 `{"error":"internal_error"}` rather
|
|
50
|
+
than a raw exception message.
|
|
51
|
+
|
|
52
|
+
## Cached status
|
|
53
|
+
|
|
54
|
+
Clients must ignore additional JSON fields and inspect capability objects rather
|
|
55
|
+
than infer support from the URL version. Existing field names and meanings below
|
|
56
|
+
are covered by regression tests; JSON object ordering is not an interface.
|
|
57
|
+
|
|
58
|
+
| Field | JSON type | Meaning |
|
|
59
|
+
| --- | --- | --- |
|
|
60
|
+
| `api_version` | integer | Currently 1; independent of package and journal versions |
|
|
61
|
+
| `running` | boolean | A monitoring cycle is collecting or applying rules; not a manual-action activity flag |
|
|
62
|
+
| `ready` | boolean | Last completed cycle succeeded and its monotonic age is at most `stale_after` |
|
|
63
|
+
| `last_cycle_success` | boolean | False at startup; outcome of the last completed cycle |
|
|
64
|
+
| `last_cycle_finished_at` | number or null | Last cycle completion, Unix seconds |
|
|
65
|
+
| `last_success_at` | number or null | Last successful completion, Unix seconds; retained after later failure/staleness |
|
|
66
|
+
| `age_seconds` | number or null | Nonnegative monotonic age of that success; null before first success or after invalidation for manual execution |
|
|
67
|
+
| `last_error_code` | integer or null | Agent failure code, not an HTTP status; no raw exception message |
|
|
68
|
+
| `cycles_total`, `errors_total` | integers | Completed cycles / failed cycles since process startup |
|
|
69
|
+
| `actions` | object | Automatic decision counters, described below |
|
|
70
|
+
| `containers` | array | Complete fresh snapshot, or `[]` when not ready |
|
|
71
|
+
| `manual_actions` | object | Always present in this baseline; `{"enabled":false}` when disabled |
|
|
72
|
+
| `audit_enabled` | boolean | Whether the authenticated journal reader is available, not merely whether audit writing is configured |
|
|
73
|
+
|
|
74
|
+
`actions` always has `executed`, `cooldown`, `pending`, `restart-limit`,
|
|
75
|
+
`maintenance` and `dry-run`, initially zero. These count automatic rule decisions,
|
|
76
|
+
not manual requests. One rule can produce multiple decisions. Successful actions
|
|
77
|
+
before a later failure remain counted; failed actions are not counted as
|
|
78
|
+
`executed`. All process counters reset on restart.
|
|
79
|
+
|
|
80
|
+
Starting a new cycle does not immediately invalidate a still-fresh previous
|
|
81
|
+
success: `running:true` and `ready:true` may coexist. At startup, after a failed
|
|
82
|
+
cycle or after staleness, status and metrics remain HTTP 200 while readiness is
|
|
83
|
+
503 and container measurements are withheld. Staleness alone does not increment
|
|
84
|
+
errors or create a failure code. A failed cycle clears the exposed containers;
|
|
85
|
+
its prior success timestamp and age can still be present. A manual execution
|
|
86
|
+
invalidates freshness before calling Docker, including if the attempt fails.
|
|
87
|
+
Successful metadata-only collection can be ready without numerical measurements.
|
|
88
|
+
|
|
89
|
+
### Container fields
|
|
90
|
+
|
|
91
|
+
Each snapshot includes the fields below; unavailable or unrequested numerical
|
|
92
|
+
fields are `null`, not formatted strings or synthetic zeroes. Container order is
|
|
93
|
+
not guaranteed. The collector uses full Docker IDs and names without a leading
|
|
94
|
+
slash. A replacement container has a new identity.
|
|
95
|
+
|
|
96
|
+
| Fields | JSON type / units |
|
|
97
|
+
| --- | --- |
|
|
98
|
+
| `id`, `name`, `status` | Strings; Docker identity, name and state |
|
|
99
|
+
| `pid` | Integer or null; host PID of the container's initial process |
|
|
100
|
+
| `health` | `healthy`, `unhealthy`, `starting`, `none` or `unknown` |
|
|
101
|
+
| `mem_usage`, `mem_limit`, `io_read`, `io_write`, `net_rx`, `net_tx` | Numbers or null, bytes |
|
|
102
|
+
| `mem_percent`, `cpu_percent` | Numbers or null, percentages; CPU may exceed 100 |
|
|
103
|
+
| `oom_events`, `starts_recent` | Nonnegative integers or null, counts in the requested window |
|
|
104
|
+
| `pids_current`, `pids_limit` | Nonnegative integers or null; process/thread count and finite cgroup limit |
|
|
105
|
+
| `pids_percent` | Number or null, percentage of the finite PID limit |
|
|
106
|
+
| `event_window_seconds`, `event_window_end` | Nonnegative integers or null; window duration and cutoff in Unix seconds |
|
|
107
|
+
| `event_history_complete` | Integer 0 or 1, or null; retained daemon-buffer completeness, not durable history |
|
|
108
|
+
| `manual_actions_protected` | Boolean, false by default; protects against manual actions only |
|
|
109
|
+
| `restart_attempts`, `restart_limit` | Nonnegative / positive integers or null; automatic restart policy metadata |
|
|
110
|
+
| `maintenance_active` | Boolean; whether maintenance was active at collection time |
|
|
111
|
+
| `maintenance_until` | Number or null, configured expiry in Unix seconds |
|
|
112
|
+
| `filesystems` | Array, empty when none were collected |
|
|
113
|
+
|
|
114
|
+
Each filesystem object has string `group` and `path`, plus these measurements:
|
|
115
|
+
|
|
116
|
+
- `disk_usage`, `disk_available`, `disk_total`: bytes or null.
|
|
117
|
+
- `disk_percent`: used / (used + available) × 100, or null.
|
|
118
|
+
- `inode_usage`, `inode_available`, `inode_total`: inode counts or null.
|
|
119
|
+
- `inode_percent`: used / total × 100, or null.
|
|
120
|
+
- `fs_mode`: `ro`, `rw` or null.
|
|
121
|
+
- `fs_readable`, `fs_writable`, `fs_executable`: integer 0 or 1, or null,
|
|
122
|
+
for the explicitly configured access identity.
|
|
123
|
+
|
|
124
|
+
See [filesystem semantics](filesystems.md), [ACL-aware access checks](access-checks.md)
|
|
125
|
+
and [runtime checks](runtime-checks.md). Maintenance indicators are sampled state,
|
|
126
|
+
not a live countdown; repeated GET requests do not update the snapshot.
|
|
127
|
+
|
|
128
|
+
## Manual actions
|
|
129
|
+
|
|
130
|
+
Send exactly three string fields: `request_id` (32 lowercase hexadecimal
|
|
131
|
+
characters), `container_id` (full 64 lowercase hexadecimal characters) and
|
|
132
|
+
`action`. Discover available commands through
|
|
133
|
+
`manual_actions.allowed_states`; its values are arrays of acceptable cached
|
|
134
|
+
Docker states. Do not send shell commands, aliases or extra arguments.
|
|
135
|
+
|
|
136
|
+
| Action | Accepted cached states |
|
|
137
|
+
| --- | --- |
|
|
138
|
+
| `start` | `created`, `exited` |
|
|
139
|
+
| `stop` | `running`, `restarting` |
|
|
140
|
+
| `restart` | `running` |
|
|
141
|
+
| `restart-reset` | `created`, `running`, `paused`, `restarting`, `exited`, `dead`; also requires a nonzero restart budget counter |
|
|
142
|
+
| `maintenance-15m`, `maintenance-1h`, `maintenance-off` | Same states as restart-reset; present only when manual maintenance is enabled |
|
|
143
|
+
|
|
144
|
+
The request needs exactly one `X-Monit-Action-Token` and one `Origin`, matching
|
|
145
|
+
the configured values. With trusted proxy attribution enabled, exactly one
|
|
146
|
+
nonblank `X-Monit-Actor` is required (at most 128 characters, no ASCII controls
|
|
147
|
+
or DEL). Otherwise the actor is `anonymous` and a supplied actor is ignored.
|
|
148
|
+
Credentials are not returned in status. A trusted proxy must replace client actor
|
|
149
|
+
headers; see [authentication setup](ui.md).
|
|
150
|
+
|
|
151
|
+
The body limit is **1024 bytes**, inclusive. Actions currently require
|
|
152
|
+
`Content-Type: application/json` without parameters, so even
|
|
153
|
+
`application/json; charset=utf-8` is rejected. The body must have a single ASCII
|
|
154
|
+
decimal `Content-Length` of at most five digits and no `Transfer-Encoding`.
|
|
155
|
+
Zero length is rejected with 413. JSON decoding/framing failures return 400;
|
|
156
|
+
read timeouts return 408. These are current adapter behaviors, not a general
|
|
157
|
+
HTTP parser specification.
|
|
158
|
+
|
|
159
|
+
### Acceptance, completion and retries
|
|
160
|
+
|
|
161
|
+
202 returns a record with `request_id`, `container_id`, `action`, `actor`,
|
|
162
|
+
`container_name`, `status`, `submitted_at`, `finished_at`, `error` and `error_code`.
|
|
163
|
+
Timestamps are Unix-second numbers; `finished_at`, `error` and `error_code` start
|
|
164
|
+
as null. States are `queued`, `running`, `succeeded`, `failed`. Poll
|
|
165
|
+
`manual_actions.recent` in `/v1/status` for results; there is no GET-by-request-ID
|
|
166
|
+
route. Records are in submission order and at most 32 are retained in memory.
|
|
167
|
+
|
|
168
|
+
One action may be queued or running across the agent. The scheduler executes it
|
|
169
|
+
between cycles and refreshes measurements after an execution attempt. Queue
|
|
170
|
+
expiry is checked when dequeuing, after more than 60 monotonic seconds; it is not
|
|
171
|
+
a completion deadline. Protection, selection, state and cooldown are checked
|
|
172
|
+
again before the mutation, so an accepted request may later fail.
|
|
173
|
+
|
|
174
|
+
A retained ID with the same three fields **and actor** returns its existing record
|
|
175
|
+
with HTTP 202, even after completion or if the agent is now unready. It does not
|
|
176
|
+
execute again. Different payload/actor with that ID returns 409. This is bounded,
|
|
177
|
+
process-local deduplication: eviction or restart removes that guarantee. A timeout
|
|
178
|
+
does not establish whether an action executed. Inspect status and the retained
|
|
179
|
+
journal before deciding whether to submit another mutation.
|
|
180
|
+
|
|
181
|
+
| Submission status | `error` reasons |
|
|
182
|
+
| --- | --- |
|
|
183
|
+
| 400 | `invalid_request`, `invalid_length`, `invalid_json` |
|
|
184
|
+
| 403 | `forbidden`, `origin_rejected`, `container_protected` |
|
|
185
|
+
| 405 | `method_not_allowed` |
|
|
186
|
+
| 408 | `request_timeout` |
|
|
187
|
+
| 409 | `request_id_conflict`, `busy`, `not_ready`, `not_selected`, `state_changed`, `no_restart_attempts` |
|
|
188
|
+
| 413 | `request_too_large` |
|
|
189
|
+
| 415 | `json_required` |
|
|
190
|
+
| 503 | `audit_unavailable` |
|
|
191
|
+
|
|
192
|
+
Transport/authentication failures are not action records. Audit failures can
|
|
193
|
+
replace a rejection response with 503. Completed record reasons include
|
|
194
|
+
`expired`, `audit_unavailable`, `unsupported_action`, `busy`, `not_selected`,
|
|
195
|
+
`container_protected`, `state_changed`, `no_restart_attempts`, `cooldown` and `execution_failed`.
|
|
196
|
+
`execution_failed` can carry an agent `error_code`; raw exception text is not
|
|
197
|
+
exposed. Reasons and state names remain English machine-readable values.
|
|
198
|
+
|
|
199
|
+
## Journal pages and exports
|
|
200
|
+
|
|
201
|
+
Both routes require exactly one `X-Monit-Audit-Token` and one valid
|
|
202
|
+
`X-Monit-Actor`, with the same actor length/control restrictions as above.
|
|
203
|
+
Authentication applies even to an empty journal. HTTP 200 returns:
|
|
204
|
+
|
|
205
|
+
| Field | Type / meaning |
|
|
206
|
+
| --- | --- |
|
|
207
|
+
| `records` | Array of retained events, newest file records first |
|
|
208
|
+
| `next_cursor` | Opaque string for the next older page, or null when exhausted |
|
|
209
|
+
| `page_cursor` | Opaque string replaying this page's snapshot, for export |
|
|
210
|
+
| `scanned_bytes` | Nonnegative integer, journal bytes read including identity checks |
|
|
211
|
+
| `limit` | Integer, currently 100 records per page |
|
|
212
|
+
|
|
213
|
+
Accept an empty `records` array with a non-null `next_cursor`: a bounded scan may
|
|
214
|
+
find no matches yet. Reads scan at most 1 MiB and collect at most 512 KiB of encoded
|
|
215
|
+
event data per page, plus response overhead. No client-selectable page size exists.
|
|
216
|
+
The [audit guide](audit.md) defines event fields, escaping and retention. Journal
|
|
217
|
+
schema version 2 is independent of HTTP `api_version`; its longer-term evolution
|
|
218
|
+
policy remains a separate roadmap item.
|
|
219
|
+
|
|
220
|
+
| Query parameter | Meaning |
|
|
221
|
+
| --- | --- |
|
|
222
|
+
| `since`, `until` | Inclusive ISO timestamps with a timezone; since must not exceed until |
|
|
223
|
+
| `container` | Case-insensitive substring of container name or ID, not a glob or regular expression |
|
|
224
|
+
| `source` | `manual` or `automatic` |
|
|
225
|
+
| `category` | `action` or `notification` |
|
|
226
|
+
| `result` | `pending`, `succeeded`, `failed`, `rejected`, `skipped`, `simulated`, `accepted`, `received` |
|
|
227
|
+
| `correlation_id` | Exact, case-sensitive ID |
|
|
228
|
+
| `cursor` | Opaque signed continuation or page token |
|
|
229
|
+
| `format` | `jsonl` (default) or `csv`; affects the export route, not the JSON page envelope |
|
|
230
|
+
|
|
231
|
+
Filters combine with AND. Unknown or repeated query keys are rejected; empty
|
|
232
|
+
values are ignored. Each nonempty filter is at most 256 printable characters.
|
|
233
|
+
The encoded query is limited to 32768 characters and a cursor to 24000.
|
|
234
|
+
Cursors are bound to the authenticated actor and exact filter values, exclude
|
|
235
|
+
later appends, and expire after 15 minutes or loss of unread snapshot data.
|
|
236
|
+
Changing only export format is permitted. An agent restart changes the signing
|
|
237
|
+
key: old cursors become invalid, with 400 rather than 410.
|
|
238
|
+
|
|
239
|
+
Errors are `{"error":"REASON"}`: 400 `invalid_filters` or `invalid_cursor`,
|
|
240
|
+
403 `forbidden`, 404 `not_found` when disabled, 410 `cursor_expired`, or 503
|
|
241
|
+
`audit_busy` / `audit_unavailable`. A 503 is an explicit read failure, never an
|
|
242
|
+
empty successful history. Cursor and storage errors do not reveal file paths.
|
|
243
|
+
|
|
244
|
+
`/v1/audit/export` returns one bounded page, not the whole journal. Pass the
|
|
245
|
+
displayed `page_cursor` and the same filters. Its media type is
|
|
246
|
+
`application/x-ndjson; charset=utf-8` or `text/csv; charset=utf-8`, with
|
|
247
|
+
`Content-Disposition: attachment; filename="monit-docker-events.jsonl"` (or
|
|
248
|
+
`.csv`). JSONL has one event per line; CSV has the documented event-column header.
|
|
249
|
+
An empty JSONL export is empty; an empty CSV export still has its header.
|
|
250
|
+
Use the administrative `audit-export` command for all retained events.
|
|
251
|
+
|
|
252
|
+
## Notification receipts
|
|
253
|
+
|
|
254
|
+
`POST /v1/notifications` accepts the Alertmanager version-4 webhook shape, with
|
|
255
|
+
`Authorization: Bearer TOKEN` using the separately configured audit token. No
|
|
256
|
+
Origin or actor header is required. It accepts JSON content-type parameters and
|
|
257
|
+
has an inclusive **65536-byte** limit; length/framing rules otherwise match
|
|
258
|
+
actions. Manual actions do not need to be enabled for this route.
|
|
259
|
+
|
|
260
|
+
Required top-level fields are `version: "4"`, `status: "firing"` or `"resolved"`,
|
|
261
|
+
string `receiver` (at most 256 characters), string `groupKey` (at most 2048), and
|
|
262
|
+
`alerts` (1..100 objects). `truncatedAlerts` must be zero if supplied. Each alert
|
|
263
|
+
requires a firing/resolved `status` and a nonempty string `labels.alertname` of at
|
|
264
|
+
most 256 characters. Optional `fingerprint`, `startsAt`, `endsAt` are strings of
|
|
265
|
+
at most 256 characters; timestamps are not parsed here. Extra webhook fields are
|
|
266
|
+
accepted but arbitrary labels/annotations are not copied into the journal.
|
|
267
|
+
|
|
268
|
+
The whole batch is validated before writes. HTTP 202 returns
|
|
269
|
+
`{"recorded":N,"delivery_status":"not_reported"}` after receipt recording; it
|
|
270
|
+
does not prove email/Slack delivery. Invalid payloads return 400
|
|
271
|
+
`invalid_notification`; storage failure returns 503 `audit_unavailable`.
|
|
272
|
+
A write failure partway through a valid batch may leave earlier receipts stored.
|
|
273
|
+
Retries can repeat receipts; `notification_id` provides correlation, not durable
|
|
274
|
+
deduplication. See [notification audit semantics](audit.md).
|
|
275
|
+
|
|
276
|
+
## Prometheus contract
|
|
277
|
+
|
|
278
|
+
The [metrics reference](metrics.md) is the name/type/unit/label catalogue for this
|
|
279
|
+
baseline. `/metrics` uses `text/plain; version=0.0.4; charset=utf-8` with a final
|
|
280
|
+
newline. Required names, declared types, label keys and representative values
|
|
281
|
+
are covered by `tests/test_api_contract.py` alongside existing collector tests.
|
|
282
|
+
|
|
283
|
+
- Agent counters reset on process restart; Docker I/O/network counters have their
|
|
284
|
+
own reset lifecycle. Percentages use 0..100 units, not 0..1 ratios; CPU can exceed 100.
|
|
285
|
+
- Container samples require ready, fresh cached data. Unknown or unrequested
|
|
286
|
+
measurements are omitted; a known zero still emits a sample. Empty metric
|
|
287
|
+
families can retain HELP/TYPE lines. Last-success metadata is absent until the
|
|
288
|
+
first success and remains present after subsequent degradation.
|
|
289
|
+
- Health emits the current state with value 1, not five one-hot zero/one series.
|
|
290
|
+
Boolean metrics use numeric 0/1. Event-window counts are gauges, not counters.
|
|
291
|
+
- Container labels are `id`, `name`, plus only the specific keys in the catalogue.
|
|
292
|
+
Manual protection, actor, reason and arbitrary Docker labels are not metrics.
|
|
293
|
+
- Label backslashes, newlines and double quotes are escaped. Sample order, label
|
|
294
|
+
order and HELP prose are not compatibility promises. There are no explicit
|
|
295
|
+
sample timestamps. New metric families or JSON fields may be added.
|
|
296
|
+
|
|
297
|
+
## curl examples
|
|
298
|
+
|
|
299
|
+
Read the private agent (these four calls never execute a monitoring cycle):
|
|
300
|
+
|
|
301
|
+
```sh
|
|
302
|
+
AGENT_URL='http://127.0.0.1:9808'
|
|
303
|
+
curl --fail-with-body --silent --show-error "$AGENT_URL/healthz"
|
|
304
|
+
curl --fail-with-body --silent --show-error "$AGENT_URL/readyz"
|
|
305
|
+
curl --fail-with-body --silent --show-error "$AGENT_URL/v1/status"
|
|
306
|
+
curl --fail-with-body --silent --show-error "$AGENT_URL/metrics"
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
For a direct, authorized mutation, configure actions first and supply your actual
|
|
310
|
+
token, allowed origin and selected full container ID. Keep the generated request
|
|
311
|
+
ID to correlate status and journal records. This example **restarts a container**:
|
|
312
|
+
|
|
313
|
+
```sh
|
|
314
|
+
ACTION_TOKEN=$(cat /path/to/private/action-token)
|
|
315
|
+
ACTION_ORIGIN='https://monitor.example'
|
|
316
|
+
CONTAINER_ID='replace-with-a-selected-64-character-container-id'
|
|
317
|
+
REQUEST_ID=$(python3 -c 'import secrets; print(secrets.token_hex(16))')
|
|
318
|
+
curl --fail-with-body --silent --show-error "$AGENT_URL/v1/actions" \
|
|
319
|
+
-H 'Content-Type: application/json' \
|
|
320
|
+
-H "X-Monit-Action-Token: $ACTION_TOKEN" \
|
|
321
|
+
-H "Origin: $ACTION_ORIGIN" \
|
|
322
|
+
-H 'X-Monit-Actor: operator' \
|
|
323
|
+
--data "{\"request_id\":\"$REQUEST_ID\",\"container_id\":\"$CONTAINER_ID\",\"action\":\"restart\"}"
|
|
324
|
+
curl --fail-with-body --silent --show-error "$AGENT_URL/v1/status"
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
Browse the journal using its separate token, then export exactly the same page
|
|
328
|
+
(Python reads the saved JSON; no extra JSON command-line utility is needed):
|
|
329
|
+
|
|
330
|
+
```sh
|
|
331
|
+
AUDIT_TOKEN=$(cat /path/to/private/audit-read-token)
|
|
332
|
+
curl --fail-with-body --silent --show-error --get "$AGENT_URL/v1/audit" \
|
|
333
|
+
-H "X-Monit-Audit-Token: $AUDIT_TOKEN" -H 'X-Monit-Actor: operator' \
|
|
334
|
+
--data-urlencode 'category=action' --data-urlencode "correlation_id=$REQUEST_ID" \
|
|
335
|
+
--output page.json
|
|
336
|
+
PAGE_CURSOR=$(python3 -c 'import json; print(json.load(open("page.json"))["page_cursor"])')
|
|
337
|
+
curl --fail-with-body --silent --show-error --get "$AGENT_URL/v1/audit/export" \
|
|
338
|
+
-H "X-Monit-Audit-Token: $AUDIT_TOKEN" -H 'X-Monit-Actor: operator' \
|
|
339
|
+
--data-urlencode 'category=action' --data-urlencode "correlation_id=$REQUEST_ID" \
|
|
340
|
+
--data-urlencode "cursor=$PAGE_CURSOR" --data-urlencode 'format=csv' \
|
|
341
|
+
--output action-events.csv
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
These are direct private-agent examples, not commands for the public demo or a
|
|
345
|
+
proxy using browser/session authentication. See [UI setup](ui.md) for proxy rules.
|
|
346
|
+
|
|
347
|
+
## Decisions still open before 1.0
|
|
348
|
+
|
|
349
|
+
- Unify content-type parameter handling between actions and notifications.
|
|
350
|
+
- Decide whether wrong methods on known routes should consistently return 405.
|
|
351
|
+
- Define support for any additional HTTP verbs, parser edge cases or path aliases;
|
|
352
|
+
do not rely on accidental acceptance as a stable interface.
|
|
353
|
+
- Approve which field/value changes require an API version change, and define
|
|
354
|
+
deprecation/migration rules before removing or changing existing semantics.
|
|
355
|
+
- Define journal schema evolution separately from the page envelope and the
|
|
356
|
+
package version; bounded cursors and in-memory request IDs are not durable APIs.
|
|
357
|
+
|
|
358
|
+
This documentation deliberately records current differences instead of changing
|
|
359
|
+
behavior while inventorying the interfaces.
|
|
@@ -32,12 +32,15 @@ For installation and the command reference, see the
|
|
|
32
32
|
:caption: Serve mode
|
|
33
33
|
|
|
34
34
|
serve
|
|
35
|
+
http-api-contract
|
|
35
36
|
ui
|
|
36
37
|
compose
|
|
37
38
|
metrics
|
|
38
39
|
alerts
|
|
39
40
|
notifications
|
|
40
41
|
audit
|
|
42
|
+
journal-compatibility
|
|
43
|
+
audit-migration
|
|
41
44
|
redis-notifications
|
|
42
45
|
dwho-http-notifications
|
|
43
46
|
grafana
|
|
@@ -48,6 +51,7 @@ For installation and the command reference, see the
|
|
|
48
51
|
|
|
49
52
|
check-config
|
|
50
53
|
config-cli-contract
|
|
54
|
+
supported-environments
|
|
51
55
|
troubleshooting
|
|
52
56
|
architecture
|
|
53
57
|
roadmap
|