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. **Anmerkung** Sie können Abfragen mit Parametern erstellen und speichern — wiederverwendbare Vorlagen mit benannten Platzhaltern. Anstatt mehrere Varianten derselben Abfrage mit unterschiedlichen Werten zu speichern, erstellen Sie eine Vorlage und geben Sie bei der Ausführung unterschiedliche Parameterwerte an. Diese Funktion wird derzeit nur für Abfragen unterstützt, die die Logs Insights-Abfragesprache verwenden. Weitere Informationen finden Sie unter [Gespeicherte Abfragen mit Parametern verwenden](#CWL_Insights-Parameterized-Queries). ------ #### [ Console ] **Um eine Abfrage zu speichern** 1. Öffnen Sie die CloudWatch Konsole unter [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Wählen Sie im Navigationsbereich **Logs** (Protokolle) und dann **Logs Insights** aus. 1. Erstellen Sie im Abfrage-Editor eine Abfrage. 1. Wählen Sie **Speichern**. 1. Geben Sie einen Namen für die Abfrage ein. 1. (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. 1. (Optional) Ändern Sie die Protokollgruppen oder den Abfragetext der Abfrage. 1. (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}} ``` 1. **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. 1. 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. 1. Wählen Sie **Speichern**. ------ #### [ AWS CLI ] **Um eine Abfrage zu speichern**, verwenden Sie`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 ``` (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](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) 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" } ] } ``` ------ **Tipp** Sie können einen Ordner für gespeicherte Abfragen mit `PutQueryDefinition` erstellen. Um einen Ordner für Ihre gespeicherten Abfragen zu erstellen, verwenden Sie einen Schrägstrich (/), um Ihrem gewünschten Abfragenamen den gewünschten Ordnernamen voranzustellen: `/`. Weitere Informationen zu dieser Aktion finden Sie unter [PutQueryDefinition](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html). ------ #### [ Console ] **So führen Sie eine gespeicherte Abfrage aus** 1. Öffnen Sie die CloudWatch Konsole unter [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Wählen Sie im Navigationsbereich **Logs** (Protokolle) und dann **Logs Insights** aus. 1. Wählen Sie auf der rechten Seite **Queries (Abfragen)** aus. 1. Wählen Sie Ihre Abfrage aus der Liste **Gespeicherte Abfragen** aus. Der Abfragetext wird im Abfrage-Editor angezeigt. 1. (Optional) Um eine Abfrage mit Parametern zu verwenden: 1. Wählen Sie im Seitenbereich **Gespeicherte Abfragen** das Pluszeichen (**\$1**) neben dem Abfragenamen aus. 1. Die Abfrage mit den Parametern wird im Abfrage-Editor angezeigt. Wenn Sie beispielsweise das Pluszeichen (**\$1**) neben wählen`ErrorsByLevel`, wird der Abfrage-Editor mit folgenden Informationen gefüllt: `$ErrorsByLevel(level=, applicationName=)` 1. Geben Sie die Werte für die Parameter (level, applicationName) an und führen Sie die Abfrage aus. Beispiel: `$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")` 1. 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 [StartQuery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html)mit der `$QueryName()` Syntax im `queryString` Feld auf: ``` { "logGroupNames": ["/aws/lambda/my-function"], "startTime": 1707566400, "endTime": 1707570000, "queryString": "$ErrorsByLevel(level=\"ERROR\", applicationName= \"OrderService\")" } ``` ------ **So speichern Sie eine neue Version einer gespeicherten Abfrage** 1. Öffnen Sie die CloudWatch Konsole unter [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Wählen Sie im Navigationsbereich **Logs** (Protokolle) und dann **Logs Insights** aus. 1. Wählen Sie auf der rechten Seite **Queries (Abfragen)** aus. 1. Wählen Sie Ihre Abfrage aus der Liste **Saved queries (Gespeicherte Abfragen)** aus. Anschließend wird sie im Abfrage-Editor angezeigt. 1. Ändern Sie die Abfrage. Wenn Sie die Abfrage ausführen müssen, um Ihre Arbeit zu überprüfen, wählen Sie **Run query (Abfrage ausführen)** aus. 1. Wenn Sie bereit sind, die neue Version zu speichern, wählen Sie **Actions (Aktionen)** und **Save as (Speichern unter)** aus. 1. Geben Sie einen Namen für die Abfrage ein. 1. (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. 1. (Optional) Ändern Sie die Protokollgruppen oder den Abfragetext der Abfrage. 1. Wählen Sie **Speichern**. Um eine Abfrage zu löschen, müssen Sie bei einer Rolle mit der Berechtigung `logs:DeleteQueryDefinition` angemeldet sein. **So bearbeiten oder löschen Sie eine gespeicherte Abfrage** 1. Öffnen Sie die CloudWatch Konsole unter [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Wählen Sie im Navigationsbereich **Logs** (Protokolle) und dann **Logs Insights** aus. 1. Wählen Sie auf der rechten Seite **Queries (Abfragen)** aus. 1. Wählen Sie Ihre Abfrage aus der Liste **Saved queries (Gespeicherte Abfragen)** aus. Anschließend wird sie im Abfrage-Editor angezeigt. 1. Wählen Sie **Actions (Aktionen)**, **Edit (Bearbeiten)** oder **Actions (Aktionen)**, **Delete (Löschen)** aus. ## 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` und`applicationName`. ``` 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 Abfrage`RecentN`, die als `sort @timestamp desc | limit {{count}}` (mit Parameter`count`, Standard`20`) 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 **Anmerkung** Jede gespeicherte Abfrage kann maximal 20 Parameter haben. 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). **Häufige Fehler** | Fehler | Ursache | | --- | --- | | Parameter werden nur für die CWLI-Abfragesprache unterstützt | Parameter werden nur in der CloudWatch Logs Insights-Abfragesprache unterstützt. | | Erforderliche Parameter wurden nicht in QueryString gefunden | Für einen Parameternamen in `--parameters` gibt es keine Übereinstimmung `{{placeholder}}` in der Abfragezeichenfolge. | | Die Anzahl der Parameter überschreitet den Höchstwert von 20 | Gespeicherte Abfragen unterstützen derzeit nur 20 Parameter. | | Doppelter Parametername | Die Abfragedefinition enthält doppelte Parameter in`parameters`. | **Anmerkung** Um eine gespeicherte Abfrage mit Parametern zu erstellen oder zu aktualisieren, benötigen Sie die `logs:PutQueryDefinition` entsprechende Berechtigung. Um eine auszuführen, benötigen Sie `logs:StartQuery` und`logs:DescribeQueryDefinitions`.