README

awslogs
=======

.. image:: https://badge.fury.io/py/awslogs.png
  :target: http://badge.fury.io/py/awslogs

.. image:: https://coveralls.io/repos/jorgebastida/awslogs/badge.svg
  :target: https://coveralls.io/r/jorgebastida/awslogs


awslogs is a simple command line tool for querying groups, streams and events from Amazon CloudWatch _ logs.

One of the most powerful features is to query events from several streams and consume them (ordered) in pseudo-realtime using your favourite tools such as grep::

    $ awslogs get /var/log/syslog ip-10-1. --start='2h ago' | grep ERROR


Features
--------

 Aggregate logs from across streams.

  - Aggregate all streams in a group.
  - Aggregate streams matching a regular expression.

 Colored output.
 List existing groups

  - $ awslogs groups

 List existing streams

  - $ awslogs streams /var/log/syslog

 Watch logs as they are created

  - $ awslogs get /var/log/syslog ALL --watch

 Human-friendly time filtering:

  - --start='23/1/2015 14:23'
  - --start='2h ago'
  - --start='2d ago'
  - --start='2w ago'
  - --start='2d ago' --end='1h ago'

 Retrieve event metadata:

  - --timestamp Prints the creation timestamp of each event.
  - --ingestion-time Prints the ingestion time of each event.


Example
-------

Running: awslogs get /var/logs/syslog ALL -s1d will return you events from any stream in the /var/logs/syslog group generated in the last day.

.. image:: https://github.com/jorgebastida/awslogs/raw/master/media/screenshot.png


Installation
------------

You can easily install awslogs using pip::

  $ pip install awslogs

If you are on OSX El Capitan, use the following (Why? Check Donald Stufft's comment here _) ::

  $ pip install awslogs --ignore-installed six

You can also install it with brew _::

  $ brew install awslogs


Options
-------

 awslogs groups: List existing groups
 awslogs streams GROUP: List existing streams within GROUP
 awslogs get GROUP [STREAM_EXPRESSION]: Get logs matching STREAM_EXPRESSION in GROUP.

  - Expressions can be regular expressions or the wildcard ALL if you want any and don't want to type ..

Note: You need to provide to all these options a valid AWS region using --aws-region or AWS_REGION env variable.


Time options
-------------

While querying for logs you can filter events by --start -s and --end -e date.

 By minute:

  - --start='2m' Events generated two minutes ago.
  - --start='1 minute' Events generated one minute ago.
  - --start='5 minutes' Events generated five minutes ago.

 By hours:

  - --start='2h' Events generated two hours ago.
  - --start='1 hour' Events generated one hour ago.
  - --start='5 hours' Events generated five hours ago.

 By days:

  - --start='2d' Events generated two days ago.
  - --start='1 day' Events generated one day ago.
  - --start='5 days' Events generated five days ago.

 By weeks:

  - --start='2w' Events generated two week ago.
  - --start='1 week' Events generated one weeks ago.
  - --start='5 weeks' Events generated fi