Skip to content
ImranR98Public

About

Simple log monitoring service that uses ntfy for alerts.

Topics

Resources

Stars

13 stars

Watchers

1 watching

Forks

Repository files navigation

Logtfy

Simple log monitoring service that uses ntfy for alerts.

Details

  • 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_logins module is used to monitor SSH logs and send an alert when someone logs in via SSH.
    • Modules are stored in the modules directory 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).
  • 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.

Usage

  1. Create a copy of config.default.json and name it config.json.
  2. Modify config.json to suit your needs.
    • This file defines your ntfy.sh servers (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 moduleInstances array 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.
  3. Optionally, create a file named onExit.sh and customize it - this file runs when the monitoring script exits for any reason.
  4. If you've enabled a module that grabs logs from a Kubernetes service, you'll need to run k8s/prep.sh.
  5. Launch the service with run.sh
    • Alternatively, you can use the Dockerfile to 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.

Container image

Images are built and published by GitHub Actions:

  • ghcr.io/imranr98/logtfy:latest
  • ghcr.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:latest

The previous Docker Hub imranrdev/logtfy repository is deprecated and no longer updated.

Development

  • 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.

Modules

generic_logs

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 to Logtfy 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.

About

Simple log monitoring service that uses ntfy for alerts.

Topics

Resources

Stars

13 stars

Watchers

1 watching

Forks

Contributors

Languages