Metadata-Version: 2.1
Name: aws-cloudwatch-insights
Version: 0.1.3
Summary: Library and cli for querying AWS Cloudwatch Insights
Home-page: https://github.com/valmikirao/aws_cloudwatch_insights
Author: Valmiki Rao
Author-email: valmikirao@gmail.com
License: MIT license
Keywords: aws,cloudwatch,insights
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.7
Requires-Dist: boto3 (<2.0.0,>=1.21.40)
Requires-Dist: botocore (<2.0.0,>=1.21.40)
Provides-Extra: cli
Requires-Dist: Click (<8.0.0,>=7.0.0) ; extra == 'cli'
Requires-Dist: timedeltafmt (<1.0.0,>=0.1.1) ; extra == 'cli'
Requires-Dist: PyYAML (<7.0.0,>=6.0.0) ; extra == 'cli'
Provides-Extra: lint
Requires-Dist: flake8 (<6.0.0,>=5.0.4) ; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest (<8.0.0,>=7.0.0) ; extra == 'test'
Requires-Dist: freezegun (<2.0.0,>=1.2.2) ; extra == 'test'
Requires-Dist: mypy (<2.0.0,>=1.0.1) ; extra == 'test'
Provides-Extra: types
Requires-Dist: boto3-stubs (<2.0.0,>=1.26.80) ; extra == 'types'
Requires-Dist: botocore-stubs (<2.0.0,>=1.29.80) ; extra == 'types'
Requires-Dist: mypy-boto3-logs (<2.0.0,>=1.26.53) ; extra == 'types'
Requires-Dist: types-PyYAML (<7.0.0,>=6.0.12.8) ; extra == 'types'
Requires-Dist: types-Pygments (<3.0.0,>=2.14.0.5) ; extra == 'types'
Requires-Dist: types-click (<8.0.0,>=7.1.8) ; extra == 'types'
Requires-Dist: types-colorama (<1.0.0,>=0.4.15.8) ; extra == 'types'
Requires-Dist: types-docutils (<1.0.0,>=0.19.1.6) ; extra == 'types'
Requires-Dist: types-python-dateutil (<3.0.0,>=2.8.19.9) ; extra == 'types'
Requires-Dist: types-setuptools (<68.0.0,>=67.4.0.3) ; extra == 'types'


AWS Cloudwatch Insights
=======================


.. image:: https://img.shields.io/pypi/v/aws_cloudwatch_insights
   :target: https://img.shields.io/pypi/v/aws_cloudwatch_insights
   :alt: version


.. image:: https://img.shields.io/pypi/pyversions/aws_cloudwatch_insights
   :target: https://img.shields.io/pypi/pyversions/aws_cloudwatch_insights
   :alt: python versions


.. image:: https://img.shields.io/github/actions/workflow/status/valmikirao/aws_cloudwatch_insights/push-workflow.yml?branch=master
   :target: https://img.shields.io/github/actions/workflow/status/valmikirao/aws_cloudwatch_insights/push-workflow.yml?branch=master
   :alt: build


Both a command line tool and a python API to simplify interacting with AWS cloudwatch insights

CLI
---

Installation
^^^^^^^^^^^^

.. code-block:: 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:

.. code-block::

   fields @timestamp, @message, @logStream, @log
   | sort @timestamp desc
   | limit 20

And you ran this:

.. code-block:: 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:

.. code-block:: 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:

.. code-block:: 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.

.. code-block:: shell

   $ pip install aws_cloudwatch_insights

Usage
-----

Examples
^^^^^^^^

.. code-block:: 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:

.. code-block:: 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, docker, and docker-compose:

.. code-block:: shell

   # setting up dev environment
   $ make develop

   # run tests
   $ make test
   # ... or
   $ pytest

   # run tests for all environments
   $ make test-all
   $ make test-all-build  # checks to see if images need rebuilding
   # ... you can use the underlying script to pass args to docker-compose directly:
   $ ./scripts/run_tests_all.sh --build py36-no-cli py37  # runs for python 3.7 and python 3.6 with no cli

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.


