Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Guarde y vuelva a ejecutar CloudWatch las consultas de Logs Insights Cuando haya creado una consulta, puede guardarla para volver a ejecutarla más adelante. Las consultas se guardan en una estructura de carpetas para que pueda mantenerlas organizadas. Puede guardar hasta 1000 consultas por región y cuenta. Las consultas se guardan en un nivel específico de la región, no en un nivel específico del usuario. Si crea y guarda una consulta, otros usuarios con acceso a los CloudWatch registros de la misma región podrán ver todas las consultas guardadas y sus estructuras de carpetas en la región. Para guardar una consulta, debe haber iniciado sesión en un rol que tenga el permiso `logs:PutQueryDefinition`. Para ver una lista de consultas guardadas, debe haber iniciado sesión en un rol que tenga el permiso `logs:DescribeQueryDefinitions`. **nota** Puede crear y guardar consultas con parámetros: plantillas reutilizables con marcadores de posición con nombre. En lugar de guardar varias variantes de la misma consulta con valores diferentes, cree una plantilla y proporcione valores de parámetros diferentes al ejecutarla. Actualmente, esta funcionalidad solo se admite para consultas que utilizan el lenguaje de consultas de Logs Insights. Para obtener más información, consulte [Uso de consultas guardadas con parámetros](#CWL_Insights-Parameterized-Queries). ------ #### [ Console ] **Para guardar una consulta** 1. Abra la CloudWatch consola en [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. En el panel de navegación, elija **Logs** (Registros) y, luego, **Logs Insights** (Registros de Insights). 1. En el editor de consultas, cree una consulta. 1. Seleccione **Save**. 1. Escriba un nombre para la consulta. 1. (Opcional) Elija una carpeta en la que desee guardar la consulta. Seleccione **Create new (Crear nueva)** para crear una carpeta. Si crea una carpeta nueva, puede utilizar caracteres de barra (/) en el nombre de la carpeta para definir una estructura de carpetas. Por ejemplo, poner nombre a una carpeta nueva **folder-level-1/folder-level-2** crea una carpeta de nivel superior llamada **folder-level-1**, con otra carpeta llamada **folder-level-2** dentro de esa carpeta. La consulta se guarda en **folder-level-2**. 1. (Opcional) Cambie los grupos de registro de la consulta o el texto de la consulta. 1. (Opcional) Para usar los parámetros en la consulta, siga estos pasos adicionales: 1. **Añada parámetros a la consulta.** Sustituya los valores estáticos por marcadores de posición utilizando la `{{parameter}}` sintaxis (corchetes dobles antes y después del nombre del parámetro). Ejemplo: consulta original con valores estáticos: ``` fields @timestamp, @message | filter level = "Error" | filter applicationName = "OrderService" ``` Consulta actualizada con parámetros: ``` fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}} ``` 1. **Defina los parámetros utilizados en la consulta.** Para cada parámetro marcador de posición, especifique: + **Nombre**: debe coincidir exactamente con el nombre del marcador de posición (por ejemplo,`logLevel`,`applicationName`). + **Valor predeterminado** (opcional): el valor que se utilizará si no se proporciona ningún valor de parámetro. + **Descripción** (opcional): explica el propósito del parámetro. 1. Las consultas con parámetros se pueden ejecutar utilizando el nombre de la consulta con un `$` prefijo y pasando los nombres de los parámetros como pares clave-valor. Consulte **Para ejecutar una consulta guardada** para obtener más información. 1. Seleccione **Save**. ------ #### [ AWS CLI ] **Para guardar una consulta**, utilice`put-query-definition`: ``` 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 ``` (Opcional) Para guardar una consulta con parámetros, añada la `--parameters` opción y utilice `{{parameterName}}` marcadores de posición en la cadena de consulta: ``` 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 ``` Para guardar una consulta en una carpeta, añada al nombre de la consulta la ruta de la carpeta: ``` 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 ] **Para guardar una consulta**, llama a [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"] } ``` (Opcional) Para guardar una consulta con parámetros, incluye el `parameters` campo y utiliza `{{parameterName}}` marcadores de posición en la cadena de consulta: ``` { "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" } ] } ``` ------ **sugerencia** Puede crear una carpeta para las consultas guardadas con `PutQueryDefinition`. Con el fin de crear una carpeta para las consultas guardadas, utilice una barra diagonal (/) a fin de anteponer el nombre de la consulta deseada con el nombre de la carpeta deseada: `/`. Para obtener más información sobre esta acción, consulte [PutQueryDefinition](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html). ------ #### [ Console ] **Para ejecutar una consulta guardada** 1. Abra la CloudWatch consola en. [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 1. En el panel de navegación, elija **Logs** (Registros) y, luego, **Logs Insights** (Registros de Insights). 1. A la derecha, elija **Queries (Consultas)**. 1. Seleccione la consulta en la lista de **consultas guardadas**. El texto de la consulta aparece en el editor de consultas. 1. (Opcional) Para usar una consulta con parámetros: 1. Seleccione el icono **\$1** situado junto al nombre de la consulta en el panel lateral de **consultas guardadas**. 1. La consulta con los parámetros aparece en el editor de consultas. Por ejemplo, si selecciona el icono **\$1** situado junto a`ErrorsByLevel`, el editor de consultas aparecerá con: `$ErrorsByLevel(level=, applicationName=)` 1. Proporcione los valores de los parámetros (level, ApplicationName) y ejecute la consulta. Por ejemplo: `$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")` 1. Seleccione **Ejecutar**. ------ #### [ AWS CLI ] **Para ejecutar una consulta guardada con parámetros** `start-query`Utilícela con la `$QueryName()` siguiente sintaxis: ``` 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 ] **Para ejecutar una consulta guardada con parámetros** Llame [StartQuery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html)con la `$QueryName()` sintaxis del `queryString` campo: ``` { "logGroupNames": ["/aws/lambda/my-function"], "startTime": 1707566400, "endTime": 1707570000, "queryString": "$ErrorsByLevel(level=\"ERROR\", applicationName= \"OrderService\")" } ``` ------ **Para guardar una nueva versión de una consulta guardada** 1. Abra la CloudWatch consola en [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. En el panel de navegación, elija **Logs** (Registros) y, luego, **Logs Insights** (Registros de Insights). 1. A la derecha, elija **Queries (Consultas)**. 1. Seleccione la consulta de la lista **Saved queries (Consultas guardadas)** . Aparece en el editor de consultas. 1. Modifique la consulta. Si necesita ejecutarla para comprobar su trabajo, elija **Run query (Ejecutar consulta)**. 1. Cuando esté listo para guardar la nueva versión, elija **Actions (Acciones)**, **Save as (Guardar como)**. 1. Escriba un nombre para la consulta. 1. (Opcional) Elija una carpeta en la que desee guardar la consulta. Seleccione **Create new (Crear nueva)** para crear una carpeta. Si crea una carpeta nueva, puede utilizar caracteres de barra (/) en el nombre de la carpeta para definir una estructura de carpetas. Por ejemplo, poner nombre a una carpeta nueva **folder-level-1/folder-level-2** crea una carpeta de nivel superior llamada **folder-level-1**, con otra carpeta llamada **folder-level-2** dentro de esa carpeta. La consulta se guarda en **folder-level-2**. 1. (Opcional) Cambie los grupos de registro de la consulta o el texto de la consulta. 1. Seleccione **Save**. Para eliminar una consulta, debe haber iniciado sesión en un rol que tenga el permiso `logs:DeleteQueryDefinition`. **Para editar o eliminar una consulta guardada** 1. Abra la CloudWatch consola en [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. En el panel de navegación, elija **Logs** (Registros) y, luego, **Logs Insights** (Registros de Insights). 1. A la derecha, elija **Queries (Consultas)**. 1. Seleccione la consulta de la lista **Saved queries (Consultas guardadas)** . Aparece en el editor de consultas. 1. Elija **Actions (Acciones)**, **Edit (Editar)** o **Actions (Acciones)**, **Delete (Eliminar)**. ## Uso de consultas guardadas con parámetros Las consultas guardadas con parámetros son plantillas de consulta reutilizables con marcadores de posición con nombre. En lugar de mantener varias copias de consultas prácticamente idénticas, puede guardar una plantilla y proporcionar valores de parámetros diferentes al ejecutar la consulta. Los parámetros solo se admiten en el lenguaje de consultas de CloudWatch Logs Insights. **Cómo funciona** Al guardar una consulta, los marcadores de posición identifican los valores que puede proporcionar en el momento de la ejecución de la consulta. Los marcadores de posición utilizan la `{{parameterName}}` sintaxis. A continuación se muestra un ejemplo de una consulta guardada denominada `ErrorsByLevel` con dos parámetros `logLevel` y`applicationName`. ``` fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}} ``` Para ejecutar una consulta guardada, puede invocarla utilizando el nombre de la consulta con el prefijo `$` y pasando los valores de los parámetros. El motor de consultas CloudWatch de Logs Insights reemplaza cada marcador de posición. Si un parámetro contiene valores predeterminados, esos valores se utilizan si no se proporcionan otros valores. ``` # 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() ``` Los nombres de consulta guardados que contengan espacios o caracteres especiales deben estar entre comillas invertidas: ``` $`Errors By Level`(logLevel = "WARN") ``` ### Ejemplos de consultas guardadas con parámetros **Añadir un límite de resultados como parámetro** Nombre de consulta: `ErrorsByLevel` con parámetros `logLevel` (predeterminado:`"ERROR"`), `applicationName` (predeterminado:`"OrderService"`) y `maxResults` (predeterminado:`50`) ``` fields @timestamp, @message, @logStream | filter level = {{logLevel}} | filter applicationName = {{applicationName}} | sort @timestamp desc | limit {{maxResults}} ``` ``` # Run the query using the query name and passing parameter values $ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService", maxResults = 100) ``` **Uso de varias consultas guardadas con parámetros** En el ejemplo siguiente se utiliza `ErrorsByLevel` una segunda consulta guardada `RecentN` que se define como `sort @timestamp desc | limit {{count}}` (con parámetro`count`, predeterminado`20`). El motor de consultas de CloudWatch Logs Insights expande cada consulta antes de ejecutarla. ``` # Using multiple queries with parameters in sequence $ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService") | $RecentN(count = 10) # Each of the queries is expanded, resulting in the following query when it is run. fields @timestamp, @message | filter level = "WARN" | filter applicationName = "OrderService" | sort @timestamp desc | limit 10 ``` ### Cuotas y gestión de errores **nota** Cada consulta guardada puede tener un máximo de 20 parámetros. La cadena de consulta expandida no puede superar los 10 000 caracteres. Los nombres de los parámetros deben empezar por una letra o un guión bajo. Una consulta guardada no puede hacer referencia a otra consulta guardada (no se admiten las invocaciones anidadas). **Errores comunes** | Error | Causa | | --- | --- | | Los parámetros solo se admiten en el lenguaje de consultas CWLI | Los parámetros solo se admiten en el lenguaje de consultas CloudWatch de Logs Insights. | | No se encontraron los parámetros necesarios en QueryString | El nombre de un parámetro no `--parameters` coincide con el nombre de un parámetro `{{placeholder}}` en la cadena de consulta. | | El recuento de parámetros supera el máximo de 20 | Las consultas guardadas actualmente solo admiten 20 parámetros. | | Nombre de parámetro duplicado | La definición de consulta contiene parámetros duplicados`parameters`. | **nota** Para crear o actualizar una consulta guardada con parámetros, necesita el `logs:PutQueryDefinition` permiso. Para ejecutar una, necesita `logs:StartQuery` y`logs:DescribeQueryDefinitions`.