Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Salva ed esegui nuovamente le query di Logs Insights CloudWatch Dopo aver creato una query, è possibile salvarla in modo da poterla eseguire di nuovo in un secondo momento. Le query vengono salvate in una struttura di cartelle, in modo da poterle organizzare. Puoi salvare fino a 1000 query per regione per account. Le interrogazioni vengono salvate a un livello specifico della regione, non a un livello specifico dell'utente. Se si crea e si salva un'interrogazione, gli altri utenti con accesso ai CloudWatch registri nella stessa area possono visualizzare tutte le interrogazioni salvate e le relative strutture di cartelle nella regione. Per salvare una query, è necessario accedere a un ruolo che dispone dell'autorizzazione `logs:PutQueryDefinition`. Per visualizzare un elenco di query salvate, è necessario accedere a un ruolo che dispone dell'autorizzazione `logs:DescribeQueryDefinitions`. **Nota** È possibile creare e salvare interrogazioni con parametri, ovvero modelli riutilizzabili con segnaposto denominati. Invece di salvare più varianti della stessa interrogazione con valori diversi, create un modello e fornite valori di parametro diversi quando lo eseguite. Questa funzionalità è attualmente supportata solo per le query che utilizzano il linguaggio di query Logs Insights. Per ulteriori informazioni, vedere [Utilizzo delle interrogazioni salvate con](#CWL_Insights-Parameterized-Queries) parametri. ------ #### [ Console ] **Per salvare un'interrogazione** 1. Apri la CloudWatch console all'indirizzo [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Nel pannello di navigazione scegli **Logs** (Registri), quindi **Logs Insights**. 1. Nell'editor di query, crea una query. 1. Scegli **Save** (Salva). 1. Immettere un nome per la query. 1. (Facoltativo) Scegliere una cartella in cui si desidera salvare la query. Selezionare **Create new (Crea nuova)** per creare una cartella. Se si crea una nuova cartella, è possibile utilizzare i caratteri barra (/) nel nome della cartella per definire una struttura di cartelle. Ad esempio, la denominazione di una nuova cartella **folder-level-1/folder-level-2** crea una cartella di livello superiore denominata **folder-level-1**, con un'altra cartella chiamata **folder-level-2** all'interno di tale cartella. La query viene salvata in **folder-level-2**. 1. (Facoltativo) Modificare i gruppi di log o il testo della query. 1. (Facoltativo) Per utilizzare i parametri nella query, segui questi passaggi aggiuntivi: 1. **Aggiungi parametri alla tua query.** Sostituisci i valori statici con segnaposto utilizzando la `{{parameter}}` sintassi (doppie parentesi prima e dopo il nome del parametro). Esempio: interrogazione originale con valori statici: ``` fields @timestamp, @message | filter level = "Error" | filter applicationName = "OrderService" ``` Interrogazione aggiornata con parametri: ``` fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}} ``` 1. **Definire i parametri utilizzati nella query.** Per ogni parametro segnaposto, specificate: + **Nome**: deve corrispondere esattamente al nome del segnaposto (ad esempio,). `logLevel` `applicationName` + **Valore predefinito** (opzionale): il valore da utilizzare se non viene fornito alcun valore di parametro. + **Descrizione** (opzionale): spiega lo scopo del parametro. 1. Le interrogazioni con parametri possono essere eseguite utilizzando il nome della query con un `$` prefisso e passando i nomi dei parametri come coppie chiave-valore. **Per ulteriori informazioni, vedere Eseguire un'interrogazione salvata**. 1. Scegli **Save** (Salva). ------ #### [ AWS CLI ] **Per salvare un'interrogazione**, usa`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 ``` (Facoltativo) Per salvare un'interrogazione con parametri, aggiungete l'`--parameters`opzione e utilizzate i `{{parameterName}}` segnaposto nella stringa di query: ``` 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 ``` Per salvare un'interrogazione in una cartella, aggiungete il percorso della cartella come prefisso al nome della query: ``` 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 ] **Per salvare un'interrogazione**, chiama [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"] } ``` (Facoltativo) Per salvare un'interrogazione con parametri, includete il `parameters` campo e utilizzate i `{{parameterName}}` segnaposto nella stringa di query: ``` { "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" } ] } ``` ------ **Suggerimento** Puoi creare una cartella per le query salvate con`PutQueryDefinition`. Per creare una cartella per le query salvate, utilizza una barra (/) per anteporre al nome della query desiderata il nome della cartella: `<{{folder-name}}>/<{{query-name}}>`. Per ulteriori informazioni su questa azione, vedere. [PutQueryDefinition](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html) ------ #### [ Console ] **Per eseguire una query salvata** 1. Aprire la CloudWatch console all'indirizzo [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Nel pannello di navigazione scegli **Logs** (Registri), quindi **Logs Insights**. 1. A destra, scegliere **Query**. 1. Seleziona la tua interrogazione dall'elenco **Interrogazioni salvate**. Il testo della query viene visualizzato nell'editor delle query. 1. (Facoltativo) Per utilizzare un'interrogazione con parametri: 1. Scegli l'icona **\+** accanto al nome dell'interrogazione nel pannello laterale **Interrogazioni salvate**. 1. L'interrogazione con parametri viene visualizzata nell'editor delle interrogazioni. Ad esempio, se si sceglie l'icona **\+** accanto a`ErrorsByLevel`, l'editor di query viene popolato con: `$ErrorsByLevel(level=, applicationName=)` 1. Fornire i valori per i parametri (level, ApplicationName) ed eseguire la query. Ad esempio: `$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")` 1. Scegli **Esegui**. ------ #### [ AWS CLI ] **Per eseguire un'interrogazione salvata con parametri** Utilizzare `start-query` con la `$QueryName()` sintassi: ``` 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 ] **Per eseguire un'interrogazione salvata con parametri** Chiama [StartQuery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html)con la `$QueryName()` sintassi presente nel `queryString` campo: ``` { "logGroupNames": ["/aws/lambda/my-function"], "startTime": 1707566400, "endTime": 1707570000, "queryString": "$ErrorsByLevel(level=\"ERROR\", applicationName= \"OrderService\")" } ``` ------ **Per salvare una nuova versione di una query salvata** 1. Apri la CloudWatch console all'indirizzo [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Nel pannello di navigazione scegli **Logs** (Registri), quindi **Logs Insights**. 1. A destra, scegliere **Query**. 1. Selezionare la query dall'elenco **Saved queries (Query salvate)**. Viene visualizzata nell'editor di query. 1. Modificare la query. Se è necessario eseguire la query per controllare il proprio lavoro, scegliere **Run query (Esegui query)**. 1. Quando si è pronti per salvare la nuova versione, scegliere **Actions (Operazioni)**, **Save as (Salva con nome)**. 1. Immettere un nome per la query. 1. (Facoltativo) Scegliere una cartella in cui si desidera salvare la query. Selezionare **Create new (Crea nuova)** per creare una cartella. Se si crea una nuova cartella, è possibile utilizzare i caratteri barra (/) nel nome della cartella per definire una struttura di cartelle. Ad esempio, la denominazione di una nuova cartella **folder-level-1/folder-level-2** crea una cartella di livello superiore denominata **folder-level-1**, con un'altra cartella chiamata **folder-level-2** all'interno di tale cartella. La query viene salvata in **folder-level-2**. 1. (Facoltativo) Modificare i gruppi di log o il testo della query. 1. Scegli **Save** (Salva). Per eliminare una query, è necessario accedere a un ruolo che dispone dell'autorizzazione `logs:DeleteQueryDefinition`. **Per modificare o eliminare una query salvata** 1. Apri la CloudWatch console all'indirizzo [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Nel pannello di navigazione scegli **Logs** (Registri), quindi **Logs Insights**. 1. A destra, scegliere **Query**. 1. Selezionare la query dall'elenco **Saved queries (Query salvate)**. Viene visualizzata nell'editor di query. 1. Scegliere **Actions (Operazioni)**, **Edit (Modifica)** oppure **Actions (Operazioni)**, **Delete (Elimina)**. ## Utilizzo di interrogazioni salvate con parametri Le interrogazioni salvate con parametri sono modelli di query riutilizzabili con segnaposto denominati. Invece di conservare più copie di interrogazioni quasi identiche, è possibile salvare un modello e fornire valori di parametro diversi durante l'esecuzione della query. I parametri sono supportati solo nel linguaggio di interrogazione CloudWatch Logs Insights. **Come funziona** Quando si salva un'interrogazione, i segnaposto identificano i valori che è possibile fornire al momento dell'esecuzione della query. I segnaposti utilizzano la sintassi. `{{parameterName}}` Di seguito è riportato un esempio di interrogazione salvata denominata `ErrorsByLevel` con due parametri e. `logLevel` `applicationName` ``` fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}} ``` Per eseguire un'interrogazione salvata, è possibile richiamarla utilizzando il nome dell'interrogazione preceduto da `$` e passando i valori dei parametri. Il motore di query CloudWatch Logs Insights sostituisce ogni segnaposto. Se un parametro contiene valori predefiniti, tali valori vengono utilizzati se non vengono forniti altri valori. ``` # 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() ``` I nomi delle interrogazioni salvate contenenti spazi o caratteri speciali devono essere racchiusi tra segni di spunta inversa: ``` $`Errors By Level`(logLevel = "WARN") ``` ### Esempi di interrogazioni salvate con parametri **Aggiungere un limite di risultati come parametro** Nome della query: `ErrorsByLevel` con parametri `logLevel` (default:`"ERROR"`), `applicationName` (default:`"OrderService"`) e `maxResults` (default:`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) ``` **Utilizzo di più interrogazioni salvate con parametri** L'esempio seguente utilizza `ErrorsByLevel` una seconda query salvata `RecentN` che è definita come `sort @timestamp desc | limit {{count}}` (con parametro`count`, impostazione predefinita`20`). Il motore di query CloudWatch Logs Insights espande ogni query prima di eseguirla. ``` # 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 ``` ### Quote e gestione degli errori **Nota** Ogni interrogazione salvata può avere un massimo di 20 parametri. La stringa di query espansa non può superare i 10.000 caratteri. I nomi dei parametri devono iniziare con una lettera o un carattere di sottolineatura. Un'interrogazione salvata non può fare riferimento a un'altra interrogazione salvata (le chiamate annidate non sono supportate). **Errori comuni** | Errore | Causa | | --- | --- | | I parametri sono supportati solo per il linguaggio di interrogazione CWLI | I parametri sono supportati solo nel linguaggio di query CloudWatch Logs Insights. | | Parametri obbligatori non trovati in QueryString | Il nome di un parametro in `--parameters` non ha una corrispondenza `{{placeholder}}` nella stringa di query. | | Il numero di parametri supera il massimo di 20 | Le interrogazioni salvate attualmente supportano solo 20 parametri. | | Nome di parametro duplicato | La definizione della query contiene parametri duplicati. `parameters` | **Nota** Per creare o aggiornare un'interrogazione salvata con parametri, è necessaria l'`logs:PutQueryDefinition`autorizzazione. Per eseguirne una, è necessario `logs:StartQuery` e`logs:DescribeQueryDefinitions`.