Simple log monitoring service that uses ntfy for alerts.
- Logs from a specified source are continuously monitored, parsed, and used to trigger alerts that are posted to a ntfy topic.
- This is done through packages called modules - each module represents a specific source of logs.
- For example, the
ssh_loginsmodule is used to monitor SSH logs and send an alert when someone logs in via SSH. - Modules are stored in the
modulesdirectory and each module must contain these 2 files:logger.sh: Defines the log message source (continuously outputs log messages).parser.sh: Parses an individual log and decides whether it should trigger a ntfy alert (if so, this script print a specifically formatted output containing the final alert data).
- For example, the
- Alerts can be sent to a user-defined ntfy server/topic, with the option to fallback to a second server/topic in case of failure.
- Create a copy of
config.default.jsonand name itconfig.json. - Modify
config.jsonto suit your needs.- This file defines your
ntfy.shservers (server URL, credentials, and an optional prefix to append to all topic names).- You can define as many servers as you want, but only 1 to 2 are used (the main server, with an optional fallback).
- This file also defines changes to the default settings per module.
- This includes specifying a different ntfy server (and fallback) to use, customizing the topic name, disabling modules, and adding additional data to use for log collection and parsing.
- A module entry can contain a
moduleInstancesarray to run the same module multiple times with different settings (each instance gets its own logger/parser args, topic, and enable flag).
- Other details not mentioned - most property names are self-explanatory.
- This file defines your
- Optionally, create a file named
onExit.shand customize it - this file runs when the monitoring script exits for any reason. - If you've enabled a module that grabs logs from a Kubernetes service, you'll need to run
k8s/prep.sh. - Launch the service with
run.sh- Alternatively, you can use the
Dockerfileto build and run a Docker image. - You can also set it up to run as a systemd service using the example service config file
logtfy.service.example.
- Alternatively, you can use the
Images are built and published by GitHub Actions:
ghcr.io/imranr98/logtfy:latestghcr.io/imranr98/logtfy:sha-<commit>
docker pull ghcr.io/imranr98/logtfy:latest
docker run --rm -v ./config.json:/logtfy/config.json ghcr.io/imranr98/logtfy:latestThe previous Docker Hub imranrdev/logtfy repository is deprecated and no longer updated.
- Run the test suite:
bash tests/run-tests.sh - Lint shell scripts:
shellcheck --severity=warning $(find . -name '*.sh' -not -path './.git/*') - Validate the Renovate config:
npx --yes -p renovate renovate-config-validator --strict renovate.json
The tests use fake Docker/journalctl/ntfy endpoints and do not need a Docker
socket or a live notification server. Bash line coverage is not measured (there
is no portable line-coverage tool for this spawned-process/temp-copy suite);
instead, a coverage-manifest test requires every module to have both scripts and
be referenced by tests, and the image smoke re-runs the config/parser tests
inside the production image. A separate smoke script builds and runs the
production image: bash tests/smoke-image.sh ghcr.io/imranr98/logtfy:latest.
Monitors either a Docker container or a Kubernetes service and alerts when a log line matches a user-provided regex.
loggerArg- space-separated, where the first word picks the source:<container> [stderr2stdout|printstderr]- streams Docker logs (default stderr mode: suppress stderr).k8s <service> [namespace]- streams Kubernetes pod logs (default namespace:default).
parserArg- a JSON string with the following fields:regex- regex (extended) to match log lines against; an empty regex matches every line.title- notification title (optional, defaults toLogtfy Alert).message- text to prepend to the matched log line in the notification (optional).
- If you need to monitor more than one source, configure multiple entries under
moduleInstances.