{"id":13449420,"url":"https://github.com/jorgebastida/awslogs","last_synced_at":"2025-05-13T17:10:06.397Z","repository":{"id":26168440,"uuid":"29613985","full_name":"jorgebastida/awslogs","owner":"jorgebastida","description":"AWS CloudWatch logs for Humans™","archived":false,"fork":false,"pushed_at":"2024-05-17T01:57:44.000Z","size":1143,"stargazers_count":4915,"open_issues_count":160,"forks_count":338,"subscribers_count":56,"default_branch":"master","last_synced_at":"2025-05-11T23:32:58.359Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jorgebastida.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-01-21T21:02:01.000Z","updated_at":"2025-05-08T08:46:01.000Z","dependencies_parsed_at":"2023-02-17T23:46:13.567Z","dependency_job_id":"28c13754-ce42-4bcc-92fb-3165ad6b0f3e","html_url":"https://github.com/jorgebastida/awslogs","commit_stats":{"total_commits":260,"total_committers":38,"mean_commits":6.842105263157895,"dds":0.2730769230769231,"last_synced_commit":"0886184d72acb57dfde6020fad41ec908a32806e"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgebastida%2Fawslogs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgebastida%2Fawslogs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgebastida%2Fawslogs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgebastida%2Fawslogs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jorgebastida","download_url":"https://codeload.github.com/jorgebastida/awslogs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253870868,"owners_count":21976613,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T06:00:37.639Z","updated_at":"2025-05-13T17:10:06.260Z","avatar_url":"https://github.com/jorgebastida.png","language":"Python","funding_links":[],"categories":["Development","HarmonyOS","Python","Open Source Repos"],"sub_categories":["Time Series","Windows Manager","CloudWatch"],"readme":"awslogs\n=======\n\n.. image:: https://badge.fury.io/py/awslogs.png\n  :target: http://badge.fury.io/py/awslogs\n\n.. image:: https://coveralls.io/repos/jorgebastida/awslogs/badge.svg\n  :target: https://coveralls.io/r/jorgebastida/awslogs\n\n\n``awslogs`` is a simple command line tool for querying groups, streams and events from `Amazon CloudWatch \u003chttp://aws.amazon.com/cloudwatch/\u003e`_ logs.\n\nOne 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``::\n\n    $ awslogs get /var/log/syslog ip-10-1.* --start='2h ago' | grep ERROR\n\n\nFeatures\n--------\n\n* Aggregate logs from across streams.\n\n  - Aggregate all streams in a group.\n  - Aggregate streams matching a regular expression.\n\n* Colored output.\n* List existing groups\n\n  - ``$ awslogs groups``\n\n* List existing streams\n\n  - ``$ awslogs streams /var/log/syslog``\n\n* Watch logs as they are created\n\n  - ``$ awslogs get /var/log/syslog ALL --watch``\n\n* Human-friendly time filtering:\n\n  - ``--start='23/1/2015 14:23'``\n  - ``--start='2h ago'``\n  - ``--start='2d ago'``\n  - ``--start='2w ago'``\n  - ``--start='2d ago' --end='1h ago'``\n\n* Retrieve event metadata:\n\n  - ``--timestamp`` Prints the creation timestamp of each event.\n  - ``--ingestion-time`` Prints the ingestion time of each event.\n\n\nExample\n-------\n\nRunning: ``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.\n\n.. image:: https://github.com/jorgebastida/awslogs/raw/master/media/screenshot.png\n\n\nInstallation\n------------\n\nYou can easily install ``awslogs`` using ``pip``::\n\n  $ pip install awslogs\n\nIf you are on OSX El Capitan, use the following (Why? Check Donald Stufft's comment `here \u003chttps://github.com/pypa/pip/issues/3165#issuecomment-145856429\u003e`_) ::\n\n  $ pip install awslogs --ignore-installed six\n\nYou can also install it with `brew \u003chttps://brew.sh/\u003e`_::\n\n  $ brew install awslogs\n\n\nOptions\n-------\n\n* ``awslogs groups``: List existing groups\n* ``awslogs streams GROUP``: List existing streams within ``GROUP``\n* ``awslogs get GROUP [STREAM_EXPRESSION]``: Get logs matching ``STREAM_EXPRESSION`` in ``GROUP``.\n\n  - Expressions can be regular expressions or the wildcard ``ALL`` if you want any and don't want to type ``.*``.\n\n**Note:** You need to provide to all these options a valid AWS region using ``--aws-region`` or ``AWS_REGION`` env variable.\n\n\nTime options\n-------------\n\nWhile querying for logs you can filter events by ``--start`` ``-s`` and ``--end`` ``-e`` date.\n\n* By minute:\n\n  - ``--start='2m'`` Events generated two minutes ago.\n  - ``--start='1 minute'`` Events generated one minute ago.\n  - ``--start='5 minutes'`` Events generated five minutes ago.\n\n* By hours:\n\n  - ``--start='2h'`` Events generated two hours ago.\n  - ``--start='1 hour'`` Events generated one hour ago.\n  - ``--start='5 hours'`` Events generated five hours ago.\n\n* By days:\n\n  - ``--start='2d'`` Events generated two days ago.\n  - ``--start='1 day'`` Events generated one day ago.\n  - ``--start='5 days'`` Events generated five days ago.\n\n* By weeks:\n\n  - ``--start='2w'`` Events generated two week ago.\n  - ``--start='1 week'`` Events generated one weeks ago.\n  - ``--start='5 weeks'`` Events generated five week ago.\n\n* Using specific dates:\n\n  - ``--start='23/1/2015 12:00'`` Events generated after midday  on the 23th of January 2015.\n  - ``--start='1/1/2015'`` Events generated after midnight on the 1st of January 2015.\n  - ``--start='Sat Oct 11 17:13:46 UTC 2003'`` You can use detailed dates too.\n\n  Note, for time parsing awslogs uses `dateutil \u003chttps://dateutil.readthedocs.io/en/latest/\u003e`_.\n\n* All previous examples are applicable for  ``--end`` ``-e`` too.\n\nFilter options\n----------------\n\nYou can use ``--filter-pattern`` if you want to only retrieve logs which match one CloudWatch Logs Filter pattern.\nThis is helpful if you know precisely what you are looking for, and don't want to download the entire stream.\n\nFor example, if you only want to download only the report events from a Lambda stream you can run::\n\n  $ awslogs get my_lambda_group --filter-pattern=\"[r=REPORT,...]\"\n\n\nFull documentation of how to write patterns: http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/FilterAndPatternSyntax.html\n\nJSON logs\n------------\n\nIn a similar way than the `aws-cli \u003chttp://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html#controlling-output-filter\u003e`_ command, you can use  ``--query`` to\nfilter each of your json log lines and extract certain fields::\n\n  $ awslogs get my_lambda_group --query=message\n\nThis will only display the ``message`` field for each of the json log lines.\n\n\nUsing third-party endpoints\n-------------\n\nIf you use tools like localstack, fakes3 or other, consider to change boto3 endpoint using ``--aws-endpoint-url`` or ``AWS_REGION`` env variable.\n\n\nAWS IAM Permissions\n-------------------\n\nThe required permissions to run ``awslogs`` are contained within the `CloudWatchLogsReadOnlyAccess \u003chttps://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-identity-based-access-control-cwl.html\u003e`_ AWS managed permissions.\nAs of 2020-01-13, these are the permissions::\n\n    {\n        \"Version\": \"2012-10-17\",\n        \"Statement\": [\n            {\n                \"Action\": [\n                    \"logs:Describe*\",\n                    \"logs:Get*\",\n                    \"logs:List*\",\n                    \"logs:StartQuery\",\n                    \"logs:StopQuery\",\n                    \"logs:TestMetricFilter\",\n                    \"logs:FilterLogEvents\"\n                ],\n                \"Effect\": \"Allow\",\n                \"Resource\": \"*\"\n            }\n        ]\n    }\n\nContribute\n-----------\n\n* Fork the repository on GitHub.\n* Write a test which shows that the bug was fixed or that the feature works as expected.\n\n  - Use ``tox`` command to run all the tests in all locally available python version.\n\n* Send a pull request and bug the maintainer until it gets merged and published. :).\n\nFor more instructions see `TESTING.md`.\n\n\nHelpful Links\n-------------\n\n* http://aws.amazon.com/cloudwatch/\n* https://boto.readthedocs.io/en/latest/ref/logs.html\n* http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/cloudwatch_limits.html\n\n\n\nHow to provide AWS credentials to awslogs\n------------------------------------------\n\nAlthough, the most straightforward thing to do might be use ``--aws-access-key-id`` and ``--aws-secret-access-key``, this will eventually become a pain in the ass.\n\n* If you only have one ``AWS`` account, my personal recommendation would be to configure `aws-cli \u003chttp://aws.amazon.com/cli/\u003e`_. ``awslogs`` will use those credentials if available. If you have multiple ``AWS`` profiles managed by ``aws-cli``, just add ``--profile [PROFILE_NAME]`` at the end of every ``awslogs`` command to use those credentials, or set the ``AWS_PROFILE`` env variable.\n* If you don't want to setup ``aws-cli``, I would recommend you to use `envdir \u003chttps://pypi.python.org/pypi/envdir\u003e`_ in order to make ``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY`` available to ``awslogs``.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjorgebastida%2Fawslogs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjorgebastida%2Fawslogs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjorgebastida%2Fawslogs/lists"}