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.

Console

Para guardar una consulta

1. Abra la CloudWatch consola en https://console.aws.amazon.com/cloudwatch/.

2. En el panel de navegación, elija Logs (Registros) y, luego, Logs Insights (Registros de Insights).

3. En el editor de consultas, cree una consulta.

4. Seleccione Save.

5. Escriba un nombre para la consulta.

6. (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.

7. (Opcional) Cambie los grupos de registro de la consulta o el texto de la consulta.

8. (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}}

   2. 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.

   3. 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.

9. Seleccione Save.

AWS CLI

Para guardar una consulta, utiliceput-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:

{
  "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"
    }
  ]
}

Console

Para ejecutar una consulta guardada

1. Abra la CloudWatch consola en. https://console.aws.amazon.com/cloudwatch/

2. En el panel de navegación, elija Logs (Registros) y, luego, Logs Insights (Registros de Insights).

3. A la derecha, elija Queries (Consultas).

4. Seleccione la consulta en la lista de consultas guardadas. El texto de la consulta aparece en el editor de consultas.

5. (Opcional) Para usar una consulta con parámetros:

   1. Seleccione el icono + situado junto al nombre de la consulta en el panel lateral de consultas guardadas.

   2. La consulta con los parámetros aparece en el editor de consultas. Por ejemplo, si selecciona el icono + situado junto aErrorsByLevel, el editor de consultas aparecerá con: $ErrorsByLevel(level=, applicationName=)

   3. Proporcione los valores de los parámetros (level, ApplicationName) y ejecute la consulta. Por ejemplo: $ErrorsByLevel(level= "ERROR", applicationName= "OrderService")

6. Seleccione Ejecutar.

AWS CLI

Para ejecutar una consulta guardada con parámetros

start-queryUtilí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 StartQuerycon la $QueryName() sintaxis del queryString campo:

{
  "logGroupNames": ["/aws/lambda/my-function"],
  "startTime": 1707566400,
  "endTime": 1707570000,
  "queryString": "$ErrorsByLevel(level=\"ERROR\", applicationName= \"OrderService\")"
}

Para eliminar una consulta, debe haber iniciado sesión en un rol que tenga el permiso logs:DeleteQueryDefinition.

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 yapplicationName.

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ámetrocount, predeterminado20). 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

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).