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 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
- # Temporary Holding Version
1
+ # kiosko-plugin-logs
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+ ![Live log](docs/tail.png)
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
+ ![Errors per minute](docs/rate.png)
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
+ ![Last error](docs/last-error.png)
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.