Skip to main content

Lightweight HTTP log monitoring and alerting tool

Project description


build status codecov code style license

Lightweight HTTP log monitoring and alerting console tool written in Python.

Note: only W3C-formatted logs are supported for now. See here for an example W3C-formatted log file.


  • Live tail of log files.
  • Stats reporting in the console: top hit sections, traffic, throughput, etc.
  • Live alerting and recovery detection with customizable thresholds and delays.
  • Friendly command line interface.
  • Detailed and machine-readable JSON-formatted output.
  • Asynchronous architecture with low resources footprint.
  • Optional Docker-based execution.

Example command:

$ watchl -f access.log --report-every=2 --alert-tick=2 --traffic-up=1 --traffic-down=1

Output (JSON prettification by piping into jq):

  "levelname": "INFO",
  "message": "process started",
  "timestamp": "2019-07-30T21:02:30.652107",
  "pid": 2417
  "levelname": "INFO",
  "message": "watching logs",
  "timestamp": "2019-07-30T21:02:30.653034",
  "path": "access.log"
  "levelname": "INFO",
  "message": "activity in the past 2.0 seconds",
  "timestamp": "2019-07-30T21:02:32.708673",
  "sections.count": {
    "unit": "hits",
    "value": [
        "key": "/presentations",
        "count": 68
        "key": "/images",
        "count": 13
        "key": "/blog",
        "count": 9
  "": {
    "unit": "req",
    "value": 135
  "requests.average": {
    "unit": "req/s",
    "value": 67.5
  "transfer.average": {
    "unit": "bytes/s",
    "value": 3064559
  "transfer.mean": {
    "unit": "bytes/req",
    "value": 45400.874074074076
  "levelname": "WARNING",
  "message": "alert status changed",
  "timestamp": "2019-07-30T21:02:34.773988",
  "status": "active",
  "previous_status": "activating",
  "value": 89.5,
  "reason": "stayed above threshold for longer than up delay",
  "metric": "requests.average",
  "threshold": 10,
  "up": "0:00:01",
  "down": "0:00:01"


  • If you have Python 3.6+ installed, you can install watchl from PyPI:
pip install watchl

or locally by cloning the repository and running:

pip install .
  • If you have Docker installed, you can build the image by cloning the repository and running:
docker build -t watchl .


General notes

watchl exposes a command line executable named watchl.

When run without any other options, watchl will read logs from /tmp/access.log (this is configurable — see CLI reference for options) and consume them as they are written to the file.

Known limitation: watchl does not handle log rotation yet. If the log file is renamed, truncated or moved, watchl won't be able to read new logs anymore, and will need to be restarted. See #9.

If using Docker, and assuming you have a log file somewhere on your machine, you can run a watchl container using:

docker run -it --rm -v /host/path/to/access.log:/tmp/access.log watchl <options>

By default, watchl works on relatively long time scales (minutes). For quicker feedback (e.g. when trying watchl for the first time), you can try the following options:

watchl --report-every=5 --alert-tick=1 --traffic-up=1 --traffic-down=1

CLI reference

Usage: watchl [OPTIONS]

  -f PATH                         Path to an actively written-to log file.
                                  [default: /tmp/access.log]
  --report-every FLOAT            Number of seconds between stats reports.
                                  [default: 10]
  --sections-top INTEGER          Number of most hit website sections to
                                  display in the report.  [default: 3]
  --traffic-threshold FLOAT       [default: 10]
  --traffic-up FLOAT              Number of seconds to trigger an alert after
                                  traffic exceeded the threshold.  [default:
  --traffic-down FLOAT            Number of seconds to stop an alert after
                                  traffic dropped below the threshold.
                                  [default: 120]
  --alert-tick FLOAT              Number of seconds between evaluation of
                                  stats for alerting purposes.  [default: 10]
  --tick FLOAT                    Number of seconds between system event
                                  checks. Note: lower values increase CPU
                                  usage.  [default: 0.5]
  --log-level [debug|info|warning|critical|error]
                                  Level for internal log messages  [default:
  --limit-max-log-lines INTEGER   Limit the number of log lines to ingest
                                  before terminating the process.
  --help                          Show this message and exit.


See Contributing guidelines.



Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

watchl-0.2.tar.gz (12.2 kB view hashes)

Uploaded source

Built Distribution

watchl-0.2-py3-none-any.whl (13.6 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page