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.
# Requête ProMAL
Lorsque vous ingérez OpenTelemetry des métriques CloudWatch via le[Point final des métriques](CloudWatch-OTLPEndpoint.md#CloudWatch-MetricsEndpoint), le modèle de données OTLP hiérarchique est aplati en étiquettes. PromQL-compatible Cette section décrit la structure des étiquettes, la syntaxe ProMQL pour interroger ces étiquettes et la prise en UTF-8 charge dans ProMQL.
**Note**
Dans Prometheus 3, Promql prend en charge les UTF-8 caractères complets dans les noms métriques et les noms d'étiquettes. Cela est particulièrement important pour les métriques OTLP, car les conventions OpenTelemetry sémantiques utilisent des points dans les noms d'attributs tels que. `service.name` Auparavant, ces points étaient remplacés par des traits de soulignement lors de la traduction, ce qui provoquait des divergences entre ce qui était défini dans les conventions OTel et ce qui était interrogeable dans Prometheus.
Lorsque vous utilisez ProMQL dans CloudWatch, la convention de `@` préfixe distingue les étiquettes des OTLP-scoped étiquettes Prometheus standard. Les champs de chaque étendue utilisent un `@` préfixe à double portée (par exemple,`@resource.@schema_url`), tandis que les attributs utilisent un préfixe à `@` portée unique, par exemple,. `@resource.service.name` Les attributs de point de données prennent également en charge l'accès nu (non préfixé) pour une compatibilité descendante avec les requêtes ProMQL standard, par exemple, et sont équivalents. `{"http.server.active_requests"}` `{"@datapoint.@name"="http.server.active_requests"}`
Une expression ProMQL est placée entre accolades, spécifiant le nom de la métrique et un ensemble facultatif de correspondants d'étiquettes. L'exemple suivant sélectionne toutes les séries chronologiques pour la `http.server.active_requests` métrique :
```
{"http.server.active_requests"}
```
L'exemple suivant sélectionne toutes les séries chronologiques pour la métrique `http.server.active_requests` dont l'attribut de OpenTelemetry ressource `service.name` est égal à `myservice` :
```
{"http.server.active_requests", "@resource.service.name"="myservice"}
```
Vous pouvez combiner plusieurs correcteurs d'étiquettes dans une seule requête. L'exemple suivant sélectionne toutes les séries chronologiques pour la `http.server.active_requests` métrique dont l'attribut de OpenTelemetry ressource `service.name` est égal `myservice` dans toutes les régions des États-Unis :
```
{"http.server.active_requests",
"@resource.service.name"="myservice",
"@aws.region"=~"us-.*"}
```
L'exemple suivant montre une requête de plage. Il calcule la valeur moyenne de tous les points de données dans une plage de temps spécifiée pour chaque série chronologique :
```
avg_over_time(
{"http.server.active_requests",
"@resource.service.name"="myservice"}[5m]
)
```
Le tableau suivant récapitule les conventions de préfixes pour chaque étendue OTLP :
| Champ d'application OTLP | Préfixe des champs | Préfixe d'attributs | Exemple |
| --- | --- | --- | --- |
| Ressource | `@resource.@` | `@resource.` | `@resource.service.name="myservice"` |
| Champ d'instrumentation | `@instrumentation.@` | `@instrumentation.` | `@instrumentation.@name="otel-go/metrics"` |
| Point de données | `@datapoint.@` | `@datapoint.`ou nu | `cpu="cpu0"` ou `@datapoint.cpu="cpu0"` |
| AWS-réservé | N/A | `@aws.` | `@aws.account_id="123456789"` |
## Interrogation de vended AWS métriques avec ProMQL
Pour pouvoir interroger les AWS métriques vendues dans ProMQL, vous devez d'abord activer l'enrichissement OTel des métriques vendues. Voir : [AWS métriques vendues au format OpenTelemetry](CloudWatch-OTelEnrichment.md).
Une fois que vous avez activé l'enrichissement par OTel, AWS les métriques vendues peuvent être consultées via ProMQL avec des étiquettes supplémentaires. Le nom de la métrique est identique au nom de la CloudWatch métrique d'origine, et les CloudWatch dimensions d'origine sont disponibles sous forme d'attributs de point de données. Les libellés suivants sont disponibles (l'exemple ci-dessous concerne une instance EC2) :
| Étiquette ProMQL | Description | Exemple |
| --- | --- | --- |
| `InstanceId` | CloudWatch Dimension d'origine, sous forme d'attribut de point de données | `i-0123456789abcdef0` |
| `"@resource.cloud.resource_id"` | ARN complet de la ressource | `arn:aws:ec2:us-east-1:123456789012:instance/i-0123456789abcdef0` |
| `"@resource.cloud.provider"` | Fournisseur de cloud | `aws` |
| `"@resource.cloud.region"` | AWS Région d'origine de cette métrique | `us-east-1` |
| `"@resource.cloud.account.id"` | AWS ID de compte d'où provient cette métrique | `123456789012` |
| `"@instrumentation.@name"` | Nom du champ d'application de l'instrumentation identifiant le service source | `cloudwatch.aws/ec2` |
| `"@instrumentation.cloudwatch.source"` | Identifiant du service source | `aws.ec2` |
| `"@instrumentation.cloudwatch.solution"` | Identifiant de la solution d'enrichissement | `CloudWatchOTelEnrichment` |
| `"@aws.tag.Environment"` | AWS balise de ressource | `production` |
| `"@aws.account"` | AWS compte où cette métrique a été ingérée (étiquette du système) | `123456789012` |
| `"@aws.region"` | AWS Région où cette métrique a été ingérée (étiquette du système) | `us-east-1` |
L'exemple suivant sélectionne `Invocations` une fonction Lambda spécifique :
```
{Invocations, FunctionName="my-api-handler"}
```
L'exemple suivant sélectionne Lambda `Errors` pour toutes les fonctions associées à une équipe spécifique :
```
{Errors, "@instrumentation.@name"="cloudwatch.aws/lambda", "@aws.tag.Team"="backend"}
```
L'exemple suivant calcule le nombre total de `Invocations` Lambda groupé par équipe :
```
sum by ("@aws.tag.Team")(
{Invocations, "@instrumentation.@name"="cloudwatch.aws/lambda"}
)
```
L'exemple suivant sélectionne toutes les séries chronologiques pour la `CPUUtilization` métrique EC2. L'utilisation de `"@instrumentation.@name"="cloudwatch.aws/ec2"` est destinée à correspondre exclusivement à CPUUtilization d'EC2 et non à celle d'autres AWS services tels qu'Amazon Relational Database Service :
```
histogram_avg({CPUUtilization, "@instrumentation.@name"="cloudwatch.aws/ec2"})
```
## Interrogation depuis Grafana
Vous pouvez interroger les données CloudWatch ProMQL depuis Grafana en ajoutant le plugin de source de données **Amazon Managed Service for Prometheus et en le pointant vers le point** de terminaison de surveillance. CloudWatch La signature SigV4 est intégrée au plugin et est toujours activée, il n'y a donc pas de bouton à activer. Le plugin est publié sur [grafana. com/grafana/plugins/grafana-amazonprometheus-datasource/](https://grafana.com/grafana/plugins/grafana-amazonprometheus-datasource/) ; installez-le depuis le catalogue des plugins Grafana avant d'ajouter la source de données. Le plugin AMP v3.0.0 nécessite Grafana. `>=11.6.11 <12 || >=12.0.10 <12.1 || >=12.1.7 <12.2 || >=12.2.5`
**Conditions requises pour l'IAM** : le principal IAM dont Grafana utilise les informations d'identification doivent avoir à la fois `cloudwatch:GetMetricData` (requis pour les requêtes instantanées et par plage) et `cloudwatch:ListMetrics` (requis pour la découverte de séries et d'étiquettes). Pour en savoir plus, consultez [Autorisations IAM pour ProMQL](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM).
Pour configurer Grafana, procédez comme suit.
1. Installez le plug-in de source de données **Amazon Managed Service for Prometheus** à partir du catalogue de plugins Grafana.
1. Dans Grafana, accédez à **Connexions**, **Sources de données**, choisissez **Ajouter une source de données, puis** sélectionnez **Amazon Managed Service for Prometheus**.
1. Définissez l'**URL** de la source de données sur`https://monitoring.{{AWS Region}}.amazonaws.com`.
1. Définissez votre **région** comme étant AWS la vôtre. Choisissez un **fournisseur d'authentification** adapté à votre environnement (chaîne d'informations d'identification par défaut, clés d'accès ou rôle IAM dans l'espace de travail).
1. Choisissez **Enregistrer et tester**.
## Effectuer des requêtes depuis Amazon Managed Grafana
Vous pouvez interroger les données CloudWatch ProMQL depuis un espace de travail Amazon Managed Grafana en ajoutant une source de données **Amazon Managed Service for Prometheus pointant vers le point de terminaison de surveillance**. CloudWatch Ce plugin de source de données signe automatiquement les demandes avec SigV4 en utilisant le rôle IAM de l'espace de travail ; SigV4 est toujours activé, sans qu'il soit nécessaire de le configurer. Le plugin est disponible dans les versions 12 et ultérieures d'Amazon Managed Grafana. Pour plus d'informations, consultez la section [Connect to an Amazon Managed Service for Prometheus source de données](https://docs.aws.amazon.com/grafana/latest/userguide/amazon-prometheus-data-source.html) dans le guide de l'utilisateur d'*Amazon Managed Grafana*.
**Conditions requises pour l'IAM** : le rôle IAM de l'espace de travail Amazon Managed Grafana doit avoir à la fois `cloudwatch:GetMetricData` (obligatoire pour les requêtes instantanées et par plage) et `cloudwatch:ListMetrics` (obligatoire pour la découverte de séries et d'étiquettes). Pour en savoir plus, consultez [Autorisations IAM pour ProMQL](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM).
Pour configurer la source de données, procédez comme suit.
1. Dans votre espace de travail Amazon Managed Grafana, ajoutez une source de données **Amazon Managed Service for Prometheus**.
1. Définissez l'**URL** de la source de données sur`https://monitoring.{{AWS Region}}.amazonaws.com`.
1. Définissez votre **région** comme étant AWS la vôtre. Amazon Managed Grafana injecte automatiquement les informations d'identification depuis le rôle IAM de l'espace de travail ; vous n'avez pas besoin de configurer de clés statiques.
1. Choisissez **Enregistrer et tester**.
## Interrogation avec les outils MCP
Le [serveur CloudWatch MCP](https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server/) fournit des outils MCP (Model Context Protocol) qui permettent aux assistants d'intelligence artificielle et aux outils de développement d'interroger les données CloudWatch ProMQL en votre nom. Les outils MCP gèrent automatiquement l'authentification et le formatage des demandes. Vous pouvez donc vous concentrer sur l'écriture de requêtes ProMQL plutôt que sur la gestion des requêtes HTTP et de la signature SigV4.
Les outils ProMQL suivants sont disponibles sur le serveur CloudWatch MCP :
| Outil | Description |
| --- | --- |
| `execute_promql_query` | Exécute une requête ProMQL instantanée, renvoyant des valeurs métriques à un moment donné. |
| `execute_promql_range_query` | Exécute une requête de plage ProMQL sur une fenêtre temporelle, renvoyant des données de séries chronologiques pour l'analyse des tendances et la création de graphiques. |
| `get_promql_label_values` | Récupère les valeurs d'une étiquette ProMQL spécifique, par exemple pour les noms de métriques ou `__name__` `@resource.service.name` pour les services. |
| `get_promql_series` | Recherche les séries chronologiques correspondant aux sélecteurs d'étiquettes ProMQL et renvoie le jeu d'étiquettes complet de chaque série correspondante. |
| `get_promql_labels` | Répertorie tous les noms d'étiquettes ProMQL disponibles pour vous aider à découvrir la structure des étiquettes de vos métriques. |
Pour plus de détails sur les paramètres, la configuration et les instructions de configuration, consultez la section [Outils pour CloudWatch ProMQL](https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server#tools-for-cloudwatch-promql) dans la documentation du serveur CloudWatch MCP.
## Interrogation avec l'API HTTP
Vous pouvez également interroger les données CloudWatch ProMQL par programmation en appelant directement les points de terminaison HTTP. Prometheus-compatible Les demandes doivent être signées avec [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) en utilisant `monitoring` comme nom de service.
Le point de terminaison ProMQL suit le modèle. `https://monitoring.{{AWS Region}}.amazonaws.com/api/v1/{{operation}}` Par exemple, pour la région USA Est (Virginie du Nord) (us-east-1), le point de terminaison d'une requête instantanée est. `https://monitoring.us-east-1.amazonaws.com/api/v1/query`
Pour la référence complète de l'API, y compris les opérations prises en charge, les paramètres de demande et les formats de réponse, consultez[Prometheus-compatible API](CloudWatch-PromQL-APIs.md). Pour la liste des AWS régions dans lesquelles les requêtes ProMQL sont disponibles, consultez. [Pris en charge AWS Régions](CloudWatch-PromQL.md#CloudWatch-PromQL-Regions) Pour connaître les actions IAM requises pour chaque opération, consultez[Autorisations IAM pour ProMQL](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM).