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.
Files changed (152) hide show
  1. {monit_docker-0.0.77/monit_docker.egg-info → monit_docker-0.0.78}/PKG-INFO +19 -9
  2. {monit_docker-0.0.77 → monit_docker-0.0.78}/README.md +14 -2
  3. monit_docker-0.0.78/RELEASE +1 -0
  4. monit_docker-0.0.78/VERSION +1 -0
  5. monit_docker-0.0.78/docs/audit-migration.md +118 -0
  6. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/audit.md +9 -0
  7. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/config-cli-contract.md +1 -0
  8. monit_docker-0.0.78/docs/http-api-contract.md +359 -0
  9. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/index.rst +4 -0
  10. monit_docker-0.0.78/docs/journal-compatibility.md +147 -0
  11. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/metrics.md +15 -0
  12. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/roadmap.md +19 -3
  13. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/serve.md +9 -4
  14. monit_docker-0.0.78/docs/supported-environments.md +97 -0
  15. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/__init__.py +1 -1
  16. monit_docker-0.0.78/monit_docker/audit_migrate.py +185 -0
  17. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/cli.py +40 -1
  18. {monit_docker-0.0.77 → monit_docker-0.0.78/monit_docker.egg-info}/PKG-INFO +19 -9
  19. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker.egg-info/SOURCES.txt +8 -0
  20. {monit_docker-0.0.77 → monit_docker-0.0.78}/setup.yml +6 -13
  21. monit_docker-0.0.78/tests/test_api_contract.py +381 -0
  22. monit_docker-0.0.78/tests/test_audit_migrate.py +204 -0
  23. monit_docker-0.0.78/tests/test_journal_compatibility.py +139 -0
  24. monit_docker-0.0.77/RELEASE +0 -1
  25. monit_docker-0.0.77/VERSION +0 -1
  26. {monit_docker-0.0.77 → monit_docker-0.0.78}/LICENSE +0 -0
  27. {monit_docker-0.0.77 → monit_docker-0.0.78}/MANIFEST.in +0 -0
  28. {monit_docker-0.0.77 → monit_docker-0.0.78}/bin/monit-docker +0 -0
  29. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/access-checks.md +0 -0
  30. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/alerts.md +0 -0
  31. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/architecture.md +0 -0
  32. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/check-config.md +0 -0
  33. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/compose.md +0 -0
  34. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/cron.md +0 -0
  35. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/dockerhub.md +0 -0
  36. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/dwho-http-notifications.md +0 -0
  37. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/filesystems.md +0 -0
  38. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/grafana.md +0 -0
  39. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/healthchecks.md +0 -0
  40. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/images/grafana-cpu.png +0 -0
  41. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/images/grafana-network.png +0 -0
  42. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/images/grafana-overview.png +0 -0
  43. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/maintenance.md +0 -0
  44. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/notifications.md +0 -0
  45. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/pypi.md +0 -0
  46. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/redis-notifications.md +0 -0
  47. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/restart-limit.md +0 -0
  48. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/runtime-checks.md +0 -0
  49. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/scenarios.md +0 -0
  50. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/simple.md +0 -0
  51. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/trigger-delay.md +0 -0
  52. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/troubleshooting.md +0 -0
  53. {monit_docker-0.0.77 → monit_docker-0.0.78}/docs/ui.md +0 -0
  54. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/grafana/monit-docker.json +0 -0
  55. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/alertmanager.email-slack.yml +0 -0
  56. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/alertmanager.email.yml +0 -0
  57. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/alertmanager.redis.yml +0 -0
  58. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/alertmanager.slack.yml +0 -0
  59. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/alerts.runtime.test.yml +0 -0
  60. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/alerts.runtime.yml +0 -0
  61. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/alerts.test.yml +0 -0
  62. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/alerts.yml +0 -0
  63. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/compose.audit.yaml +0 -0
  64. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/compose.notifications.yaml +0 -0
  65. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/compose.redis.yaml +0 -0
  66. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/compose.yaml +0 -0
  67. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/dwho-http/http.json +0 -0
  68. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/dwho-http/http.yml +0 -0
  69. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/dwho-http/payload.json +0 -0
  70. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/dwho-http/send.py +0 -0
  71. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/grafana/dashboards.yml +0 -0
  72. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/grafana/datasources.yml +0 -0
  73. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/prometheus-notifications.yml +0 -0
  74. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/prometheus.yml +0 -0
  75. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/redis-webhook/Dockerfile +0 -0
  76. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/redis-webhook/bridge.py +0 -0
  77. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/redis-webhook/requirements.txt +0 -0
  78. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/monitoring/start.sh +0 -0
  79. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/scenarios.yml +0 -0
  80. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/ui/compose.actions.yaml +0 -0
  81. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/ui/compose.journal.yaml +0 -0
  82. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/ui/compose.yaml +0 -0
  83. {monit_docker-0.0.77 → monit_docker-0.0.78}/examples/ui/prepare.py +0 -0
  84. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/__main__.py +0 -0
  85. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/__init__.py +0 -0
  86. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/access.py +0 -0
  87. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/configuration.py +0 -0
  88. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/docker.py +0 -0
  89. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/events.py +0 -0
  90. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/filesystems.py +0 -0
  91. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/http.py +0 -0
  92. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/http_routes.py +0 -0
  93. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/rules.py +0 -0
  94. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/scenarios.py +0 -0
  95. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/selection.py +0 -0
  96. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/state.py +0 -0
  97. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/syntax.py +0 -0
  98. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/adapters/validation.py +0 -0
  99. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/audit.py +0 -0
  100. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/audit_forward.py +0 -0
  101. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/audit_query.py +0 -0
  102. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/core/__init__.py +0 -0
  103. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/core/engine.py +0 -0
  104. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/core/manual.py +0 -0
  105. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/core/metrics.py +0 -0
  106. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/core/policy.py +0 -0
  107. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/core/rules.py +0 -0
  108. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/domain/__init__.py +0 -0
  109. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/domain/errors.py +0 -0
  110. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/domain/filesystems.py +0 -0
  111. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/domain/maintenance.py +0 -0
  112. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/domain/models.py +0 -0
  113. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/domain/rules.py +0 -0
  114. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/domain/runtime.py +0 -0
  115. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/manual_actions.py +0 -0
  116. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/notification_audit.py +0 -0
  117. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/outputs/__init__.py +0 -0
  118. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/outputs/formatting.py +0 -0
  119. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/outputs/prometheus.py +0 -0
  120. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker/service.py +0 -0
  121. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker.egg-info/dependency_links.txt +0 -0
  122. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker.egg-info/requires.txt +0 -0
  123. {monit_docker-0.0.77 → monit_docker-0.0.78}/monit_docker.egg-info/top_level.txt +0 -0
  124. {monit_docker-0.0.77 → monit_docker-0.0.78}/pyproject.toml +0 -0
  125. {monit_docker-0.0.77 → monit_docker-0.0.78}/requirements.txt +0 -0
  126. {monit_docker-0.0.77 → monit_docker-0.0.78}/setup.cfg +0 -0
  127. {monit_docker-0.0.77 → monit_docker-0.0.78}/setup.py +0 -0
  128. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_access.py +0 -0
  129. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_access_docker.py +0 -0
  130. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_adapters.py +0 -0
  131. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_audit.py +0 -0
  132. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_audit_query.py +0 -0
  133. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_check_config.py +0 -0
  134. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_cli_contract.py +0 -0
  135. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_core.py +0 -0
  136. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_cron.py +0 -0
  137. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_docker_integration.py +0 -0
  138. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_engine.py +0 -0
  139. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_filesystem_mode.py +0 -0
  140. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_filesystems.py +0 -0
  141. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_health.py +0 -0
  142. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_httpdis_transport.py +0 -0
  143. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_maintenance.py +0 -0
  144. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_manual_actions.py +0 -0
  145. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_monit_docker.py +0 -0
  146. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_packaging.py +0 -0
  147. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_restart_limit.py +0 -0
  148. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_runtime_checks.py +0 -0
  149. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_runtime_docker.py +0 -0
  150. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_scenarios.py +0 -0
  151. {monit_docker-0.0.77 → monit_docker-0.0.78}/tests/test_service.py +0 -0
  152. {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.77
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.5
17
- Classifier: Programming Language :: Python :: 3.6
18
- Classifier: Programming Language :: Python :: 3.7
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: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*
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 examples below use Python 3 (CI tests Python 3.10 and 3.12). You need a Docker
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 examples below use Python 3 (CI tests Python 3.10 and 3.12). You need a Docker
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