# AWS Cloudwatch Lightweight Handler
This small log handler is designed to send events to AWS Cloudwatch. It is useful when operating infrastructure outside of the AWS, when AWS does not log automatically (EC2) or when you want to separate logs. If you are logging on Serverless Infrastructure (e.g. Lambdas or ECS) you might find it easier to just let AWS Handle the logs automatically.
We originally developed this to be used on dedicated servers (on and off EC2) and chose to create something new because we wanted to:
* Be able to provide your own AWS programmatic access credentials
* Have a lightweight solution (only the handler is included and you need only one file)
If you already have a codebase that is using python's logger, you only need minor modifications to send your logs to AWS. In fact, you only need to change code at the logger creation. If you haven't done any logging before, I recommend you look at a basic tutorial on python's logging module. There are plenty of resources out there.
# Installing it
We are on PyPi, so you can install via pip
```bash
pip install cloudwatch
```
Or if you prefer to customise and (hopefully) feedback on improvements and bugs
```bash
git clone https://github.com/labrixdigital/cloudwatch
```
# Usage
This module is designed to fit right into your existing logging code, so you only need to replace (or add) a handler and the same logger will send events to cloudwatch.
```python
import logging
#Create the logger
logger = logging.getLogger('my_logger')
#Create the formatter
formatter = logging.Formatter('%(asctime)s : %(levelname)s - %(message)s')
#Import cloudwath and create the new handler
from cloudwatch import cloudwatch
handler = cloudwatch.CloudwatchHandler(log_group = 'my_log_group')
#Pass the formater to the handler
handler.setFormatter(formatter)
#Set the level
logger.setLevel(logging.WARNING)
#Add the handler to the logger
logger.addHandler(handler)
#USE IT!
logger.warning("Watch out! Something happened!")
```
# Credentials
## Specifying credentials and region
If you dont add credentials when creating the handler, it uses the default AWS credentials that you set-up on the CLI, or that you passed on the invokation (if using on EC2, Lambda, ECS), this is in line with the boto3 configuration [Expained here](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html). However, you can also specify the credentials like this:
```python
handler = cloudwatch.CloudwatchHandler(
log_group = 'my_log_group',
access_id = 'AWS_ACCESS_KEY_ID',
access_key = 'AWS_SECRET_ACCESS_KEY'
)
```
Likewise, you can specify a region where the logger will be with the parameter: `region = 'us-east-1'`
## Specifying log stream
If you dont add a log stream, the logger will create one for you with the timestamp and a random number. This is useful when you have multiple processes logging to the same log group without colliding. If you want, you can specify the log stream like this:
```python
handler = cloudwatch.CloudwatchHandler(
log_group = 'my_log_group',
log_stream = 'my_log_stream'
)
```
# Overflow
AWS CloudWatch Logs takes a maximum event size of 256 KB ([reference](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html)). This means that large messages can result in an error if not handled correctly. We have included 3 options in the parameters:
* __error__: This is the default, and will simply raise a value exception
* __truncate__: This will truncate the original message to the maximum possible size and log it
* __split__: This will divide the original message into multiple parts of the maximum size and send them separately
One caveat is that because the truncate and split options are based on bytes and not characters (because its size limited), its possible that non-ASCII characters will end up being split or truncated.
```python
#Specify truncate
handler = cloudwatch.CloudwatchHandler(
log_group = 'my_log_group',
overflow = 'truncate'
)
#Specify split
```python
handler = cloudwatch.CloudwatchHandler(
log_group = 'my_log_group',
overflow = 'split'
)
```
# Parameters
|Positional order|Keyword argument|Required|Default|Description|
|---|---|---|---|---|
|0|`access_id`|No|Taken from the AWS Configuration File or Role|The AWS Access Key ID that you want to use to interact with your AWS Account. Usually a 20 character alphanumeric.|
|1|`access_key`|No|Taken from the AWS Configuration File or Role|The corresponding AWS Secret to the above parameter|
|2|`region`|No|Taken from the AWS Configuration File or Role|The AWS Region name (e.g. `us-east-1`)|
|3|`log_group`|Yes||The name of the log group. If it already exists, it writes to it, otherwise it creates it.|
|4|`log_stream`|No|Datetime in the format `%Y%m%d%H%M%S%f` and 3 random digits|The name of the log stream. If it already exists, it writes to it, otherwise it creates it.|
|5|`overflow`|No|Defines the behaviour when a message is too large to send in one API call. Either `'error'`, `'truncate'` or `'split'`. Default is `'error'`|
# Legacy initialisation
We much prefer keyword arguments, and encourage you to use them. However, if you really want to avoid some typing, the order of the positional arguments work as follows:
```python
handler = cloudwatch.CloudwatchHandler(
'AWS_ACCESS_KEY_ID',
'AWS_SECRET_ACCESS_KEY',
'REGION',
'LOG_GROUP',
'LOG_STREAM',
'OVERFLOW'
)
```
Raw data
{
"_id": null,
"home_page": "",
"name": "cloudwatch",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "cloudwatch,aws,boto3,logging,logger",
"author": "Ernesto Monroy",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/48/50/2dac00b744f18834ea4e23cd126fa1d169acab00c86634e498fa5293bce5/cloudwatch-1.2.2.tar.gz",
"platform": null,
"description": "# AWS Cloudwatch Lightweight Handler\n\nThis small log handler is designed to send events to AWS Cloudwatch. It is useful when operating infrastructure outside of the AWS, when AWS does not log automatically (EC2) or when you want to separate logs. If you are logging on Serverless Infrastructure (e.g. Lambdas or ECS) you might find it easier to just let AWS Handle the logs automatically.\n\nWe originally developed this to be used on dedicated servers (on and off EC2) and chose to create something new because we wanted to:\n\n* Be able to provide your own AWS programmatic access credentials\n* Have a lightweight solution (only the handler is included and you need only one file)\n\nIf you already have a codebase that is using python's logger, you only need minor modifications to send your logs to AWS. In fact, you only need to change code at the logger creation. If you haven't done any logging before, I recommend you look at a basic tutorial on python's logging module. There are plenty of resources out there.\n\n# Installing it\n\nWe are on PyPi, so you can install via pip\n\n```bash\npip install cloudwatch\n```\n\nOr if you prefer to customise and (hopefully) feedback on improvements and bugs\n\n```bash\ngit clone https://github.com/labrixdigital/cloudwatch\n```\n\n# Usage\n\nThis module is designed to fit right into your existing logging code, so you only need to replace (or add) a handler and the same logger will send events to cloudwatch.\n\n```python\nimport logging\n#Create the logger\nlogger = logging.getLogger('my_logger')\n#Create the formatter\nformatter = logging.Formatter('%(asctime)s : %(levelname)s - %(message)s')\n\n#Import cloudwath and create the new handler\nfrom cloudwatch import cloudwatch\nhandler = cloudwatch.CloudwatchHandler(log_group = 'my_log_group')\n\n#Pass the formater to the handler\nhandler.setFormatter(formatter)\n#Set the level\nlogger.setLevel(logging.WARNING)\n#Add the handler to the logger\nlogger.addHandler(handler)\n\n#USE IT!\nlogger.warning(\"Watch out! Something happened!\")\n```\n\n# Credentials\n\n## Specifying credentials and region\n\nIf you dont add credentials when creating the handler, it uses the default AWS credentials that you set-up on the CLI, or that you passed on the invokation (if using on EC2, Lambda, ECS), this is in line with the boto3 configuration [Expained here](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html). However, you can also specify the credentials like this:\n\n```python\nhandler = cloudwatch.CloudwatchHandler(\n log_group = 'my_log_group',\n access_id = 'AWS_ACCESS_KEY_ID', \n access_key = 'AWS_SECRET_ACCESS_KEY'\n)\n```\n\nLikewise, you can specify a region where the logger will be with the parameter: `region = 'us-east-1'`\n\n## Specifying log stream\n\nIf you dont add a log stream, the logger will create one for you with the timestamp and a random number. This is useful when you have multiple processes logging to the same log group without colliding. If you want, you can specify the log stream like this:\n\n```python\nhandler = cloudwatch.CloudwatchHandler(\n log_group = 'my_log_group',\n log_stream = 'my_log_stream'\n)\n```\n\n# Overflow\n\nAWS CloudWatch Logs takes a maximum event size of 256 KB ([reference](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html)). This means that large messages can result in an error if not handled correctly. We have included 3 options in the parameters:\n* __error__: This is the default, and will simply raise a value exception\n* __truncate__: This will truncate the original message to the maximum possible size and log it\n* __split__: This will divide the original message into multiple parts of the maximum size and send them separately\n\nOne caveat is that because the truncate and split options are based on bytes and not characters (because its size limited), its possible that non-ASCII characters will end up being split or truncated.\n\n```python\n#Specify truncate\nhandler = cloudwatch.CloudwatchHandler(\n log_group = 'my_log_group',\n overflow = 'truncate'\n)\n\n#Specify split\n```python\nhandler = cloudwatch.CloudwatchHandler(\n log_group = 'my_log_group',\n overflow = 'split'\n)\n```\n\n# Parameters\n\n|Positional order|Keyword argument|Required|Default|Description|\n|---|---|---|---|---|\n|0|`access_id`|No|Taken from the AWS Configuration File or Role|The AWS Access Key ID that you want to use to interact with your AWS Account. Usually a 20 character alphanumeric.|\n|1|`access_key`|No|Taken from the AWS Configuration File or Role|The corresponding AWS Secret to the above parameter|\n|2|`region`|No|Taken from the AWS Configuration File or Role|The AWS Region name (e.g. `us-east-1`)|\n|3|`log_group`|Yes||The name of the log group. If it already exists, it writes to it, otherwise it creates it.|\n|4|`log_stream`|No|Datetime in the format `%Y%m%d%H%M%S%f` and 3 random digits|The name of the log stream. If it already exists, it writes to it, otherwise it creates it.|\n|5|`overflow`|No|Defines the behaviour when a message is too large to send in one API call. Either `'error'`, `'truncate'` or `'split'`. Default is `'error'`|\n\n# Legacy initialisation\n\nWe much prefer keyword arguments, and encourage you to use them. However, if you really want to avoid some typing, the order of the positional arguments work as follows:\n\n```python\nhandler = cloudwatch.CloudwatchHandler(\n 'AWS_ACCESS_KEY_ID',\n 'AWS_SECRET_ACCESS_KEY',\n 'REGION',\n 'LOG_GROUP',\n 'LOG_STREAM',\n 'OVERFLOW'\n)\n```\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "A small handler for AWS Cloudwatch",
"version": "1.2.2",
"project_urls": {
"Bug Tracker": "https://github.com/labrixdigital/cloudwatch/issues",
"Homepage": "https://github.com/labrixdigital/cloudwatch"
},
"split_keywords": [
"cloudwatch",
"aws",
"boto3",
"logging",
"logger"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4f5e8555cb209edcc40758a6cbfaa0b5d588fea119f57caada5b7f16dec96fb0",
"md5": "37db42bdfc21164a6fdc94a968a90874",
"sha256": "c4c991bcb09495a0bbaa5603990bf65ea8fa5c106b6dfc685d297887ad73daa5"
},
"downloads": -1,
"filename": "cloudwatch-1.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "37db42bdfc21164a6fdc94a968a90874",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 6574,
"upload_time": "2023-11-08T16:46:53",
"upload_time_iso_8601": "2023-11-08T16:46:53.838172Z",
"url": "https://files.pythonhosted.org/packages/4f/5e/8555cb209edcc40758a6cbfaa0b5d588fea119f57caada5b7f16dec96fb0/cloudwatch-1.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "48502dac00b744f18834ea4e23cd126fa1d169acab00c86634e498fa5293bce5",
"md5": "0e3fca005fa36866b0317e64f896d613",
"sha256": "74e5663f5e3846c0130b4bb61eb611266495882e244102346dab007d9691236f"
},
"downloads": -1,
"filename": "cloudwatch-1.2.2.tar.gz",
"has_sig": false,
"md5_digest": "0e3fca005fa36866b0317e64f896d613",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 6576,
"upload_time": "2023-11-08T16:46:55",
"upload_time_iso_8601": "2023-11-08T16:46:55.738906Z",
"url": "https://files.pythonhosted.org/packages/48/50/2dac00b744f18834ea4e23cd126fa1d169acab00c86634e498fa5293bce5/cloudwatch-1.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-08 16:46:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "labrixdigital",
"github_project": "cloudwatch",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cloudwatch"
}
JSON
