# AWS Cloudwatch Insights
Both a command line tool and a python API to simplify interacting with AWS cloudwatch insights
## CLI
### Installation
```shell
# globally
$ pipx install 'aws_cloudwatch_insights[cli]'
# or in a particular virtual env
$ pip install 'aws_cloudwatch_insights[cli]'
```
### Usage
Run via the `acwi` command. Results returned in json.
It takes either a file of AWS Inisghts code or a yaml file with a `query` argument and other options.
For example, if file `acwi.acwi` contained this:
```
fields @timestamp, @message, @logStream, @log
| sort @timestamp desc
| limit 20
```
And you ran this:
```shell
$ acwi --group-names /aws/lambda/log_maker --region us-west-2 --start -30d tmp/acwi.acwi --out results.json
```
It would run the query against the stated log group in the stated region from 30 days ago.
Alternatively, if you had a file `acwi.yml` containing this:
```yaml
query: |
fields @timestamp, @message, @logStream, @log
| sort @timestamp desc
| limit 20
groups:
- /aws/lambda/log_maker
region: us-west-2
start: -30d
out_file: results.json
```
And running this:
```shell
$ acwi acwi.yml
```
You would get the same result.
If an option is on both the command line of in the .yml file, the command line overrides the value in the file.
There is some fancy partial results returned as the query runs. You can shut these off using the `--quiet` option.
## API
If you're only using the api, you don't need to install with the `[cli]` extras.
```shell
$ pip install aws_cloudwatch_insights
```
## Usage
### Examples
```python
from aws_cloudwatch_insights import Insights
from datetime import timedelta
insights = Insights()
query = """
fields @timestamp, @message, @logStream, @log
| sort @timestamp desc
| limit 20
"""
results = insights.get_insights(
query, group_names=["/aws/lambda/log_maker"], result_limit=20,
start_time=-timedelta(days=1)
)
```
### Reference
From the inline documentation:
```python
class Insights:
def __init__(self, logs_client: Optional[BaseClient] = None):
"""
Object for querying AWS Cloudwatch. Optionally takes a boto3 client as an argument, otherwise creates its own
"""
...
def get_insights(self, query: str, result_limit: int, group_names: List[str], start_time: Union[int, datetime, timedelta],
end_time: Union[int, datetime, timedelta, None] = None, callback: Optional[CallbackFunction] = None,
error: Optional[ErrorFunction] = None, jsonify: bool = True) -> Iterable[GenericDict]:
"""
Gets elements from AWS Cloudwatch Logs using an Insights query:
Returns an iterable of dicts
query: The Insights query
result_limit: Limit of the number of results returned
group_names: The log groups searched through
start_time: The time of the earliest record the query looks for. Can be an int timestamp, a datetime, or a
timedelta. If it's a timedelta, the start time is now offset by the delta
end_time: The time of the latest record the query looks for. Accepts same values as `start_time`
callback: A function witch is called when partial results are returned, before the function returns the final
results. Takes the partial results as an argument.
error: If included, this function is called when an exception is encountered (instead of not catching the
exception). The arguments passed to the function are the Exception instance and the partial results. If
this function doesn't through an exception, get_insights() returns the returned value of this function, empty
list if that value is None
jsonify: If set to True, attempts to parse suspected json objects. If parsing fails, just returns the string.
Default: True
"""
...
```
## Development
Requires make:
```shell
# setting up dev environment
$ make develop
# run tests
$ make test
# ... or
$ pytest
# run tests for all environments
$ make test-all
```
No CI/CD or coverage yet
## To Do
* If someone tells me they actually use this, I'll bump it to v1.0.0
* More extensive CLI unit tests
* `--csv` output option
* Integration tests
## Credits
This package was created with _cookiecutter_ and the `audreyr/cookiecutter-pypackage` project template.
Raw data
{
"_id": null,
"home_page": "https://github.com/valmikirao/aws_cloudwatch_insights",
"name": "aws-cloudwatch-insights",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "aws,cloudwatch,insights",
"author": "Valmiki Rao",
"author_email": "valmikirao@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/67/78/606c0879f8c40dddbd2c8d1ed13d6eacd860ec66794890285395a0937127/aws_cloudwatch_insights-0.1.5.tar.gz",
"platform": null,
"description": "# AWS Cloudwatch Insights\n\n\n\n\n\nBoth a command line tool and a python API to simplify interacting with AWS cloudwatch insights\n\n## CLI\n\n### Installation\n\n```shell\n# globally\n$ pipx install 'aws_cloudwatch_insights[cli]'\n# or in a particular virtual env\n$ pip install 'aws_cloudwatch_insights[cli]'\n```\n\n### Usage\n\nRun via the `acwi` command. Results returned in json.\n\nIt takes either a file of AWS Inisghts code or a yaml file with a `query` argument and other options.\n\nFor example, if file `acwi.acwi` contained this:\n\n```\nfields @timestamp, @message, @logStream, @log\n| sort @timestamp desc\n| limit 20\n```\n\nAnd you ran this:\n\n```shell\n$ acwi --group-names /aws/lambda/log_maker --region us-west-2 --start -30d tmp/acwi.acwi --out results.json\n```\n\nIt would run the query against the stated log group in the stated region from 30 days ago.\n\nAlternatively, if you had a file `acwi.yml` containing this:\n\n```yaml\nquery: |\n fields @timestamp, @message, @logStream, @log\n | sort @timestamp desc\n | limit 20\ngroups:\n - /aws/lambda/log_maker\nregion: us-west-2\nstart: -30d\nout_file: results.json\n```\n\nAnd running this:\n\n```shell\n$ acwi acwi.yml\n```\n\nYou would get the same result.\n\nIf an option is on both the command line of in the .yml file, the command line overrides the value in the file.\n\nThere is some fancy partial results returned as the query runs. You can shut these off using the `--quiet` option.\n\n## API\n\nIf you're only using the api, you don't need to install with the `[cli]` extras.\n\n```shell\n$ pip install aws_cloudwatch_insights\n```\n\n## Usage\n\n### Examples\n\n```python\nfrom aws_cloudwatch_insights import Insights\nfrom datetime import timedelta\n\ninsights = Insights()\nquery = \"\"\"\nfields @timestamp, @message, @logStream, @log\n| sort @timestamp desc\n| limit 20\n\"\"\"\n\nresults = insights.get_insights(\n query, group_names=[\"/aws/lambda/log_maker\"], result_limit=20,\n start_time=-timedelta(days=1)\n)\n\n```\n\n### Reference\n\nFrom the inline documentation:\n\n```python\nclass Insights:\n def __init__(self, logs_client: Optional[BaseClient] = None):\n \"\"\"\n Object for querying AWS Cloudwatch. Optionally takes a boto3 client as an argument, otherwise creates its own\n \"\"\"\n ...\n\n def get_insights(self, query: str, result_limit: int, group_names: List[str], start_time: Union[int, datetime, timedelta],\n end_time: Union[int, datetime, timedelta, None] = None, callback: Optional[CallbackFunction] = None,\n error: Optional[ErrorFunction] = None, jsonify: bool = True) -> Iterable[GenericDict]:\n \"\"\"\n Gets elements from AWS Cloudwatch Logs using an Insights query:\n\n Returns an iterable of dicts\n\n query: The Insights query\n result_limit: Limit of the number of results returned\n group_names: The log groups searched through\n start_time: The time of the earliest record the query looks for. Can be an int timestamp, a datetime, or a\n timedelta. If it's a timedelta, the start time is now offset by the delta\n end_time: The time of the latest record the query looks for. Accepts same values as `start_time`\n callback: A function witch is called when partial results are returned, before the function returns the final\n results. Takes the partial results as an argument.\n error: If included, this function is called when an exception is encountered (instead of not catching the\n exception). The arguments passed to the function are the Exception instance and the partial results. If\n this function doesn't through an exception, get_insights() returns the returned value of this function, empty\n list if that value is None\n jsonify: If set to True, attempts to parse suspected json objects. If parsing fails, just returns the string.\n Default: True\n \"\"\"\n ...\n```\n\n## Development\n\nRequires make:\n\n```shell\n# setting up dev environment\n$ make develop\n\n# run tests\n$ make test\n# ... or\n$ pytest\n\n# run tests for all environments\n$ make test-all\n\n```\n\nNo CI/CD or coverage yet\n\n## To Do\n* If someone tells me they actually use this, I'll bump it to v1.0.0\n* More extensive CLI unit tests\n* `--csv` output option\n* Integration tests\n\n## Credits\n\nThis package was created with _cookiecutter_ and the `audreyr/cookiecutter-pypackage` project template.\n\n\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "Library and cli for querying AWS Cloudwatch Insights",
"version": "0.1.5",
"split_keywords": [
"aws",
"cloudwatch",
"insights"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2dba5f75823ad5fe7983500aaad6a19af9e7d125454f3669d5eb63e6ee69b13f",
"md5": "50021a4dda841865ba37ee4864805dda",
"sha256": "78053313edb3d1d9ee51722c1fd850502788971489f963cd233fb3c673e4826e"
},
"downloads": -1,
"filename": "aws_cloudwatch_insights-0.1.5-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "50021a4dda841865ba37ee4864805dda",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 13731,
"upload_time": "2023-04-14T20:13:03",
"upload_time_iso_8601": "2023-04-14T20:13:03.375871Z",
"url": "https://files.pythonhosted.org/packages/2d/ba/5f75823ad5fe7983500aaad6a19af9e7d125454f3669d5eb63e6ee69b13f/aws_cloudwatch_insights-0.1.5-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6778606c0879f8c40dddbd2c8d1ed13d6eacd860ec66794890285395a0937127",
"md5": "02bf9e364ffe3718c1dd02f5502f5874",
"sha256": "c492a74bf48ec9a7914b8de0a8517dc5f2aa0d82f356f4d63eb6229fe729da7b"
},
"downloads": -1,
"filename": "aws_cloudwatch_insights-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "02bf9e364ffe3718c1dd02f5502f5874",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 9594,
"upload_time": "2023-04-14T20:13:05",
"upload_time_iso_8601": "2023-04-14T20:13:05.735466Z",
"url": "https://files.pythonhosted.org/packages/67/78/606c0879f8c40dddbd2c8d1ed13d6eacd860ec66794890285395a0937127/aws_cloudwatch_insights-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-14 20:13:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "valmikirao",
"github_project": "aws_cloudwatch_insights",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "aws-cloudwatch-insights"
}
JSON
