kiosko-plugin-logs 0.0.0-stage → 0.1.0
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.
- package/LICENSE +21 -0
- package/README.md +249 -2
- package/dist/index.js +1750 -0
- package/docs/last-error.png +0 -0
- package/docs/rate.png +0 -0
- package/docs/tail.png +0 -0
- package/kiosko-manifest.json +1600 -0
- package/package.json +70 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Loksly
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,250 @@
|
|
|
1
|
-
#
|
|
1
|
+
# kiosko-plugin-logs
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Live logs on your panel: the end of your logs as they are written, errors per
|
|
4
|
+
minute as a curve, and the last error, big. Errors show as they happen and
|
|
5
|
+
keep their tile a while; repeats fold into one line ("×37"); tokens,
|
|
6
|
+
passwords and e-mail addresses are masked before anything is kept or painted.
|
|
7
|
+
|
|
8
|
+
From **journald**, **log files**, **Docker** containers, the **macOS** unified
|
|
9
|
+
log, the **Windows** Event Log, **Kubernetes** pods and **Grafana Loki**.
|
|
10
|
+
|
|
11
|
+
A plugin for [Kiosko](https://github.com/kiosko-lcd/kiosko), the widget mosaic
|
|
12
|
+
for small USB LCD panels. **Optional:** Kiosko doesn't install it.
|
|
13
|
+
|
|
14
|
+

|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
In Kiosko, **Plugins → Install from npm** → `kiosko-plugin-logs`. Or from a
|
|
19
|
+
terminal:
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
npm install --prefix ~/.config/kiosko/plugins kiosko-plugin-logs
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
(macOS: `~/Library/Application Support/Kiosko/plugins`, Windows: `%APPDATA%\Kiosko\plugins`.)
|
|
26
|
+
|
|
27
|
+
Then tell it what to follow in **Settings → Data sources** (one source per
|
|
28
|
+
kind of log, below) and add a widget. Out of the box only the system's own
|
|
29
|
+
log is followed, on its own system: the journal on Linux, the unified log
|
|
30
|
+
(errors only) on macOS, the System and Application logs (warnings and worse)
|
|
31
|
+
on Windows. Files, Docker, Kubernetes and Loki do nothing until you set them
|
|
32
|
+
up.
|
|
33
|
+
|
|
34
|
+
## What it does on your machine
|
|
35
|
+
|
|
36
|
+
Be sure you want this before you turn a source on. Logs say a lot about a
|
|
37
|
+
machine and the people who use it.
|
|
38
|
+
|
|
39
|
+
- **Runs** `journalctl` (Linux), `log stream` (macOS), `powershell.exe`
|
|
40
|
+
(Windows, every 15 s) and `kubectl` (only with pods chosen), or the program
|
|
41
|
+
you name in each source's `bin`. Each is restarted when it dies, waiting
|
|
42
|
+
longer each time (1 s, 2 s, 4 s… up to a minute).
|
|
43
|
+
- **Reads** the log files you list, following their end like `tail -F`.
|
|
44
|
+
- **Talks to Docker** through its socket, only with `GET` requests (list the
|
|
45
|
+
containers, read their logs). Nothing is started, stopped or changed.
|
|
46
|
+
- **Contacts** the Loki you name, and your Kubernetes cluster through your
|
|
47
|
+
kubeconfig. Nothing else on the network.
|
|
48
|
+
|
|
49
|
+
### Permissions, honestly
|
|
50
|
+
|
|
51
|
+
- **The system journal** needs your user in the `systemd-journal` (or `adm`)
|
|
52
|
+
group. Without it `journalctl` shows only your own user's messages, which
|
|
53
|
+
is often what you want on a desktop: Kiosko never asks for more, and it
|
|
54
|
+
doesn't need root.
|
|
55
|
+
- **The Docker socket is root.** Anyone who can write to
|
|
56
|
+
`/var/run/docker.sock` can start a container that mounts `/` and do
|
|
57
|
+
anything to the machine. This plugin only reads, but giving Kiosko's user
|
|
58
|
+
the `docker` group gives that power to everything running as that user.
|
|
59
|
+
Rootless Docker (its socket is `$XDG_RUNTIME_DIR/docker.sock`, found on its
|
|
60
|
+
own) doesn't have that problem. Docker is read only once you choose
|
|
61
|
+
containers.
|
|
62
|
+
- **Windows**: the Security log needs an administrator; System and
|
|
63
|
+
Application don't.
|
|
64
|
+
- **macOS**: `log stream` works for any user; some private details are
|
|
65
|
+
redacted by macOS itself.
|
|
66
|
+
- **Kubernetes** and **Loki** see what your kubeconfig and your Loki token
|
|
67
|
+
allow.
|
|
68
|
+
|
|
69
|
+
### What is masked
|
|
70
|
+
|
|
71
|
+
Before a line is kept, shown or sent to the editor:
|
|
72
|
+
|
|
73
|
+
- passwords in URLs (`postgres://app:***@db:5432`);
|
|
74
|
+
- `Authorization: Bearer ***`, `Basic ***`, `token ***`;
|
|
75
|
+
- values of `password`, `token`, `secret`, `api_key`, `session`, `cookie` and
|
|
76
|
+
the like, in `key=value`, `key: value` and JSON;
|
|
77
|
+
- well-known token formats anywhere in a line: GitHub, GitLab, Slack, AWS,
|
|
78
|
+
Google, `sk-…` API keys, Stripe, Hugging Face, npm, JSON Web Tokens,
|
|
79
|
+
private key blocks;
|
|
80
|
+
- e-mail addresses (`***@***`).
|
|
81
|
+
|
|
82
|
+
It errs on the side of hiding, but it can't know every secret format: a
|
|
83
|
+
panel on a shelf is seen by anyone walking by, so think about which logs you
|
|
84
|
+
put on it. Lines are cut to 400 characters, and at most 300 lines and 1000
|
|
85
|
+
warnings and errors (24 h) are kept per source, in memory only.
|
|
86
|
+
|
|
87
|
+
## Sources
|
|
88
|
+
|
|
89
|
+
Edited once, in **Settings → Data sources**. A widget shows the lines of
|
|
90
|
+
every source that is set up; its `units` filter picks among them.
|
|
91
|
+
|
|
92
|
+
### systemd journal — `logs/journal` (Linux)
|
|
93
|
+
|
|
94
|
+
`journalctl --follow --output=json`, the last 200 lines first. After a
|
|
95
|
+
restart it goes on from where it was (`--after-cursor`), so nothing is shown
|
|
96
|
+
twice.
|
|
97
|
+
|
|
98
|
+
| Option | Type | Default | |
|
|
99
|
+
|---|---|---|---|
|
|
100
|
+
| `units` | filter | `[]` | Which units: `nginx.service`, `backup*`, `!cron.service`. Empty: all. |
|
|
101
|
+
| `priority` | `error` … `debug` | `info` | The least serious messages read (`--priority`). |
|
|
102
|
+
| `onlyUser` | boolean | `false` | Only your user's journal (`--user`). |
|
|
103
|
+
| `bin` | program | `""` | `journalctl` by its full path. |
|
|
104
|
+
|
|
105
|
+
### Log files — `logs/file`
|
|
106
|
+
|
|
107
|
+
Follows the end of each file like `tail -F`: the last lines first, then what
|
|
108
|
+
is appended. Rotation by renaming (logrotate) is noticed and the new file is
|
|
109
|
+
read from its start; truncation in place (`copytruncate`, `> app.log`) starts
|
|
110
|
+
again from the top; a file that isn't there yet is waited for. A file
|
|
111
|
+
growing faster than a panel can show is skipped forward. Lines are read for
|
|
112
|
+
their own timestamp (ISO, syslog) and level (`ERROR`, `[warn]`,
|
|
113
|
+
`level=error`, JSON `"level"`, glog's `E1121`).
|
|
114
|
+
|
|
115
|
+
| Option | Type | Default | |
|
|
116
|
+
|---|---|---|---|
|
|
117
|
+
| `paths` | list of paths | `[]` | The files, by full path (`~` and `$VARS` work). Empty: none is read. |
|
|
118
|
+
|
|
119
|
+
### Docker containers — `logs/docker`
|
|
120
|
+
|
|
121
|
+
Through Docker's API on its socket: the running containers your filter
|
|
122
|
+
picks, followed with timestamps, frames read whether the container has a
|
|
123
|
+
TTY or not. New and restarted containers are picked up within 15 s, from
|
|
124
|
+
where they were left.
|
|
125
|
+
|
|
126
|
+
| Option | Type | Default | |
|
|
127
|
+
|---|---|---|---|
|
|
128
|
+
| `containers` | filter | `[]` | By name or Compose service: `web`, `db-*`, `!*-test`; `*` for all. **Empty: Docker is not read.** |
|
|
129
|
+
| `socket` | path | `""` | Empty: `DOCKER_HOST`, else `$XDG_RUNTIME_DIR/docker.sock` (rootless), `~/.docker/run/docker.sock` (Docker Desktop), `/var/run/docker.sock`; on Windows `\\.\pipe\docker_engine`. |
|
|
130
|
+
|
|
131
|
+
### macOS unified log — `logs/macos`
|
|
132
|
+
|
|
133
|
+
`log stream --style ndjson`. The whole log is thousands of lines a second,
|
|
134
|
+
so by default only errors and faults.
|
|
135
|
+
|
|
136
|
+
| Option | Type | Default | |
|
|
137
|
+
|---|---|---|---|
|
|
138
|
+
| `predicate` | text | `messageType == error OR messageType == fault` | As `log stream --predicate` takes it. Empty: everything. |
|
|
139
|
+
| `level` | `default` \| `info` \| `debug` | `default` | `--level`. |
|
|
140
|
+
| `bin` | program | `""` | `/usr/bin/log`. |
|
|
141
|
+
|
|
142
|
+
### Windows Event Log — `logs/windows`
|
|
143
|
+
|
|
144
|
+
`Get-WinEvent` through PowerShell every 15 seconds (Windows has no `-f`),
|
|
145
|
+
new events only.
|
|
146
|
+
|
|
147
|
+
| Option | Type | Default | |
|
|
148
|
+
|---|---|---|---|
|
|
149
|
+
| `logs` | list | `["System", "Application"]` | Event log names. |
|
|
150
|
+
| `priority` | `error` \| `warning` \| `info` | `warning` | The least serious events read. |
|
|
151
|
+
| `bin` | program | `""` | `powershell.exe`. |
|
|
152
|
+
|
|
153
|
+
### Kubernetes pods — `logs/kubernetes`
|
|
154
|
+
|
|
155
|
+
`kubectl logs --follow --timestamps --prefix --all-containers`, with your
|
|
156
|
+
kubeconfig.
|
|
157
|
+
|
|
158
|
+
| Option | Type | Default | |
|
|
159
|
+
|---|---|---|---|
|
|
160
|
+
| `selector` | text | `""` | A label selector (`app=shop`) or a resource (`deployment/shop`). **Empty: kubectl is not run.** |
|
|
161
|
+
| `namespace` | text | `""` | |
|
|
162
|
+
| `context` | text | `""` | The kubeconfig context; empty, the current one. |
|
|
163
|
+
| `bin` | program | `""` | `kubectl`. |
|
|
164
|
+
|
|
165
|
+
### Grafana Loki — `logs/loki`
|
|
166
|
+
|
|
167
|
+
Loki's tail API (`/loki/api/v1/tail`, a WebSocket) for a LogQL query.
|
|
168
|
+
|
|
169
|
+
| Option | Type | Default | |
|
|
170
|
+
|---|---|---|---|
|
|
171
|
+
| `url` | URL | `""` | `http://loki.example.lan:3100`. `user:password@` in it becomes Basic auth. **Empty: Loki is not contacted.** |
|
|
172
|
+
| `query` | LogQL | `""` | `{job="nginx"} \|= "error"`. |
|
|
173
|
+
| `token` | secret | `""` | Sent as `Authorization: Bearer`. |
|
|
174
|
+
| `orgId` | text | `""` | `X-Scope-OrgID`, for a multi-tenant Loki. |
|
|
175
|
+
|
|
176
|
+
## Widgets
|
|
177
|
+
|
|
178
|
+
All three take the same filters:
|
|
179
|
+
|
|
180
|
+
- `units`: which logs, by name (`nginx.service`, `web`, `app.log`) or kind
|
|
181
|
+
(`journal/*`, `docker/*`, `file/*`, `macos/*`, `windows/*`,
|
|
182
|
+
`kubernetes/*`, `loki/*`), with `!` to leave one out.
|
|
183
|
+
- `messages`: only lines with these words (`timeout`, `refused`), `!` to
|
|
184
|
+
leave out (`!healthcheck`), globs (`GET *`) and regular expressions
|
|
185
|
+
between slashes (`/5\d\d/`, case-insensitive unless it has capitals).
|
|
186
|
+
- `holdMs`: how long an error keeps the tile (urgent, while the instance's
|
|
187
|
+
**Keep the tile while urgent** is on); 0, never. Default 2 min.
|
|
188
|
+
|
|
189
|
+
They are **idle** when no warning or error has come for 10 minutes, so a
|
|
190
|
+
screen with *sleep when idle* goes dark while the logs are quiet.
|
|
191
|
+
|
|
192
|
+
### Live log — `logs/tail`
|
|
193
|
+
|
|
194
|
+
The end of the logs, newest first, in monospace: how long ago, where from,
|
|
195
|
+
"×37" for repeats, errors in red and warnings in amber. "+N more" counts the
|
|
196
|
+
older lines left out.
|
|
197
|
+
|
|
198
|
+
| Option | Type | Default | |
|
|
199
|
+
|---|---|---|---|
|
|
200
|
+
| `level` | `error` … `debug` | `info` | The least serious lines shown. |
|
|
201
|
+
| `units`, `messages` | filter | `[]` | See above. |
|
|
202
|
+
| `showUnits` | boolean | `true` | Where each line comes from. |
|
|
203
|
+
| `showTime` | boolean | `true` | How long ago. |
|
|
204
|
+
| `rows`, `layout` | list options | `0`, `auto` | As in every Kiosko list; `detailed` puts the unit and age under each line. |
|
|
205
|
+
| `holdMs` | duration | 2 min | |
|
|
206
|
+
|
|
207
|
+
### Errors per minute — `logs/rate`
|
|
208
|
+
|
|
209
|
+

|
|
210
|
+
|
|
211
|
+
How many errors in the span, and a curve of them minute by minute (warnings
|
|
212
|
+
too, in amber, with `includeWarnings`).
|
|
213
|
+
|
|
214
|
+
| Option | Type | Default | |
|
|
215
|
+
|---|---|---|---|
|
|
216
|
+
| `units`, `messages` | filter | `[]` | |
|
|
217
|
+
| `includeWarnings` | boolean | `false` | |
|
|
218
|
+
| `historyMs` | duration | 1 h | 10 min to 24 h. |
|
|
219
|
+
| `holdMs` | duration | 2 min | |
|
|
220
|
+
|
|
221
|
+
### Last error — `logs/last-error`
|
|
222
|
+
|
|
223
|
+

|
|
224
|
+
|
|
225
|
+
The last error, as big as it fits, with where, when and how many times. Red
|
|
226
|
+
while fresh (`holdMs`), plain afterwards.
|
|
227
|
+
|
|
228
|
+
| Option | Type | Default | |
|
|
229
|
+
|---|---|---|---|
|
|
230
|
+
| `units`, `messages` | filter | `[]` | |
|
|
231
|
+
| `includeWarnings` | boolean | `false` | |
|
|
232
|
+
| `holdMs` | duration | 2 min | |
|
|
233
|
+
|
|
234
|
+
## Testing
|
|
235
|
+
|
|
236
|
+
`npm test`: the parsers (journald, Docker frames, macOS, Windows, kubectl,
|
|
237
|
+
Loki, plain lines), masking, folding and the buffer, the once-a-second
|
|
238
|
+
emitter, the restarts with backoff, file following with real rotation and
|
|
239
|
+
truncation, journald through a stand-in `journalctl`, Docker through a
|
|
240
|
+
stand-in API on a Unix socket, and the widgets painted with
|
|
241
|
+
`@kiosko/sdk/testing`. Every log line in the tests, the demo and the
|
|
242
|
+
pictures is invented.
|
|
243
|
+
|
|
244
|
+
## Not yet
|
|
245
|
+
|
|
246
|
+
- Receiving **syslog over UDP** from the network (a router, a NAS).
|
|
247
|
+
|
|
248
|
+
## Licence
|
|
249
|
+
|
|
250
|
+
MIT.
|