From e889528b14d7c883e3edd0bf82b9936929e521e2 Mon Sep 17 00:00:00 2001
From: "Alexander A. Klimov" <alexander.klimov@icinga.com>
Date: Wed, 8 May 2024 17:40:05 +0200
Subject: [PATCH] Document how to enable/disable Debug Output on the fly

This is a good alternative to `icinga2 feature enable debuglog`:

* Object creation/deletion via API happens immediately and requires no restart
* Hence, the debug log is enabled exactly as long as desired

Co-authored-by: alvar <8402811+oxzi@users.noreply.github.com>
---
 doc/15-troubleshooting.md | 58 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/doc/15-troubleshooting.md b/doc/15-troubleshooting.md
index 4cc733854..fcf59d505 100644
--- a/doc/15-troubleshooting.md
+++ b/doc/15-troubleshooting.md
@@ -176,6 +176,64 @@ C:\> cd C:\ProgramData\icinga2\var\log\icinga2
 C:\ProgramData\icinga2\var\log\icinga2> Get-Content .\debug.log -tail 10 -wait
 ```
 
+### Enable/Disable Debug Output on the fly <a id="troubleshooting-enable-disable-debug-output-api"></a>
+
+The `debuglog` feature can also be created and deleted at runtime without having to restart Icinga 2.
+Technically, this is possible because this feature is a [FileLogger](09-object-types.md#objecttype-filelogger)
+that can be managed through the [API](12-icinga2-api.md#icinga2-api-config-objects).
+
+This is a good alternative to `icinga2 feature enable debuglog` as object
+creation/deletion via API happens immediately and requires no restart.
+
+The above matters in setups large enough for the reload to take a while.
+Especially these produce a lot of debug log output until disabled again.
+
+!!! info
+
+    In case of [an HA zone](06-distributed-monitoring.md#distributed-monitoring-scenarios-ha-master-agents),
+    the following API examples toggle the feature on both nodes.
+
+#### Enable Debug Output on the fly <a id="troubleshooting-enable-debug-output-api"></a>
+
+```bash
+curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
+ -X PUT 'https://localhost:5665/v1/objects/fileloggers/on-the-fly-debug-file' \
+ -d '{ "attrs": { "severity": "debug", "path": "/var/log/icinga2/on-the-fly-debug.log" }, "pretty": true }'
+```
+
+```json
+{
+    "results": [
+        {
+            "code": 200.0,
+            "status": "Object was created."
+        }
+    ]
+}
+```
+
+#### Disable Debug Output on the fly <a id="troubleshooting-disable-debug-output-api"></a>
+
+This works only for debug loggers enabled on the fly as above!
+
+```bash
+curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
+ -X DELETE 'https://localhost:5665/v1/objects/fileloggers/on-the-fly-debug-file?pretty=1'
+```
+
+```json
+{
+    "results": [
+        {
+            "code": 200.0,
+            "name": "on-the-fly-debug-file",
+            "status": "Object was deleted.",
+            "type": "FileLogger"
+        }
+    ]
+}
+```
+
 ## Icinga starts/restarts/reloads very slowly
 
 ### Try swapping out the allocator