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.

Guarda y vuelve 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 Region-specific nivel, no en un nivel específico del usuario. Si creas y guardas una consulta, otros usuarios con acceso a los CloudWatch registros de la misma región pueden 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 mediante 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 de marcador de posición, especifique:

      • Nombre: debe coincidir exactamente con el nombre del marcador de posición (por ejemplologLevel,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 como prefijo:

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, incluya el parameters campo y utilice {{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 su 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 eliges el icono + situado junto a élErrorsByLevel, el editor de consultas se rellenará 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() 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 con 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 casi idénticas, puede guardar una plantilla y proporcionar diferentes valores de parámetros al ejecutar la consulta. Los parámetros solo se admiten en el lenguaje de consulta de CloudWatch Logs Insights.

Cómo funciona

Al guardar una consulta, los marcadores de posición identifican los valores que puedes 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 de CloudWatch 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 las consultas guardadas que contengan espacios o caracteres especiales deben ir 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 la consulta: ErrorsByLevel con los 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 amplía 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).