jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-25 02:06:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add documentation for enhanced logging endpoints (#1127)

Browse Source 
* 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>
This commit is contained in:
Stefan Agner 2022-10-21 20:14:16 +02:00 committed by GitHub
parent 3b30cea057
commit fcafabfc9e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 101 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
docs/api/supervisor/endpoints.md
View File

@ -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">