From fcafabfc9e187923f84ebe8eb82243541741a213 Mon Sep 17 00:00:00 2001
From: Stefan Agner <stefan@agner.ch>
Date: Fri, 21 Oct 2022 20:14:16 +0200
Subject: [PATCH] Add documentation for enhanced logging endpoints (#1127)

* Add documentation for enhanced logging endpoints

* Document all log endpoints and options

* Update with latest endpoints

* Missed a closing tag

* Add other /follow endpoints

* Note link to /host/logs for range info

* Only modify /host/logs endpoints

Co-authored-by: Mike Degatano <michael.degatano@gmail.com>
---
 docs/api/supervisor/endpoints.md | 102 ++++++++++++++++++++++++++++++-
 1 file changed, 101 insertions(+), 1 deletion(-)

diff --git a/docs/api/supervisor/endpoints.md b/docs/api/supervisor/endpoints.md
index 87859750..403e9956 100644
--- a/docs/api/supervisor/endpoints.md
+++ b/docs/api/supervisor/endpoints.md
@@ -1423,7 +1423,107 @@ Return information about the host.
 </ApiEndpoint>
 
 <ApiEndpoint path="/host/logs" method="get">
-Get the dmesg logs from the host.
+
+Get systemd Journal logs from the host. Returns log entries in plain text, one
+log record per line.
+
+**HTTP Request Headers**
+
+| Header   | optional | description                                    |
+| -------- | -------- | ---------------------------------------------- |
+| Accept   | true     | Type of data (currently only text/plain)       |
+| Range    | true     | Range of log entries. The format is `entries=cursor[[:num_skip]:num_entries]` |
+
+:::tip
+To get the last log entries the Range request header supports negative values
+as `num_skip`. E.g. `Range: entries=:-9:` returns the last 10 entries. Or
+`Range: entries=:-200:100` to see 100 entries starting from the one 200 ago.
+:::
+
+API returns the last 100 lines by default. Provide a value for `Range` to see
+logs further in the past.
+
+</ApiEndpoint>
+
+<ApiEndpoint path="/host/logs/follow" method="get">
+
+Identical to `/host/logs` except it continuously returns new log entries.
+
+</ApiEndpoint>
+
+<ApiEndpoint path="/host/logs/identifiers">
+
+Returns a list of syslog identifiers from the systemd journal that you can use
+with `/host/logs/identifiers/<identifier>` and `/host/logs/boots/<bootid>/identifiers/<identifier>`.
+
+</ApiEndpoint>
+
+<ApiEndpoint path="/host/logs/identifiers/<identifier>" method="get">
+
+Get systemd Journal logs from the host for entries related to a specific log
+identifier. Some examples of useful identifiers here include
+
+- `audit` - If developing an apparmor profile shows you permission issues
+- `NetworkManager` - Shows NetworkManager logs when having network issues
+- `bluetoothd` - Shows bluetoothd logs when having bluetooth issues
+
+A call to `GET /host/logs/identifiers` will show the complete list of possible
+values for `identifier`.
+
+Otherwise it provides the same functionality as `/host/logs`.
+
+</ApiEndpoint>
+
+<ApiEndpoint path="/host/logs/identifiers/<identifier>/follow" method="get">
+
+Identical to `/host/logs/identifiers/<identifier>` except it continuously returns
+new log entries.
+
+</ApiEndpoint>
+
+<ApiEndpoint path="/host/logs/boots">
+
+Returns a dictionary of boot IDs for this system that you can use with
+`/host/logs/boots/<bootid>` and `/host/logs/boots/<bootid>/identifiers/<identifier>`.
+
+The key for each item in the dictionary is the boot offset. 0 is the current boot,
+a negative number denotes how many boots ago that boot was.
+
+</ApiEndpoint>
+
+<ApiEndpoint path="/host/logs/boots/<bootid>" method="get">
+
+Get systemd Journal logs from the host for entries related to a specific boot.
+Call `GET /host/info/boots` to see the boot IDs. Alternatively you can provide a
+boot offset:
+
+- 0 - The current boot
+- Negative number - Count backwards from current boot (-1 is previous boot)
+- Positive number - Count forward from last known boot (1 is last known boot)
+
+Otherwise it provides the same functionality as `/host/logs`.
+
+</ApiEndpoint>
+
+<ApiEndpoint path="/host/logs/boots/<bootid>/follow" method="get">
+
+Identical to `/host/logs/boots/<bootid>` except it continuously returns
+new log entries.
+
+</ApiEndpoint>
+
+<ApiEndpoint path="/host/logs/boots/<bootid>/identifiers/<identifier>" method="get">
+
+Get systemd Journal logs entries for a specific log identifier and boot.
+A combination of `/host/logs/boots/<bootid>` and `/host/logs/identifiers/<identifier>`.
+
+</ApiEndpoint>
+
+<ApiEndpoint path="/host/logs/boot/<bootid>/<identifier>/entries/follow" method="get">
+
+Identical to `/host/logs/boots/<bootid>/identifiers/<identifier>` except it continuously
+returns new log entries.
+
 </ApiEndpoint>
 
 <ApiEndpoint path="/host/options" method="post">