AWS AmazonCloudWatch documentation change
Summary
Added comprehensive documentation for using saved queries with parameters, including how to create, run, and manage parameterized queries via Console, AWS CLI, and API. Updated existing procedures and added new sections with examples, quotas, and error handling.
Security assessment
The changes are feature documentation updates introducing parameterized query functionality. There is no mention of security vulnerabilities, patches, or incident response. The only security-related content is a standard note about required IAM permissions (`logs:PutQueryDefinition`, `logs:StartQuery`, `logs:DescribeQueryDefinitions`), which is routine for feature documentation and does not indicate a security fix or new security feature.
Diff
diff --git a/AmazonCloudWatch/latest/logs/CWL_Insights-Saving-Queries.md b/AmazonCloudWatch/latest/logs/CWL_Insights-Saving-Queries.md index 4673c23c0..cad208f2f 100644 --- a//AmazonCloudWatch/latest/logs/CWL_Insights-Saving-Queries.md +++ b//AmazonCloudWatch/latest/logs/CWL_Insights-Saving-Queries.md @@ -4,0 +5,2 @@ +Using saved queries with parameters + @@ -13 +15,8 @@ To save a query, you must be logged into a role that has the permission `logs:Pu -###### To save a query +###### Note + +You can create and save queries with parameters — reusable templates with named placeholders. Instead of saving multiple variations of the same query with different values, create one template and provide different parameter values when you run it. This functionality is currently supported for queries using Logs Insights query language only. For more information, see Using saved queries with parameters. + +Console + + +**To save a query** @@ -23 +32 @@ To save a query, you must be logged into a role that has the permission `logs:Pu -If you don't see a **Save** button, you need to change to the new design for the CloudWatch Logs console. To do so: + 5. Enter a name for the query. @@ -25 +34 @@ If you don't see a **Save** button, you need to change to the new design for the - 1. In the navigation pane, choose **Log groups**. + 6. (Optional) Choose a folder where you want to save the query. Select **Create new** to create a folder. If you create a new folder, you can use slash (/) characters in the folder name to define a folder structure. For example, naming a new folder `folder-level-1/folder-level-2` creates a top-level folder called `folder-level-1`, with another folder called `folder-level-2` inside that folder. The query is saved in `folder-level-2`. @@ -27 +36 @@ If you don't see a **Save** button, you need to change to the new design for the - 2. Choose **Try the new design**. + 7. (Optional) Change the query's log groups or query text. @@ -29 +38,27 @@ If you don't see a **Save** button, you need to change to the new design for the - 3. In the navigation pane, choose **Insights** and return to step 3 of this procedure. + 8. (Optional) To use parameters in your query, follow these additional steps: + + 1. **Add parameters to your query.** Replace static values with placeholders using the `{{parameter}}` syntax (double braces before and after the parameter name). + +Example: Original query with static values: + + fields @timestamp, @message + | filter level = "Error" + | filter applicationName = "OrderService" + +Updated query with parameters: + + fields @timestamp, @message + | filter level = {{logLevel}} + | filter applicationName = {{applicationName}} + + 2. **Define the parameters used in your query.** For each placeholder parameter, specify: + + * **Name** : Must exactly match the placeholder name (for example, `logLevel`, `applicationName`). + + * **Default value** (optional): The value to use if no parameter value is provided. + + * **Description** (optional): Explains the parameter's purpose. + + 3. Queries with parameters can be run by using the query name with a `$` prefix and passing the parameter names as key-value pairs. See **To run a saved query** for details. + + 9. Choose **Save**. @@ -31 +65,0 @@ If you don't see a **Save** button, you need to change to the new design for the - 5. Enter a name for the query. @@ -33 +66,0 @@ If you don't see a **Save** button, you need to change to the new design for the - 6. (Optional) Choose a folder where you want to save the query. Select **Create new** to create a folder. If you create a new folder, you can use slash (/) characters in the folder name to define a folder structure. For example, naming a new folder `folder-level-1/folder-level-2` creates a top-level folder called `folder-level-1`, with another folder called `folder-level-2` inside that folder. The query is saved in `folder-level-2`. @@ -35 +67,0 @@ If you don't see a **Save** button, you need to change to the new design for the - 7. (Optional) Change the query's log groups or query text. @@ -37 +69 @@ If you don't see a **Save** button, you need to change to the new design for the - 8. Choose **Save**. +AWS CLI @@ -39,0 +72 @@ If you don't see a **Save** button, you need to change to the new design for the +**To save a query** , use `put-query-definition`: @@ -41,0 +75,59 @@ If you don't see a **Save** button, you need to change to the new design for the + aws logs put-query-definition \ + --name "ErrorsByLevel" \ + --query-string "fields @timestamp, @message | filter level = \"ERROR\"" \ + --log-group-names "/aws/lambda/my-function" \ + --region us-east-1 + +(Optional) To save a query with parameters, add the `--parameters` option and use `{{parameterName}}` placeholders in the query string: + + + aws logs put-query-definition \ + --name "ErrorsByLevel" \ + --query-string "fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}}" \ + --parameters '[{"name":"logLevel","defaultValue":"ERROR","description":"Log level to filter"},{"name":"applicationName","defaultValue":"OrderService","description":"Application name to filter"}]' \ + --log-group-names "/aws/lambda/my-function" \ + --region us-east-1 + +To save a query in a folder, prefix the query name with the folder path: + + + aws logs put-query-definition \ + --name "my-folder/ErrorsByLevel" \ + --query-string "fields @timestamp, @message | filter level = {{logLevel}}" \ + --parameters '[{"name":"logLevel","defaultValue":"ERROR","description":"Log level to filter"}]' \ + --log-group-names "/aws/lambda/my-function" \ + --region us-east-1 + +API + + +**To save a query** , call [PutQueryDefinition](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html): + + + { + "name": "ErrorsByLevel", + "queryString": "fields @timestamp, @message | filter level = \"ERROR\"", + "logGroupNames": ["/aws/lambda/my-function"] + } + +(Optional) To save a query with parameters, include the `parameters` field and use `{{parameterName}}` placeholders in the query string: + + + { + "name": "ErrorsByLevel", + "queryString": "fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}}", + "logGroupNames": ["/aws/lambda/my-function"], + "parameters": [ + { + "name": "logLevel", + "defaultValue": "ERROR", + "description": "Log level to filter" + }, + { + "name": "applicationName", + "defaultValue": "OrderService", + "description": "Application name to filter" + } + ] + } + @@ -45,0 +138,3 @@ You can create a folder for saved queries with `PutQueryDefinition`. To create a +Console + + @@ -54 +149,9 @@ You can create a folder for saved queries with `PutQueryDefinition`. To create a - 4. Select your query from **Saved queries** list. It appears in the query editor. + 4. Select your query from the **Saved queries** list. The query text appears in the query editor. + + 5. (Optional) To use a query with parameters: + + 1. Choose the **+** icon next to the query name in the **Saved queries** side panel. + + 2. The query with parameters appears in the query editor. For example, if you choose the **+** icon next to `ErrorsByLevel`, the query editor is populated with: `$ErrorsByLevel(level=, applicationName=)` + + 3. Provide the values for the parameters (level, applicationName) and run the query. For example: `$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")` @@ -56 +159 @@ You can create a folder for saved queries with `PutQueryDefinition`. To create a - 5. Choose **Run**. + 6. Choose **Run**. @@ -60,0 +164,29 @@ You can create a folder for saved queries with `PutQueryDefinition`. To create a +AWS CLI + + +**To run a saved query with parameters** + +Use `start-query` with the `$QueryName()` syntax: + + + aws logs start-query \ + --log-group-names "/aws/lambda/my-function" \ + --start-time 1707566400 --end-time 1707570000 \ + --query-string '$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")' \ + --region us-east-1 + +API + + +**To run a saved query with parameters** + +Call [StartQuery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html) with the `$QueryName()` syntax in the `queryString` field: + + + { + "logGroupNames": ["/aws/lambda/my-function"], + "startTime": 1707566400, + "endTime": 1707570000, + "queryString": "$ErrorsByLevel(level=\"ERROR\", applicationName= \"OrderService\")" + } + @@ -102,0 +235,79 @@ To delete a query, you must be logged in to a role that has the `logs:DeleteQuer +## Using saved queries with parameters + +Saved queries with parameters are reusable query templates with named placeholders. Instead of maintaining multiple copies of nearly identical queries, you can save a template and supply different parameter values when running the query. Parameters are only supported in the CloudWatch Logs Insights query language. + +**How it works** + +When saving a query, placeholders identify the values which you can provide at query execution time. Placeholders use the `{{parameterName}}` syntax. The following is an example of a saved query named `ErrorsByLevel` with two parameters `logLevel` and `applicationName`. + + + fields @timestamp, @message + | filter level = {{logLevel}} + | filter applicationName = {{applicationName}} + +To run a saved query, you can invoke it using the query name prefixed with `$` and passing the parameter values. The CloudWatch Logs Insights query engine replaces each placeholder. If a parameter contains default values, then those values are used if no other values are provided. + + + # Run query by using query name and passing parameter values explicitly + $ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService") + + # Run query without specifying parameter values - default values are used in this case. + $ErrorsByLevel() + +Saved query names containing spaces or special characters need to be enclosed with backticks: + +