Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Speichern Sie CloudWatch Logs Insights-Abfragen und führen Sie sie erneut aus

Nachdem Sie eine Abfrage erstellt haben, können Sie sie speichern, um sie später erneut auszuführen. Abfragen werden in einer Ordnerstruktur gespeichert, sodass Sie sie organisieren können. Sie können bis zu 1000 Abfragen pro Region und pro Konto speichern.

Abfragen werden auf einer regionsspezifischen Ebene gespeichert, nicht auf einer benutzerspezifischen Ebene. Wenn Sie eine Abfrage erstellen und speichern, können andere Benutzer mit Zugriff auf CloudWatch Protokolle in derselben Region alle gespeicherten Abfragen und ihre Ordnerstrukturen in der Region sehen.

Um eine Abfrage zu speichern, müssen Sie bei einer Rolle mit der Berechtigung angemeldet sein logs:PutQueryDefinition. Um die Liste Ihrer gespeicherten Abfragen anzuzeigen, müssen Sie bei einer Rolle mit der Berechtigung logs:DescribeQueryDefinitions angemeldet sein.

Console

Um eine Abfrage zu speichern

1. Öffnen Sie die CloudWatch Konsole unter https://console.aws.amazon.com/cloudwatch/.

2. Wählen Sie im Navigationsbereich Logs (Protokolle) und dann Logs Insights aus.

3. Erstellen Sie im Abfrage-Editor eine Abfrage.

4. Wählen Sie Speichern.

5. Geben Sie einen Namen für die Abfrage ein.

6. (Optional) Wählen Sie den Ordner aus, in dem Sie die Abfrage speichern möchten. Wählen Sie Create new (Neu erstellen) aus, um einen Ordner zu erstellen. Wenn Sie einen neuen Ordner erstellen, können Sie Schrägstriche (/) im Ordnernamen verwenden, um eine Ordnerstruktur zu definieren. Wenn Sie beispielsweise einen neuen Ordner mit folder-level-1/folder-level-2 benennen, wird der Ordner folder-level-1 auf der obersten Ebene erstellt. In diesem Ordner befindet sich ein weiterer Ordner namens folder-level-2. Die Abfrage wird in folder-level-2 gespeichert.

7. (Optional) Ändern Sie die Protokollgruppen oder den Abfragetext der Abfrage.

8. (Optional) Gehen Sie wie folgt vor, um Parameter in Ihrer Abfrage zu verwenden:

   1. Fügen Sie Ihrer Abfrage Parameter hinzu. Ersetzen Sie statische Werte mithilfe der {{parameter}} Syntax durch Platzhalter (doppelte Klammern vor und nach dem Parameternamen).

      Beispiel: Ursprüngliche Abfrage mit statischen Werten:

      fields @timestamp, @message
      | filter level = "Error"
      | filter applicationName = "OrderService"

      Aktualisierte Abfrage mit Parametern:

      fields @timestamp, @message
      | filter level = {{logLevel}}
      | filter applicationName = {{applicationName}}

   2. Definieren Sie die in Ihrer Abfrage verwendeten Parameter. Geben Sie für jeden Platzhalterparameter Folgendes an:

      • Name: Muss exakt mit dem Platzhalternamen übereinstimmen (z. B.logLevel,applicationName).

      • Standardwert (optional): Der Wert, der verwendet werden soll, wenn kein Parameterwert angegeben wird.

      • Beschreibung (optional): Erläutert den Zweck des Parameters.

   3. Abfragen mit Parametern können ausgeführt werden, indem der Abfragename mit einem $ Präfix verwendet und die Parameternamen als Schlüssel-Wert-Paare übergeben werden. Weitere Informationen finden Sie unter So führen Sie eine gespeicherte Abfrage aus.

9. Wählen Sie Speichern.

AWS CLI

Um eine Abfrage zu speichern, verwenden Sieput-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

(Optional) Um eine Abfrage mit Parametern zu speichern, fügen Sie die --parameters Option hinzu und verwenden Sie {{parameterName}} Platzhalter in der Abfragezeichenfolge:

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

Um eine Abfrage in einem Ordner zu speichern, stellen Sie dem Abfragenamen den Ordnerpfad voran:

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

Um eine Abfrage zu speichern, rufen Sie PutQueryDefinition:

{
  "name": "ErrorsByLevel",
  "queryString": "fields @timestamp, @message | filter level = \"ERROR\"",
  "logGroupNames": ["/aws/lambda/my-function"]
}

(Optional) Um eine Abfrage mit Parametern zu speichern, schließen Sie das parameters Feld ein und verwenden Sie {{parameterName}} Platzhalter in der Abfragezeichenfolge:

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

So führen Sie eine gespeicherte Abfrage aus

1. Öffnen Sie die CloudWatch Konsole unter https://console.aws.amazon.com/cloudwatch/.

2. Wählen Sie im Navigationsbereich Logs (Protokolle) und dann Logs Insights aus.

3. Wählen Sie auf der rechten Seite Queries (Abfragen) aus.

4. Wählen Sie Ihre Abfrage aus der Liste Gespeicherte Abfragen aus. Der Abfragetext wird im Abfrage-Editor angezeigt.

5. (Optional) Um eine Abfrage mit Parametern zu verwenden:

   1. Wählen Sie im Seitenbereich Gespeicherte Abfragen das Pluszeichen (+) neben dem Abfragenamen aus.

   2. Die Abfrage mit den Parametern wird im Abfrage-Editor angezeigt. Wenn Sie beispielsweise das Pluszeichen (+) neben wählenErrorsByLevel, wird der Abfrage-Editor mit folgenden Informationen gefüllt: $ErrorsByLevel(level=, applicationName=)

   3. Geben Sie die Werte für die Parameter (level, applicationName) an und führen Sie die Abfrage aus. Beispiel: $ErrorsByLevel(level= "ERROR", applicationName= "OrderService")

6. Klicken Sie auf Ausführen.

AWS CLI

Um eine gespeicherte Abfrage mit Parametern auszuführen

Verwenden Sie es start-query mit der folgenden $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

Um eine gespeicherte Abfrage mit Parametern auszuführen

Rufen Sie StartQuerymit der $QueryName() Syntax im queryString Feld auf:

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

Um eine Abfrage zu löschen, müssen Sie bei einer Rolle mit der Berechtigung logs:DeleteQueryDefinition angemeldet sein.

Gespeicherte Abfragen mit Parametern verwenden

Gespeicherte Abfragen mit Parametern sind wiederverwendbare Abfragevorlagen mit benannten Platzhaltern. Anstatt mehrere Kopien fast identischer Abfragen zu verwalten, können Sie eine Vorlage speichern und bei der Ausführung der Abfrage unterschiedliche Parameterwerte angeben. Parameter werden nur in der CloudWatch Logs Insights-Abfragesprache unterstützt.

Funktionsweise

Beim Speichern einer Abfrage identifizieren Platzhalter die Werte, die Sie bei der Ausführung der Abfrage angeben können. Platzhalter verwenden die {{parameterName}} Syntax. Im Folgenden finden Sie ein Beispiel für eine gespeicherte Abfrage ErrorsByLevel mit dem Namen logLevel undapplicationName.

fields @timestamp, @message
| filter level = {{logLevel}}
| filter applicationName = {{applicationName}}

Um eine gespeicherte Abfrage auszuführen, können Sie sie aufrufen, indem Sie den Abfragenamen mit dem Präfix verwenden $ und die Parameterwerte übergeben. Die CloudWatch Logs Insights-Abfrage-Engine ersetzt jeden Platzhalter. Wenn ein Parameter Standardwerte enthält, werden diese Werte verwendet, sofern keine anderen Werte angegeben werden.

# 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()

Gespeicherte Abfragenamen, die Leerzeichen oder Sonderzeichen enthalten, müssen mit Backticks umschlossen werden:

$`Errors By Level`(logLevel = "WARN")

Beispiel für gespeicherte Abfragen mit Parametern

Hinzufügen eines Ergebnislimits als Parameter

Abfragename: ErrorsByLevel mit Parametern logLevel (Standard:"ERROR"), applicationName (Standard:"OrderService") und maxResults (Standard: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)

Verwenden mehrerer gespeicherter Abfragen mit Parametern

Das folgende Beispiel verwendet ErrorsByLevel eine zweite gespeicherte AbfrageRecentN, die als sort @timestamp desc | limit {{count}} (mit Parametercount, Standard20) definiert ist. Die CloudWatch Logs Insights-Abfrage-Engine erweitert jede Abfrage, bevor sie ausgeführt wird.

# 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

Kontingente und Fehlerbehandlung

Die erweiterte Abfragezeichenfolge darf 10.000 Zeichen nicht überschreiten. Parameternamen müssen mit einem Buchstaben oder Unterstrich beginnen. Eine gespeicherte Abfrage kann nicht auf eine andere gespeicherte Abfrage verweisen (verschachtelte Aufrufe werden nicht unterstützt).