Skip to main content

Watchtower: Python CloudWatch Logging

Watchtower is a log handler for Amazon Web Services CloudWatch Logs.

CloudWatch Logs is a log management service built into AWS. It is conceptually similar to services like Splunk and Loggly, but is more lightweight, cheaper, and tightly integrated with the rest of AWS.

Watchtower, in turn, is a lightweight adapter between the Python logging system and CloudWatch Logs. It uses the boto3 AWS SDK, and lets you plug your application logging directly into CloudWatch without the need to install a system-wide log collector like awscli-cwlogs and round-trip your logs through the instance’s syslog. It aggregates logs into batches to avoid sending an API request per each log message, while guaranteeing a delivery deadline (60 seconds by default).

Installation

pip install watchtower

Synopsis

Install awscli and set your AWS credentials (run aws configure).

import watchtower, logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
logger.addHandler(watchtower.CloudWatchLogHandler())
logger.info("Hi")
logger.info(dict(foo="bar", details={}))

After running the example, you can see the log output in your AWS console.

Example: Flask logging with Watchtower

import watchtower, flask, logging

logging.basicConfig(level=logging.INFO)
app = flask.Flask("loggable")
handler = watchtower.CloudWatchLogHandler()
app.logger.addHandler(handler)
logging.getLogger("werkzeug").addHandler(handler)

@app.route('/')
def hello_world():
    return 'Hello World!'

if __name__ == '__main__':
    app.run()

(See also http://flask.pocoo.org/docs/errorhandling/.)

Examples: Querying CloudWatch logs

This section is not specific to Watchtower. It demonstrates the use of awscli and jq to read and search CloudWatch logs on the command line.

For the Flask example above, you can retrieve your application logs with the following two commands:

aws logs get-log-events --log-group-name watchtower --log-stream-name loggable | jq '.events[].message'
aws logs get-log-events --log-group-name watchtower --log-stream-name werkzeug | jq '.events[].message'

CloudWatch Logs supports alerting and dashboards based on metric filters, which are pattern rules that extract information from your logs and feed it to alarms and dashboard graphs. The following example shows logging structured JSON data using Watchtower, setting up a metric filter to extract data from the log stream, a dashboard to visualize it, and an alarm that sends an email:

TODO

Authors

  • Andrey Kislyuk

Bugs

Please report bugs, issues, feature requests, etc. on GitHub.

License

Licensed under the terms of the Apache License, Version 2.0.

https://travis-ci.org/kislyuk/watchtower.svg https://codecov.io/github/kislyuk/watchtower/coverage.svg?branch=master https://img.shields.io/pypi/v/watchtower.svg https://img.shields.io/pypi/l/watchtower.svg https://readthedocs.org/projects/watchtower/badge/?version=latest

Metadata

Release files for watchtower 0.3.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for watchtower 0.3.5
File Size Uploaded Provenance Actions
watchtower-0.3.5.tar.gz 6.6 kB Without provenance Details for watchtower-0.3.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for watchtower 0.3.5
File Interpreter ABI Platform Actions
watchtower-0.3.5-py2.py3-none-any.whl Python 2, Python 3 none any Details for watchtower-0.3.5-py2.py3-none-any.whl

Total release size: 15.2 kB

Release files / watchtower-0.3.5.tar.gz

Download URL watchtower-0.3.5.tar.gz
Size 6.6 kB
Tags Source
SHA-256 checksum
How to use checksums
2f1bc83c098cba5f71d10b46e9c9b0942028662337babb6b32e4fb057c544aeb
BLAKE2b-256 checksum
How to use checksums
9590557b435d1c9917f55c1b2b706e13d001285af081371e5951d582d54aa3fc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Release files / watchtower-0.3.5-py2.py3-none-any.whl

Download URL watchtower-0.3.5-py2.py3-none-any.whl
Size 8.6 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
a367b50707a97578e8657f47b933c4bfc9a493dc29bd804284c45450300fb50f
BLAKE2b-256 checksum
How to use checksums
dcc8e33840a0e9714bc0d98a81e7ff013a70c20616f576db8f6217354d4dd280
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Security for watchtower 0.3.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.5 This release

2 release files No provenance

0.1.1

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page