Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Comprendre les concepts de requêtes planifiées

Avant de créer des requêtes planifiées, comprenez ces concepts clés qui influent sur la façon dont vos requêtes sont exécutées et sur la destination des résultats.

Séparation des rôles IAM

Les requêtes planifiées nécessitent deux rôles IAM distincts : l'un pour l'exécution des requêtes et l'autre pour la diffusion des résultats vers des destinations telles que les compartiments Amazon S3, les bus d' EventBridge événements Amazon ou les tables de recherche. Comprendre pourquoi cette séparation existe vous permet de configurer correctement les autorisations et de tirer parti des avantages opérationnels et de sécurité qu'elle offre.

L'architecture à deux rôles répartit les responsabilités entre l'accès et la fourniture des données. Le rôle d'exécution des requêtes accède aux données de votre journal et exécute des requêtes, tandis que le rôle de diffusion de destination écrit les résultats vers la destination que vous avez choisie. Cette séparation suit le principe du moindre privilège : chaque rôle ne dispose que des autorisations dont il a besoin pour sa fonction spécifique.

Cette séparation présente des avantages pratiques pour vos opérations. Du point de vue de la sécurité, si vous devez modifier l'endroit où les résultats sont fournis, vous ne modifiez que le rôle de diffusion de destination sans modifier les autorisations d'exécution des requêtes. À des fins de conformité et d'audit, vous pouvez clairement déterminer quel rôle accède aux données de journal sensibles et quel rôle écrit sur des systèmes externes. Cela permet de démontrer plus facilement que votre infrastructure d'analyse des journaux respecte les meilleures pratiques de sécurité.

Cross-region et utilisation entre comptes

Une requête planifiée est créée dans une région spécifique et s'exécute dans cette région. Vous pouvez toutefois interroger des groupes de journaux et fournir des résultats pour toutes les régions et tous les comptes. Vous devez configurer un ou plusieurs AWS comptes en tant que comptes de surveillance et les associer à plusieurs comptes sources. Un compte de surveillance est un AWS compte central qui peut consulter et interagir avec les données d'observabilité générées à partir des comptes sources. Un compte source est un AWS compte individuel qui génère des données d'observabilité pour les ressources qui y résident. Les comptes sources partagent leurs données d'observabilité avec le compte de surveillance. Vous pouvez donc configurer des requêtes planifiées à partir du compte de surveillance en utilisant les groupes de journaux de tous les comptes liés.

Autre approche : utilisez la centralisation CloudWatch des journaux pour répliquer les données des journaux de plusieurs comptes et régions vers un compte de surveillance central. Cela vous permet de créer des requêtes planifiées dans une seule région qui accèdent à tous vos journaux centralisés, évitant ainsi les requêtes interrégionales et simplifiant la gestion des autorisations IAM.

Expressions de planification et gestion des fuseaux horaires

Le calendrier que vous définissez détermine le moment et la fréquence d'exécution de votre requête. Le choix de l'expression de planification appropriée influe sur le moment où vous recevez les résultats et sur la quantité de données que vous interrogez. Comprendre les types d'expressions vous aide à choisir entre simplicité et précision.

Les expressions Cron fournissent un contrôle précis du calendrier, vous permettant de spécifier des heures, des jours de la semaine ou des jours du mois exacts. Utilisez des expressions cron lorsque vous devez exécuter des requêtes à des heures ouvrées spécifiques ou pour les aligner sur les plannings opérationnels. Dans la console, vous pouvez également planifier des requêtes à l'aide d'options de calendrier simples.

Toutes les requêtes planifiées sont exécutées en UTC, quel que soit votre fuseau horaire local ou l'emplacement de vos AWS ressources. Cela est particulièrement important lorsque vous planifiez des requêtes pendant les heures ouvrables ou lorsque vous effectuez des analyses urgentes. Par exemple, si votre entreprise opère à l'heure de l'Est des États-Unis et que vous souhaitez un rapport quotidien à 9 h 00 ET, vous devez tenir compte du décalage UTC (14 h UTC pendant l'heure d'été, 13 h UTC sinon). Planifiez vos expressions de planification en tenant compte de l'UTC pour vous assurer que les requêtes sont exécutées aux heures prévues.

Choix d'un langage de requête

Les requêtes planifiées prennent en charge trois langages de requête différents, et votre choix influe à la fois sur la façon dont vous rédigez les requêtes et sur la facilité avec laquelle votre équipe peut les gérer. Le langage approprié dépend de vos exigences en matière d'analyse et des compétences existantes de votre équipe.

Si vous filtrez et agrégez principalement les données des CloudWatch journaux, le langage de requête Logs Insights propose la syntaxe la plus simple. Pour les transformations de données complexes nécessitant de les remodeler ou de les enrichir en plusieurs étapes, l'approche pipeline de PPL facilite la mise en œuvre de la logique. Lorsque vous devez effectuer des jointures ou des agrégations complexes similaires à des opérations de base de données, SQL fournit une syntaxe familière que les équipes expérimentées peuvent adopter rapidement.

Sélection de destinations et cas d'utilisation

L'endroit où vous envoyez les résultats des requêtes détermine ce que vous pouvez en faire. Ce choix façonne l'ensemble de votre flux de travail en aval, qu'il s'agisse de créer des analyses à long terme, de déclencher des réponses automatisées, ou les deux. Comprendre les points forts de chaque type de destination vous permet de concevoir l'architecture adaptée à votre cas d'utilisation.

Les destinations Amazon S3 sont optimisées pour le stockage et le traitement par lots. Lorsque vous devez conserver les résultats de requêtes pendant des mois ou des années, analyser les tendances au fil du temps ou alimenter des plateformes d'analyse en données, Amazon S3 fournit un stockage rentable avec une rétention illimitée. EventBridge les destinations sont optimisées pour une automatisation en temps réel. Lorsque les résultats des requêtes doivent déclencher des actions immédiates, comme l'envoi d'alertes, le démarrage de flux de travail ou la mise à jour de systèmes, EventBridge les résultats sont fournis sous forme d'événements auxquels vos applications peuvent répondre instantanément. Par défaut, tous les événements de fin de requête sont automatiquement envoyés sous forme d'événements au bus d'événements par défaut, ce qui permet l'intégration avec les systèmes de traitement en aval, les fonctions Lambda ou d'autres architectures pilotées par les événements. Les résultats ne sont publiés vers les destinations que lorsque la requête est exécutée avec succès. Les destinations des tables de recherche sont optimisées pour maintenir les données de référence à jour. Une destination de table de recherche remplit ou actualise automatiquement la table de recherche spécifiée avec les résultats de la requête à chaque exécution planifiée, afin que d'autres requêtes puissent référencer les données les plus récentes à l'aide de la lookup commande.

Format et structure des résultats de requête

Les requêtes planifiées fournissent des résultats au format JSON, mais chaque type de destination reçoit une charge utile différente. Pour une destination de table de recherche, les résultats de la requête deviennent le contenu de la table de recherche, et chaque exécution remplace ce contenu. Pour de plus amples informations, veuillez consulter Configuration des destinations des tables de recherche pour les requêtes planifiées.

Les destinations Amazon S3 reçoivent les lignes de résultats de la requête. Chaque objet contient un tableau JSON avec une entrée pour chaque ligne du jeu de résultats, et chaque entrée associe les noms des champs de sortie de la requête à leurs valeurs. L'objet ne contient pas de métadonnées de requête ni de statistiques de requête, et il omet le @ptr champ même si la requête le demande, car ce champ n'est utilisable que dans la console.

EventBridge les destinations reçoivent les métadonnées de la requête, y compris les statistiques de la requête, mais aucune ligne de résultat. Pour récupérer les lignes d'une requête terminée, appelez GetQueryResults avec la valeur de queryId from the event.

L'exemple suivant montre l'événement que CloudWatch Logs publie EventBridge lorsqu'une requête planifiée est terminée.

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

Cette requête n'est pas agrégée et elle a renvoyé moins limit de lignes que ses 10 000. Ainsi, chacun des 1 842 événements de journal correspondants est devenu une ligne de sortie recordsMatched et resultCount sont égaux. Une requête qui regroupe, ou dont le jeu de résultats est tronqué parlimit, produit une resultCount valeur inférieure à. recordsMatched Pour de plus amples informations, veuillez consulter Comprendre RecordsScanné, RecordsMatched et ResultCount.

Les principaux éléments sont les suivants :

Le tableau suivant décrit chaque champ de l'statisticsobjet. Pour les définitions d'API de ces champs, consultez QueryStatistics.

Comprendre RecordsScanné, RecordsMatched et ResultCount

Trois des statistiques de requête prennent en compte des éléments différents, et les comparer directement peut être trompeur. Chacune mesure une étape différente du traitement des requêtes :

Chaque étape permet de réduire les données. Une commande telle que stats combine de nombreux événements de journal en une seule ligne de sortie, elle resultCount peut donc être beaucoup plus petite querecordsMatched. Un grand recordsMatched avec un petit resultCount ne signifie pas que des lignes sont absentes du jeu de résultats.

Exemple — Agrégation

La requête suivante compte les messages d'erreur dans chaque flux de journaux d'un groupe de journaux sur une période d'une heure.

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

Si la requête lit 1 500 000 événements de journal, 24 318 d'entre eux en contiennent ERROR et que les événements de journal correspondants proviennent de 12 flux de journaux, la requête se termine avec les statistiques suivantes.

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

statsproduit une ligne pour chaque flux de log, soit 12 alors resultCount que recordsMatched c'est 24 318. Les 12 valeurs de errorCount totalisent 24 318.

Exemple — Post-aggregation filtre

La requête suivante ne conserve que les flux de journaux qui ont généré plus de 1 000 erreurs.

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

La dernière filter commande s'exécute après le regroupement. Elle supprime donc les lignes du jeu de résultats au lieu de consigner les événements de l'analyse. Si 3 des 12 flux de log ont un nombre errorCount supérieur à 1 000, alors resultCount c'est 3 au lieu de 12. recordsScannedet bytesScanned ne les modifiez pas, car la requête lit les mêmes données de journal dans les deux cas.

Exemple — Limite

Une limit commande réduit resultCount sans aucune agrégation. La requête suivante renvoie les 100 derniers messages d'erreur.

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

Si la requête analyse les mêmes 1 500 000 événements de journal et correspond aux mêmes 24 318, elle vaut 100, car le résultat resultCount est limit plafonné à 100 lignes. Dans la console, vous pouvez voir cette relation comme «  Afficher 100 des 24 318 enregistrements correspondants ».

Chaque statistique répond à une question différente.