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

Comprensione dei concetti relativi alle interrogazioni pianificate

Prima di creare interrogazioni pianificate, è necessario comprendere questi concetti chiave che influiscono sulla modalità di esecuzione delle query e sul luogo in cui vengono forniti i risultati.

Separazione dei ruoli IAM

Le query pianificate richiedono due ruoli IAM separati: uno per l'esecuzione delle query e l'altro per fornire risultati a destinazioni come bucket Amazon S3, bus di EventBridge eventi Amazon o tabelle di ricerca. Comprendere il motivo per cui esiste questa separazione ti aiuta a configurare correttamente le autorizzazioni e a utilizzare i vantaggi operativi e di sicurezza che offre.

L'architettura a due ruoli divide le responsabilità tra accesso e distribuzione dei dati. Il ruolo di esecuzione delle query accede ai dati di registro ed esegue le query, mentre il ruolo di destinazione di consegna scrive i risultati nella destinazione prescelta. Questa separazione segue il principio del privilegio minimo: ogni ruolo dispone solo delle autorizzazioni necessarie per la sua funzione specifica.

Questa separazione offre vantaggi pratici per le tue operazioni. Dal punto di vista della sicurezza, se è necessario modificare il luogo di consegna dei risultati, è sufficiente modificare il ruolo di destinazione senza modificare le autorizzazioni di esecuzione delle query. Per la conformità e il controllo, puoi tracciare chiaramente quale ruolo accede ai dati di registro sensibili e quale ruolo scrive su sistemi esterni. In questo modo è più facile dimostrare che l'infrastruttura di analisi dei log segue le best practice di sicurezza.

Cross-region e utilizzo su più account

Una query pianificata viene creata in una regione specifica e viene eseguita in quella regione. Tuttavia, puoi interrogare i gruppi di log e fornire risultati in tutte le regioni e gli account. È necessario configurare uno o più AWS account come account di monitoraggio e collegarli a più account di origine. Un account di monitoraggio è un AWS account centrale in grado di visualizzare e interagire con i dati di osservabilità generati dagli account di origine. Un account di origine è un AWS account individuale che genera dati di osservabilità per le risorse che vi risiedono. Gli account di origine condividono i dati di osservabilità con l'account di monitoraggio. Quindi puoi impostare query pianificate dall'account di monitoraggio utilizzando i gruppi di log di tutti gli account collegati.

Approccio alternativo: utilizza la centralizzazione dei CloudWatch log per replicare i dati di log provenienti da più account e regioni in un account di monitoraggio centrale. Ciò consente di creare query pianificate in un'unica regione che accedano a tutti i log centralizzati, evitando query interregionali e semplificando la gestione delle autorizzazioni IAM.

Pianifica le espressioni e la gestione dei fusi orari

La pianificazione definita determina quando viene eseguita la query e la frequenza di esecuzione. La scelta dell'espressione di pianificazione corretta influisce sul momento in cui si ricevono i risultati e sulla quantità di dati interrogati. La comprensione dei tipi di espressione consente di scegliere tra semplicità e precisione.

Le espressioni Cron forniscono un controllo preciso sulla tempistica, consentendo di specificare orari, giorni della settimana o giorni del mese esatti. Usa le espressioni cron quando hai bisogno che le query vengano eseguite in orari lavorativi specifici o in linea con le pianificazioni operative. Nella console puoi anche pianificare le query utilizzando semplici opzioni di calendario.

Tutte le interrogazioni pianificate vengono eseguite in UTC, indipendentemente dal fuso orario locale o da dove si trovano le risorse. AWS Ciò è particolarmente importante quando si pianificano le query per l'orario di lavoro o per analisi sensibili al fattore tempo. Ad esempio, se la tua azienda opera nell'ora orientale degli Stati Uniti e desideri un rapporto giornaliero alle 9:00 ET, devi tenere conto della differenza UTC (14:00 UTC durante l'ora legale, 13:00 UTC altrimenti). Pianifica le espressioni di pianificazione tenendo conto dell'UTC per garantire che le query vengano eseguite negli orari previsti.

Scelta di un linguaggio di interrogazione

Le interrogazioni pianificate supportano tre diversi linguaggi di interrogazione e la tua scelta influisce sia sul modo in cui scrivi le query sia sulla facilità con cui il tuo team può gestirle. La lingua giusta dipende dai requisiti di analisi e dalle competenze esistenti del team.

Se stai principalmente filtrando e aggregando i dati di registro, CloudWatch Logs Insights Query Language offre la sintassi più semplice. Per trasformazioni di dati complesse in cui è necessario rimodellare o arricchire i dati in più passaggi, l'approccio basato sulla pipeline di PPL semplifica l'applicazione della logica. Quando è necessario eseguire join o aggregazioni complesse simili alle operazioni di database, SQL fornisce una sintassi familiare che i team esperti di database possono adottare rapidamente.

Selezione della destinazione e casi d'uso

Il luogo in cui invii i risultati delle query determina cosa puoi fare con essi. Questa scelta modella l'intero flusso di lavoro a valle, che si tratti di creare analisi a lungo termine, attivare risposte automatiche o entrambe le cose. Comprendere i punti di forza di ogni tipo di destinazione ti aiuta a progettare l'architettura giusta per il tuo caso d'uso.

Le destinazioni Amazon S3 sono ottimizzate per lo storage e l'elaborazione in batch. Quando devi conservare i risultati delle query per mesi o anni, analizzare le tendenze nel tempo o inserire dati in piattaforme di analisi, Amazon S3 offre uno storage conveniente con conservazione illimitata. EventBridge le destinazioni sono ottimizzate per l'automazione in tempo reale. Quando i risultati delle query devono innescare azioni immediate, come l'invio di avvisi, l'avvio di flussi di lavoro o l'aggiornamento dei sistemi, i risultati si ottengono sotto forma EventBridge di eventi a cui le applicazioni possono rispondere istantaneamente. Per impostazione predefinita, tutti gli eventi di completamento delle query vengono inviati automaticamente come eventi al bus di eventi predefinito, consentendo l'integrazione con i sistemi di elaborazione a valle, le funzioni Lambda o altre architetture basate sugli eventi. I risultati vengono pubblicati nelle destinazioni solo quando la query viene eseguita correttamente. Le destinazioni delle tabelle di ricerca sono ottimizzate per mantenere aggiornati i dati di riferimento. Una destinazione della tabella di ricerca popola o aggiorna automaticamente la tabella di ricerca specificata con i risultati della query a ogni esecuzione pianificata, in modo che altre query possano fare riferimento ai dati più recenti con il comando. lookup

Formato e struttura dei risultati delle query

Le query pianificate forniscono risultati in formato JSON, ma ogni tipo di destinazione riceve un payload diverso. Per una destinazione per una tabella di ricerca, i risultati della query diventano il contenuto della tabella di ricerca e ogni esecuzione sostituisce tale contenuto. Per ulteriori informazioni, consulta Configurazione delle destinazioni delle tabelle di ricerca per le interrogazioni pianificate.

Le destinazioni Amazon S3 ricevono le righe dei risultati della query. Ogni oggetto contiene un array JSON con una voce per ogni riga del set di risultati e ogni voce associa i nomi dei campi di output della query ai rispettivi valori. L'oggetto non contiene metadati o statistiche di interrogazione e omette il @ptr campo anche se la query lo richiede, poiché tale campo è utilizzabile solo nella console.

EventBridge le destinazioni ricevono i metadati delle query, incluse le statistiche delle query, ma nessuna riga dei risultati. Per recuperare le righe di una query completata, chiama GetQueryResults con il valore di queryId from the event.

L'esempio seguente mostra l'evento in cui CloudWatch Logs viene pubblicato EventBridge quando viene completata una query pianificata.

{
    "version": "0",
    "id": "be72061b-eca2-e068-a7e1-83e01d6fe807",
    "detail-type": "Scheduled Query Completed",
    "source": "aws.logs",
    "account": "123456789012",
    "time": "2025-11-18T11:31:48Z",
    "region": "us-east-1",
    "resources": [
        "arn:aws:logs:us-east-1:123456789012:scheduled-query:477b4380-b098-474e-9c5e-e10a8cc2e6e7"
    ],
    "detail": {
        "queryId": "2038fd57-ab4f-4018-bb2f-61d363f4a004",
        "queryString": "fields @timestamp, @message, @logStream\n| filter @message like /ERROR/\n| sort @timestamp desc\n| limit 10000",
        "logGroupIdentifiers": [
            "/aws/lambda/my-function"
        ],
        "status": "Complete",
        "startTime": 1763465460,
        "statistics": {
            "recordsMatched": 1842,
            "recordsScanned": 48325,
            "estimatedRecordsSkipped": 0,
            "bytesScanned": 12081250,
            "estimatedBytesSkipped": 0,
            "logGroupsScanned": 1,
            "resultCount": 1842
        }
    }
}

Questa query non viene aggregata e ha restituito un numero di righe inferiore a 10.000, quindi ognuno limit dei 1.842 eventi di log corrispondenti è diventato una riga di output ed è uguale. recordsMatched resultCount Una query che aggrega, o una il cui set di risultati è troncato da, produce un valore inferiore a. limit resultCount recordsMatched Per ulteriori informazioni, consulta Informazioni su RecordsScanned, RecordsMatched e ResultCount.

Gli elementi chiave includono:

La tabella seguente descrive ogni campo dell'statisticsoggetto. Per le definizioni API di questi campi, consulta QueryStatistics.

Informazioni su RecordsScanned, RecordsMatched e ResultCount

Tre delle statistiche delle query contano cose diverse e confrontarle direttamente può essere fuorviante. Ognuna misura una diversa fase di elaborazione delle query:

Ogni fase restringe i dati. Un comando come quello stats combina molti eventi di registro in un'unica riga di output, quindi resultCount può essere molto più piccolo direcordsMatched. Un valore grande recordsMatched con un valore piccolo non resultCount significa che nel set di risultati manchino delle righe.

Esempio: aggregazione

La seguente query conta i messaggi di errore in ogni flusso di log di un gruppo di log in un periodo di un'ora.

filter @message like /ERROR/
| stats count(*) as errorCount by @logStream

Se la query legge 1.500.000 eventi di registro, 24.318 dei quali contengono ERROR e gli eventi di registro corrispondenti provengono da 12 flussi di log, la query viene completata con le seguenti statistiche.

"statistics": {
    "recordsMatched": 24318,
    "recordsScanned": 1500000,
    "estimatedRecordsSkipped": 0,
    "bytesScanned": 450000000,
    "estimatedBytesSkipped": 0,
    "logGroupsScanned": 1,
    "resultCount": 12
}

statsproduce una riga per ogni flusso di log, quindi resultCount è 12 mentre è 24.318. recordsMatched La somma dei 12 valori di è errorCount 24.318.

Esempio: filtro Post-aggregation

La seguente query mantiene solo i flussi di log che hanno prodotto più di 1.000 errori.

filter @message like /ERROR/
| stats count(*) as errorCount by @logStream
| filter errorCount > 1000

L'ultimo filter comando viene eseguito dopo il raggruppamento, quindi rimuove le righe dal set di risultati anziché registrare gli eventi dalla scansione. Se 3 dei 12 flussi di log hanno un valore errorCount superiore a 1.000, allora resultCount è 3 anziché 12. recordsScannede bytesScanned non modificate, perché la query legge gli stessi dati di registro in entrambi i casi.

Esempio: limite

Un limit comando riduce resultCount senza alcuna aggregazione. La seguente query restituisce i 100 messaggi di errore più recenti.

filter @message like /ERROR/
| sort @timestamp desc
| limit 100

Se la query analizza gli stessi 1.500.000 eventi di registro e corrisponde agli stessi 24.318, allora resultCount è 100, perché limita il set di risultati limit a 100 righe. Nella console, questa relazione viene visualizzata come Visualizzazione della corrispondenza di 100 record su 24.318.

Ogni statistica risponde a una domanda diversa.