From 39e9585a358b0b1120ab6e288d8fd57a66f6625d Mon Sep 17 00:00:00 2001 From: Brian Celenza Date: Sat, 15 Apr 2023 09:26:16 -0700 Subject: [PATCH] fix(deps): Maintenance update for dependency libraries (#64) Commit to trigger build for dependency build up and update public documentation in NPM. --- README.md | 37 ++++++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 2e04ac8..94c9868 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,27 @@ # CloudWatch Logs Query (`cwq`) -Executes a [CloudWatch Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html) query against one or more log groups. Command output options are available for further parsing of results. +The missing command-line interface for [Amazon CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html). + +CWQ is designed for fast searching and presentation of log data in multiple formats for reading or processing. It is intended as a tool to quickly share queries and results with others, or cement and maintain queries in operational runbooks/playbooks. For advanced processing command output can be piped (`|`) to another process, for example using `--format json` with [jq](https://stedolan.github.io/jq/). + +The basic command structure is: + +```bash +cwq --log-group '' +``` + +Where `` is the log group you want to search and `` is the [CloudWatch Logs Insights query](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html) to search with. + +Further usage guidelines are described below and options can be found via the help argument: + +```bash +cwq -h +``` ## Installation ```bash $ npm install -g cwq -$ cwq --help ``` ## Usage @@ -16,7 +31,7 @@ $ cwq --help ```bash $ cwq --log-group MyLogGroup 'filter @type = "REPORT" | stats max(@maxMemoryUsed / 1000 / 1000) as maxMemoryUsedMB by bin(5m)' -Querying between 2021-10-30T18:12:46.491Z and 2021-10-30T19:12:46.491Z +Querying between 2021-10-30T18:12:46.491Z and 2021-10-30T19:12:46.491Z for 1 log group(s): ["MyLogGroup"] "bin(5m)","maxMemoryUsedMB" @@ -34,7 +49,7 @@ Querying between 2021-10-30T18:12:46.491Z and 2021-10-30T19:12:46.491Z "2021-10-30 18:15:00.000","229" ``` -The default output of the command is a CSV representation of the query results for the last hour, which you can save to a file or pipe to other commands for further processing. `cwq` also supports other [output formats](#formats) and [time ranges](#tiem-ranges). +The default output of the command is a CSV representation of the query results for the last hour, which you can save to a file or pipe to other commands for further processing. `cwq` also supports other [output formats](#formats) and [time ranges](#time-ranges). The CLI respects any AWS environment variables provided, so you can use it across accounts and regions: @@ -52,7 +67,7 @@ By default, `cwq` will query over the previous hour: $ cwq --log-group MyLogGroup 'filter @message like /ERROR/' # results for last hour returned ``` -To set a custom start time, pass `--start` (or `-s`) with a duration or ISO 8601 formatted time. +To set a custom start time, pass `--start` (or `-s`) with a duration or ISO 8601 formatted time. Example for find errors from the last 8 hours: @@ -70,12 +85,12 @@ $ cwq --log-group MyLogGroup --start 2021-05-08T06:00:00Z --end 2021-05-08T12:00 #### Comma Separated Values (CSV) -The default output format is CSV, which can be piped in a unix command line to other utilities like `read`, `sed`, and `tr`. +The default output format is CSV, which can be piped in a unix command line to other utilities like `read`, `sed`, and `tr`, or to a file and opened as a spreadsheet. ```bash $ cwq --log-group MyLogGroup 'filter @type = "REPORT" | stats max(@maxMemoryUsed / 1000 / 1000) as maxMemoryUsedMB by bin(5m)' -Querying between 2021-10-30T18:12:46.491Z and 2021-10-30T19:12:46.491Z +Querying between 2021-10-30T18:12:46.491Z and 2021-10-30T19:12:46.491Z for 1 log group(s): ["MyLogGroup"] "bin(5m)","maxMemoryUsedMB" @@ -100,7 +115,7 @@ You can use JSON for more advanced result manipulation: ```bash $ cwq --log-group MyLogGroup --format json 'filter @type = "REPORT" | stats max(@maxMemoryUsed / 1000 / 1000) as maxMemoryUsedMB by bin(5m)' -Querying between 2021-10-30T18:12:46.491Z and 2021-10-30T19:12:46.491Z +Querying between 2021-10-30T18:12:46.491Z and 2021-10-30T19:12:46.491Z for 1 log group(s): ["MyLogGroup"] [{"bin(5m)":"2021-10-30 19:10:00.000","maxMemoryUsedMB":"229"},{"bin(5m)":"2021-10-30 19:05:00.000","maxMemoryUsedMB":"229"},{"bin(5m)":"2021-10-30 19:00:00.000","maxMemoryUsedMB":"229"},{"bin(5m)":"2021-10-30 18:55:00.000","maxMemoryUsedMB":"229"},{"bin(5m)":"2021-10-30 18:50:00.000","maxMemoryUsedMB":"229"},{"bin(5m)":"2021-10-30 18:45:00.000","maxMemoryUsedMB":"229"},{"bin(5m)":"2021-10-30 18:40:00.000","maxMemoryUsedMB":"229"},{"bin(5m)":"2021-10-30 18:35:00.000","maxMemoryUsedMB":"229"},{"bin(5m)":"2021-10-30 18:30:00.000","maxMemoryUsedMB":"229"},{"bin(5m)":"2021-10-30 18:25:00.000","maxMemoryUsedMB":"229"},{"bin(5m)":"2021-10-30 18:20:00.000","maxMemoryUsedMB":"229"},{"bin(5m)":"2021-10-30 18:15:00.000","maxMemoryUsedMB":"229"}] @@ -113,7 +128,7 @@ If you need to share on a medium that supports [Markdown](https://en.wikipedia.o ```bash $ cwq --format markdown --log-group MyLogGroup 'filter @type = "REPORT" | stats max(@maxMemoryUsed / 1000 / 1000) as maxMemoryUsedMB by bin(5m)' -Querying between 2021-10-30T18:12:46.491Z and 2021-10-30T19:12:46.491Z +Querying between 2021-10-30T18:12:46.491Z and 2021-10-30T19:12:46.491Z for 1 log group(s): ["MyLogGroup"] | bin(5m) | maxMemoryUsedMB | @@ -134,7 +149,7 @@ Querying between 2021-10-30T18:12:46.491Z and 2021-10-30T19:12:46.491Z #### Just The Messages -Sometimes you only want the log message from the returned data. You can get that by just passing `-m` or `--message-only`: +Sometimes you only want the log message from the returned data, as if you were reading the log file on the host. You can get that by passing `-m` or `--message-only`: ```bash $ cwq --message-only --logGroup MyLogGroup 'filter @message like /ERROR/' @@ -168,4 +183,4 @@ logs:StopQuery logs:DescribeLogGroups ``` -The necessary permissions are also available in the `CloudWatchReadOnlyAccess` [managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) \ No newline at end of file +The necessary permissions are also available in the `CloudWatchReadOnlyAccess` [managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies). \ No newline at end of file