Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Créer et gérer des variables et des filtres épinglés

Les filtres et variables épinglés sur un tableau de bord personnalisé dans Cloud Monitoring vous permettent de modifier de manière dynamique les données affichées dans votre tableau de bord à partir de la barre d'outils, sans modifier les widgets individuels. Les filtres épinglés s'appliquent à tous les widgets compatibles avec l'étiquette du filtre, tandis que les variables s'appliquent à des widgets spécifiques pour modifier leurs requêtes ou contrôler leur visibilité.

Ce document explique comment configurer des filtres et des variables épinglés dans la consoleGoogle Cloud . Pour les configurer à l'aide de l'API Cloud Monitoring, consultez Créer et gérer des tableaux de bord par API : filtres de tableau de bord. Pour appliquer des filtres ou des regroupements uniquement à votre session en cours, consultez Ajouter des filtres temporaires à un tableau de bord personnalisé.

À propos des filtres épinglés

Un filtre épinglé contient un libellé, une ou plusieurs valeurs par défaut et une liste de toutes les valeurs possibles. La liste de toutes les valeurs possibles est dérivée de manière dynamique des données de séries temporelles affichées sur votre tableau de bord.

Vous n'appliquez pas de filtre épinglé à des widgets individuels. À la place, les règles suivantes sont utilisées pour déterminer si le filtre épinglé peut modifier les données affichées par le widget :

Si le widget affiche des données qui incluent la clé d'étiquette spécifiée par un filtre épinglé et s'il ne spécifie pas de valeur pour cette clé d'étiquette, le filtre épinglé peut modifier les données affichées.

Par exemple, supposons que vous ajoutiez le filtre épinglé cluster_name: mycluster. Les graphiques n'affichent alors automatiquement que les séries temporelles qui ont une étiquette cluster_name avec la valeur mycluster. De même, les requêtes sur les widgets du panneau de journaux sont modifiées en resource.labels."cluster_name"="mycluster", et vos graphiques n'affichent automatiquement que les séries temporelles qui incluent l'étiquette dans le filtre épinglé.
Un filtre épinglé est ignoré par un widget lorsque celui-ci inclut un filtre pour la même clé d'étiquette, ou lorsque les données affichées par le widget ne contiennent pas la clé d'étiquette spécifiée dans le filtre épinglé.

Dans l'API, les filtres épinglés sont définis par la structure DashboardFilter. Par exemple, la structure suivante définit un filtre épinglé. Les séries temporelles associées à une étiquette zone dont la valeur est us-central1-c correspondent au filtre épinglé.

{
   "labelKey": "zone",
   "stringValue": "us-central1-c",
   "valueType": "STRING",
   "filterType": "RESOURCE_LABEL"
},

À propos des variables

Comme les filtres épinglés, une variable possède un nom, un type et une ou plusieurs valeurs par défaut. Toutefois, contrairement aux filtres épinglés qui sont toujours basés sur des étiquettes, les variables ne dépendent pas nécessairement d'étiquettes.

Une variable est appliquée à un widget particulier en modifiant la requête qu'il contient.

Dans la barre d'outils du tableau de bord, les noms des variables sont précédés d'un signe dollar $. Si vous voyez également une icône Visible, cela signifie que la variable contrôle la visibilité d'au moins un widget.

Les variables définies par l'utilisateur peuvent être basées sur des étiquettes ou n'avoir qu'une valeur :

Les variables basées sur des étiquettes sont semblables à des filtres épinglés. Ces variables contiennent une clé d'étiquette, une ou plusieurs valeurs d'étiquette par défaut et une liste de toutes les valeurs d'étiquette possibles. La liste de toutes les valeurs possibles est dérivée de manière dynamique des données de séries temporelles affichées sur votre tableau de bord.
Les variables de valeur uniquement contiennent une ou plusieurs valeurs par défaut, et peuvent lister toutes les valeurs possibles. Si vous ne spécifiez pas de valeur par défaut, l'opérateur générique (*) est sélectionné pour la valeur par défaut. Pour définir l'ensemble de toutes les valeurs possibles, vous devez fournir un tableau de valeurs ou écrire une requête SQL.

Il existe trois types de variables de type "Valeur uniquement" : Personnalisée, Saisie de texte et Requête SQL.
- Personnalisé : à utiliser lorsque vous souhaitez énumérer la liste de toutes les valeurs possibles et définir une ou plusieurs valeurs par défaut. Par exemple, vous pouvez définir la liste de toutes les valeurs possibles sur prod, staging, dev et définir la valeur par défaut sur prod.
- Saisie de texte : à utiliser lorsque vous ne connaissez pas toutes les valeurs possibles. Lorsque vous créez cette variable, vous pouvez spécifier une ou plusieurs valeurs. Toutefois, l'option de menu vous permet d'ajouter de nouvelles valeurs qui s'appliquent à votre session en cours.
- Requête SQL : utilisez cette option lorsque vous souhaitez générer la liste des valeurs possibles à l'aide d'une requête SQL. Ces variables sont destinées à être appliquées aux graphiques créés à l'aide d'Analyse de l'observabilité.
  
  Pour ces variables, assurez-vous que le résultat de la requête est une table comportant une colonne, que le type de données de cette colonne est une chaîne et que chaque ligne de la table contient une valeur de chaîne unique :
```
SELECT log_name
FROM `VIEW`
GROUP BY log_name
```
  La requête SQL ne peut pas dépendre d'une variable.

Il existe une variable définie par le système, @__project_id. Vous ne pouvez utiliser cette variable que dans la clause FROM pour les requêtes SQL. Pour savoir comment appliquer cette variable à une requête, consultez Graphiques avec des requêtes SQL.

Pour appliquer une variable à un widget, vous devez mettre à jour la requête émise par le widget ou modifier la visibilité du widget. Vous pouvez toujours modifier le widget pour mettre à jour sa requête. Toutefois, pour les variables basées sur des étiquettes et certains types de widgets, vous pouvez mettre à jour la requête en effectuant des sélections dans le menu. Pour contrôler la visibilité, vous devez modifier le widget. Pour en savoir plus, consultez les sections suivantes de ce document :

Mettre à jour la requête d'un widget
Définir la visibilité d'un widget

Dans l'API, les variables sont définies par la structure DashboardFilter. Par exemple, la structure suivante définit la variable my_zone_variable qui opère sur l'étiquette de ressource zone. Les séries temporelles qui ont une étiquette zone dont la valeur est us-central1-c correspondent à la variable.

{
   "labelKey": "zone",
   "stringValue": "us-central1-c",
   "templateVariable": "my_zone_variable",
   "valueType": "STRING",
   "filterType": "RESOURCE_LABEL",
},

Avant de commencer

Procédez comme suit pour le projet Google Cloud dans lequel vous souhaitez configurer des filtres et des variables épinglés :

Pour obtenir les autorisations nécessaires pour ajouter ou modifier des variables ou des filtres épinglés à l'aide de la console Google Cloud , demandez à votre administrateur de vous accorder le rôle IAM Éditeur Monitoring (roles/monitoring.editor) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Pour en savoir plus sur les rôles, consultez Contrôler les accès avec Identity and Access Management.

Créer et épingler un filtre

Pour créer et épingler un filtre qui s'applique à tous les widgets de tableau de bord compatibles avec les filtres, procédez comme suit :

Dans la console Google Cloud , accédez à la page Tableaux de bord :
Accéder à la page Tableaux de bord

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Monitoring.
Dans la barre d'outils de la console Google Cloud , sélectionnez votre projet Google Cloud . Pour les configurations App Hub, sélectionnez le projet hôte ou le projet de gestion App Hub.
Sélectionnez un tableau de bord, accédez à la barre d'outils du tableau de bord, puis cliquez sur Paramètres.
Dans la section Filtres, cliquez sur Ajouter un filtre.
Cliquez sur Libellé, puis sélectionnez un libellé. Par exemple, vous pouvez sélectionner zone.
Pour permettre aux utilisateurs de sélectionner plusieurs valeurs dans le menu des valeurs du filtre, sélectionnez Sélection multiple. Lorsque l'option Sélection multiple n'est pas activée, les utilisateurs ne peuvent sélectionner qu'une seule option dans le menu des valeurs.
Cliquez sur Valeur par défaut, puis sélectionnez la ou les valeurs par défaut du libellé. Pour faire correspondre toutes les valeurs, sélectionnez *.

Remarque : Lorsque les tableaux de bord contiennent des graphiques définis par PromQL, le menu des valeurs d'un filtre peut ne pas se charger ou ne pas contenir les valeurs correctes. Toutefois, vous pouvez saisir manuellement la valeur du filtre.

Une fois le filtre créé, il est ajouté à la barre d'outils de votre tableau de bord. Pour modifier temporairement la valeur du filtre, sélectionnez le filtre, puis faites votre choix dans le menu.
Cliquez sur OK, puis sur Appliquer.
Pour enregistrer votre tableau de bord modifié, cliquez sur Enregistrer dans la barre d'outils.

Créer une variable

Pour créer une variable qui s'applique à des widgets de tableau de bord spécifiques, procédez comme suit :

Dans la console Google Cloud , accédez à la page Tableaux de bord :
Accéder à la page Tableaux de bord

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Monitoring.
Dans la barre d'outils de la console Google Cloud , sélectionnez votre projet Google Cloud . Pour les configurations App Hub, sélectionnez le projet hôte ou le projet de gestion App Hub.
Sélectionnez un tableau de bord, accédez à la barre d'outils du tableau de bord, puis cliquez sur Paramètres.
Dans la section Variables, cliquez sur Ajouter une variable.
Sélectionnez le type de variable, puis complétez la boîte de dialogue.

Remarque : Pour permettre à un utilisateur de sélectionner plusieurs valeurs dans le menu des valeurs de la variable, sélectionnez Sélection multiple. Lorsque l'option Sélection multiple n'est pas activée, les utilisateurs ne peuvent sélectionner qu'une seule option dans le menu des valeurs.

Pour créer une variable basée sur un libellé, sélectionnez Libellé. Utilisez cette option lorsque vous souhaitez une variable comportant une clé et une valeur d'étiquette, et pouvant être utilisée comme un filtre épinglé. La liste de toutes les valeurs possibles est dérivée de manière dynamique des données de séries temporelles affichées sur votre tableau de bord. Le menu Appliquer aux graphiques vous permet de sélectionner les widgets dont la requête doit être modifiée par la variable. Vous pouvez également mettre à jour la requête en modifiant le widget.

Pour les variables de valeur uniquement, vous disposez des options suivantes :
- SQL : utilisez cette option lorsque vous souhaitez que les résultats d'une requête SQL génèrent la liste de toutes les valeurs possibles.
  
  Saisissez une ou plusieurs valeurs par défaut, puis saisissez une requête SQL qui génère la liste de toutes les valeurs possibles. Assurez-vous que le résultat de la requête est une table comportant une colonne, que le type de données de cette colonne est une chaîne et que chaque ligne de la table contient une valeur de chaîne unique.
- Personnalisé : utilisez cette option lorsque vous souhaitez spécifier à la fois la liste des valeurs possibles et une valeur par défaut. Par exemple, vous pouvez définir le champ Valeurs sur prod, staging, dev et la Valeur par défaut sur prod.
- Saisie de texte : utilisez cette option lorsque vous souhaitez spécifier une liste de valeurs appliquées par défaut.
Cliquez sur OK, puis sur Appliquer.
Pour enregistrer votre tableau de bord modifié, cliquez sur Enregistrer dans la barre d'outils.

Monitoring ajoute la variable à la barre d'outils du tableau de bord. Le nom dans la barre d'outils est un signe dollar $ suivi du nom de la variable. La barre d'outils contient un menu qui vous permet de modifier la valeur de la variable.
Facultatif : Déplacez votre variable de la barre d'outils du tableau de bord vers un widget du tableau de bord.

Vous pouvez ajouter un widget à votre tableau de bord pour modifier la valeur de votre variable. Si vous effectuez cette modification, la variable de la barre d'outils est supprimée. Toutefois, vous pouvez placer le widget qui contrôle la variable à côté des widgets qu'il affecte. Pour savoir comment effectuer cette modification, consultez Ajouter un widget pour gérer la valeur d'une variable.
Appliquez la variable aux widgets. Si vous mettez à jour la requête d'un widget, lorsque vous modifiez la valeur de la variable, la requête est modifiée et les données affichées par le widget sont modifiées. Vous pouvez également utiliser une variable pour contrôler la visibilité d'un widget. Pour en savoir plus, consultez les sections suivantes de ce document :
- Définir la visibilité d'un widget
- Mettre à jour la requête d'un widget

Étant donné que les variables s'appliquent à un sous-ensemble de widgets de tableau de bord, vous pouvez regrouper le contrôle de la variable et les widgets auxquels elle s'applique. Par exemple, vous pouvez créer un groupe réductible ou créer une section dans le tableau de bord pour le menu des variables et les widgets associés. Cette stratégie simplifie également la barre d'outils en supprimant les variables qui ne s'appliquent pas à tous les widgets.

Pour gérer la valeur d'une variable à l'aide d'un widget de tableau de bord, procédez comme suit :

Dans la console Google Cloud , accédez à la page Tableaux de bord :
Accéder à la page Tableaux de bord

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Monitoring.
Dans la barre d'outils de la console Google Cloud , sélectionnez votre projet Google Cloud . Pour les configurations App Hub, sélectionnez le projet hôte ou le projet de gestion App Hub.
Dans la boîte de dialogue Ajouter un widget, accédez à la section Mise en page, puis sélectionnez Variable.
Remplissez la boîte de dialogue, puis sélectionnez Enregistrer.

Le tableau de bord affiche un widget qui vous permet de sélectionner la valeur de votre variable. Vous pouvez déplacer ce widget dans un groupe réductible ou le repositionner d'une autre manière.
Pour enregistrer votre tableau de bord modifié, cliquez sur Enregistrer dans la barre d'outils.

Définir la visibilité d'un widget

Lorsqu'un widget interroge des données, vous pouvez utiliser une variable pour contrôler si le widget est visible sur un tableau de bord. Par exemple, supposons qu'un tableau de bord contienne des widgets qui affichent les données de vos systèmes de production et un autre ensemble de widgets qui affichent les données de vos systèmes de préproduction. Lors du débogage pendant le développement, vous ne souhaiterez peut-être afficher que les données de préproduction. En configurant la visibilité des widgets du tableau de bord avec une variable, vous pouvez basculer entre les données de production uniquement, les données de préproduction uniquement et toutes les données.

N'importe quel type de variable peut contrôler si un widget est visible ou masqué.

Pour configurer la visibilité d'un widget, procédez comme suit :

Dans la console Google Cloud , accédez à la page Tableaux de bord :
Accéder à la page Tableaux de bord

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Monitoring.
Sélectionnez un tableau de bord.
Accédez à la barre d'outils du widget dont vous souhaitez configurer la visibilité, puis cliquez sur Modifier.
Dans le volet Affichage, développez Visibilité du widget.
Sélectionnez une variable et remplissez les champs de la boîte de dialogue.

Remarque : La valeur du comparateur doit être définie sur une expression régulière.
Cliquez sur OK, puis sur Appliquer.
Pour enregistrer votre tableau de bord modifié, cliquez sur Enregistrer dans la barre d'outils.

Le tableau de bord est actualisé. Lorsqu'au moins un widget du tableau de bord est masqué en raison des contrôles de visibilité, le tableau de bord affiche une bannière. Pour afficher tous les widgets, cliquez sur Afficher tous les widgets.

Lorsque vous utilisez une variable pour contrôler la visibilité d'au moins un widget sur votre tableau de bord, dans la barre d'outils, le nom de la variable est annoté avec une icône Visible.

Limites

Les limites suivantes s'appliquent lors de la configuration de la visibilité d'un widget :

Les widgets d'organisation, tels que les widgets de groupe réductible, d'en-tête de section et de vue unique, sont toujours visibles.
Vous pouvez supprimer une variable référencée par les commandes de visibilité d'un widget. L'action variable-delete supprime également toute référence à la variable.
La création de variables n'est pas possible dans tous les tableaux de bord. Toutefois, si un tableau de bord contient des variables, vous pouvez les utiliser pour gérer la visibilité des widgets sur le tableau de bord.

Mettre à jour la requête d'un widget

Cette section explique comment inclure des variables dans la requête émise par le widget. Par conséquent, lorsque vous modifiez la valeur de la variable, la requête est modifiée, tout comme les données affichées par le widget :

Pour les graphiques qui utilisent des requêtes SQL ou PromQL, et pour les widgets du panneau de journaux, vous devez modifier le widget et la requête. Cette section explique comment effectuer ces modifications.
Pour les graphiques que vous avez configurés à l'aide de menus ou du mode de filtrage direct, Monitoring modifie la requête lorsque vous sélectionnez le widget à l'aide du menu Appliquer aux graphiques. Vous pouvez également modifier le widget, accéder au champ Filtre, puis sélectionner la variable.

Pour savoir comment mettre à jour la requête d'un widget avec une variable basée sur un libellé ou une variable basée uniquement sur une valeur, consultez les sections suivantes :

Syntaxe générale pour déréférencer une variable
Widgets du panneau des journaux
Graphiques avec des requêtes PromQL
Graphiques avec des requêtes SQL
Graphiques avec des requêtes de filtre Monitoring

Lorsque vous utilisez l'interface basée sur des menus pour créer un graphique affichant des données de séries temporelles, vos sélections sont converties en un filtre Monitoring.

Créer des filtres et des variables

Console

Pour savoir comment utiliser la console Google Cloud pour créer des filtres et des variables épinglés, consultez les documents suivants :

REST

Pour définir des filtres et des variables épinglés, utilisez la structure de données dashboardFilters.

Pour créer une variable, définissez la valeur du champ templateVariable sur le nom de la variable. Omettez ce champ ou définissez la valeur sur une chaîne vide lorsque vous souhaitez créer un filtre épinglé.
Pour créer un filtre épinglé ou une variable basée sur un libellé, vous devez spécifier le champ labelKey. Omettez ce champ si vous souhaitez une variable de valeur uniquement.
Définissez la valeur par défaut du filtre ou de la variable. La configuration de ce champ détermine si un utilisateur peut sélectionner exactement une option dans le menu de valeurs ou s'il peut sélectionner plusieurs valeurs.
Pour définir une seule valeur par défaut et limiter les utilisateurs à la sélection d'une seule option dans le menu des valeurs, définissez le champ valueType sur STRING et définissez également le champ stringValue :
```
"valueType": "STRING",
"stringValue": "my-default-value",
```
Pour définir au moins une valeur par défaut et permettre aux utilisateurs de sélectionner plusieurs options dans le menu des valeurs, définissez le champ valueType sur STRING_ARRAY et définissez également le champ stringArrayValue. Dans l'exemple suivant, il existe trois valeurs par défaut.
```
"valueType": "STRING_ARRAY",
"stringArrayValue": {
  "values": [ "a", "b", "c" ]
},
```
Remarque : Si vous ne spécifiez pas de valeur par défaut, l'opérateur générique (*) est sélectionné automatiquement. Si vous prévoyez d'utiliser la variable dans un panneau de journaux, vous devez utiliser l'expression régulière comme comparateur. Pour les requêtes SQL, vous devez utiliser une instruction IF. Pour en savoir plus, consultez Graphiques avec des requêtes SQL.
Facultatif : pour spécifier la liste de toutes les valeurs possibles d'une variable de valeur uniquement, définissez le champ stringArray ou le champ timeSeriesQuery. Si vous spécifiez une requête, il doit s'agir d'une requête d'analyse.

Remarque : Ne définissez pas les champs timeSeriesQuery ou stringArray lorsque vous créez un filtre épinglé ou une variable basée sur un libellé. L'ensemble de toutes les valeurs possibles est déterminé de manière dynamique.

Par exemple, considérons l'objet dashboardFilters suivant :

{
  "dashboardFilters": [
      {
        "labelKey": "zone"
        "stringValue": "us-central1-c",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL"
      },
      {
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL",
        "templateVariable": "my_label_based_variable"
      },
      {
        "filterType": "VALUE_ONLY",
        "templateVariable": "my_value_only_variable",
        timeSeriesQuery: {
          opsAnalyticsQuery: {
            sql: "
              SELECT log_name
              FROM `MY_TABLE`
              GROUP BY log_name
            ",
          }
        }
      }
    ],
  "displayName": "Illustrate Variables",
  ...
}

Le code JSON précédent définit un filtre épinglé et deux variables :

Le filtre épinglé comporte la clé d'étiquette zone, qui s'affiche dans la barre d'outils. Les champs valueType et stringValue spécifient la valeur par défaut unique. Pour en savoir plus, consultez la page de documentation de référence de l'API pour la structure de données dashboardFilters.
La variable basée sur des étiquettes porte le nom my_label_based_variable et sa clé d'étiquette est instance_id. La valeur par défaut de cette variable est définie sur un ID d'instance spécifique. Vous pouvez également configurer la valeur par défaut à l'aide d'un tableau. Dans la barre d'outils, le filtre s'affiche avec le nom my_label_based_variable.
La variable de valeur uniquement est nommée my_value_only_variable. Cette entrée ne spécifie pas de valeur par défaut. L'opérateur générique (*) est donc appliqué automatiquement. De plus, cette variable utilise une requête SQL pour générer la liste des valeurs possibles pour la variable.

Notez que l'objet dashboardFilters ne liste pas les widgets auxquels la variable s'applique. Au lieu de cela, vous mettez à jour la requête d'un widget pour qu'elle dépende d'une variable.

Syntaxe générale pour déréférencer une variable

Pour tous les widgets, à l'exception de ceux définis par SQL, utilisez la syntaxe suivante pour appliquer une variable à une requête :

Pour appliquer une variable basée sur une étiquette et faire en sorte que la clé et la valeur de l'étiquette soient résolues en une expression de filtre valide pour le langage de requête, utilisez ${my_label_based_variable}.
Pour n'appliquer que la valeur d'une variable basée sur un libellé, utilisez ${my_label_based_variable.value}. La comparaison doit utiliser une expression régulière.
Pour n'appliquer que la valeur d'une variable de valeur uniquement, utilisez ${my_value_only_variable}. Pour les variables de type "Valeur uniquement", n'incluez pas de clause .value. La comparaison doit utiliser une expression régulière.

Widgets du panneau des journaux

Pour appliquer une variable à un widget de panneau de journaux, mettez à jour le volet des requêtes. La syntaxe de ces widgets suit celle spécifiée dans la section Syntaxe générale.

Console

Par exemple, la requête suivante utilise une expression régulière pour comparer la valeur du champ jsonPayload.message à une valeur de chaîne qui inclut la valeur d'une variable basée sur un libellé :

jsonPayload.message=~"Connected to instance: ${my_label_based_variable.value}"

Prenons un autre exemple : une variable de valeur uniquement, value_only_severity_variable, et supposons que trois valeurs sont sélectionnées dans le menu des valeurs : ERROR, INFO et NOTICE. Ensuite, ajoutez ce qui suit au volet de requête de votre widget de panneau de journaux :

severity =~ "${value_only_severity_variable}"

Voici un exemple de formulaire affiché :

severity =~ "^(ERROR|INFO|NOTICE)$"

REST

Par exemple, le code JSON suivant montre comment mettre à jour la requête d'un widget de panneau de journaux avec une variable basée sur un libellé :

"logsPanel": {
  "filter": "${my_label_based_variable}",
  "resourceNames": [
    "projects/1234512345"
  ]
},

"logsPanel": {
  "filter": "resource.type=\"gce_instance\"\n
            resource.labels.project_id=~\"${my_label_based_variable.value}\"\n",
  "resourceNames": [
    "projects/012345"
  ]
}

Prenons un autre exemple : une variable de valeur uniquement, value_only_severity_variable, et supposons que trois valeurs sont sélectionnées dans le menu : ERROR, INFO et NOTICE. Ensuite, ajoutez ce qui suit au volet de requête de votre widget de panneau de journaux :

"logsPanel": {
  "filter": "severity =~ \"${value_only_severity_variable}\"\n",
  ...
}

Voici la requête telle qu'elle est exécutée par le widget du panneau des journaux :

severity =~ "^(ERROR|INFO|NOTICE)$"

Si vous avez configuré une requête pour le panneau des journaux, puis que vous sélectionnez le bouton pour ouvrir l'explorateur de journaux, les variables sont résolues avant l'ouverture de l'explorateur de journaux.

Le tableau suivant illustre la façon dont les exemples de variables sont résolus par le panneau des journaux. Comme indiqué précédemment, lorsque seule la valeur d'une variable est utilisée, vous devez utiliser une expression régulière comme opérateur de comparaison :

Syntaxe	Valeur sélectionnée	Expression du panneau des journaux résolue
`${my_label_based_variable}`	`12345`	`resource.labels."instance_id"="12345"` L'exemple de variable est basé sur l'étiquette de ressource `instance_id`.
`${my_label_based_variable}`	`*`	`""`
`${my_label_based_variable.value}` `${my_value_based_variable}`	`12345`	`12345`
`${my_label_based_variable.value}` `${my_value_based_variable}`	`*`	`.*`

Graphiques avec des requêtes PromQL

Pour mettre à jour un graphique comportant une requête PromQL afin qu'il dépende d'une variable basée sur des étiquettes, suivez les instructions de la section Syntaxe générale.

Console

Par exemple, la requête suivante repose sur la variable basée sur un libellé, my_label_based_variable, qui est résolue en une expression de filtre :

compute_googleapis_com:instance_cpu_utilization{
    monitored_resource="gce_instance", ${my_label_based_variable} }

Vous pouvez également modifier la requête pour résoudre uniquement la valeur d'une variable. L'exemple suivant utilise une expression régulière pour comparer la valeur d'une requête basée sur un libellé à instance_id :

compute_googleapis_com:instance_cpu_utilization{
    instance_id=~"${my_label_based_variable.value}"
}

Si vous avez une variable de valeur uniquement, omettez la clause .value. Par exemple, pour filtrer par zone à l'aide d'une variable de valeur uniquement, la requête inclurait un élément semblable à celui-ci :

zone=~"${my_value_only_variable}"

REST

Par exemple, le code JSON suivant illustre une requête qui s'appuie sur la variable basée sur un libellé, my_label_based_variable, qui est résolue en une expression de filtre :

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
      monitored_resource=\"gce_instance\",
      ${my_label_based_variable}
      }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
    monitored_resource=\"gce_instance\",
    instance_id=~\"${my_label_based_variable.value}\"
    }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

zone=~\"${my_value_only_variable}\"

Le tableau suivant illustre la façon dont les exemples de variables sont résolus par PromQL. Comme indiqué précédemment, lorsque seule la valeur d'une variable est utilisée, vous devez utiliser une expression régulière comme opérateur de comparaison :

Syntaxe	Valeur sélectionnée	Expression PromQL résolue
`${my_label_based_variable}`	`12345`	`instance_id == '12345'` L'exemple de variable est basé sur l'étiquette de ressource `instance_id`.
`${my_label_based_variable}`	`*`	`noop_filter=~".*"`
`${my_label_based_variable.value}` `${my_value_based_variable}`	`12345`	`12345`
`${my_label_based_variable.value}` `${my_value_based_variable}`	`*`	`.+`

Graphiques avec des requêtes SQL

Vous pouvez utiliser des variables à deux endroits dans vos requêtes SQL :

La clause FROM peut dépendre de la variable définie par le système nommée @__project_id, qui correspond à la valeur du projet sélectionné.
La clause WHERE peut dépendre de variables définies par l'utilisateur.

Mettre à jour la clause FROM pour qu'elle dépende d'une variable définie par le système

Si vous créez des modèles de tableau de bord et que ces modèles représentent les résultats de requêtes SQL, remplacez l'ID du projet dans votre requête par la variable @__project_id. Lorsque vous installez le modèle dans un projet, la variable est automatiquement remplacée par l'ID du projet. Vous n'avez pas besoin de modifier manuellement le widget et de mettre à jour la clause FROM.

L'exemple suivant illustre une clause FROM qui dépend de la variable définie par le système :

FROM `@__project_id.global._Default._Default`

La clause FROM ne peut pas dépendre de variables définies par l'utilisateur.

Mettre à jour la clause WHERE pour qu'elle dépende d'une variable définie par l'utilisateur

Cette section explique comment mettre à jour la clause WHERE d'un widget défini par SQL pour qu'elle dépende d'une variable définie par l'utilisateur. Pour toutes les variables, ajoutez le signe "@" au nom de la variable, par exemple : @variable_name. Pour les variables basées sur des étiquettes, ajoutez .value au nom de la variable, @my_label_based_variabe.value.

Pour les requêtes SQL, la substitution de variables repose sur BigQuery et est protégée contre les injections SQL. Pour en savoir plus, consultez Exécuter des requêtes paramétrées.

Console

Comme SQL n'interprète pas l'opérateur générique comme signifiant "toute valeur", nous vous recommandons de toujours utiliser une instruction IF lorsque vous utilisez des variables dans une requête SQL. L'exemple suivant illustre l'utilisation d'une variable de valeur uniquement dont le type de données est une chaîne :

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

Lorsque l'option de menu de la variable permet aux utilisateurs de sélectionner plusieurs valeurs, vous devez caster la valeur de la variable en un type de données GoogleSQL à l'aide de la fonction CAST. La requête suivante illustre cette syntaxe :

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

L'instruction IF présentée dans les exemples précédents est recommandée, car SQL n'interprète pas l'opérateur générique comme signifiant "toute valeur". Par conséquent, si vous omettez l'instruction IF et que vous sélectionnez l'opérateur générique, le résultat de la requête est une table vide. Dans le deuxième exemple, la fonction UNNEST convertit le tableau en table.

Pour ajouter une clause WHERE correctement formatée, procédez comme suit :

Modifiez le widget.
Dans la barre d'outils, sélectionnez Insérer un filtre de variable, puis sélectionnez la variable dont vous souhaitez mettre à jour la clause WHERE.
Dans la boîte de dialogue qui s'ouvre, examinez le code généré, puis cliquez sur Copier et fermer.
Collez le code copié dans le volet Requête et apportez les modifications nécessaires.

Par exemple, supposons que vous créiez une variable nommée LogName qui génère une liste de noms de journaux et affiche le résultat dans une table avec une seule colonne nommée log_name. Ensuite, vous créez un graphique, sélectionnez Insérer un filtre de variable, puis sélectionnez la variable LogName. Le code suivant est généré :
```
WHERE IF(@LogName = '*', TRUE, LogName = @LogName)
```
Dans cet exemple, vous devez modifier le code généré et remplacer LogName = par log_name = pour que la jointure de table puisse avoir lieu :
```
WHERE IF(@LogName = '*', TRUE, log_name = @LogName)
```
Cliquez sur Exécuter, puis sur Appliquer.
Pour enregistrer votre tableau de bord modifié, cliquez sur Enregistrer dans la barre d'outils.

REST

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

Par exemple, l'exemple suivant montre une représentation JSON partielle d'un graphique qui affiche les résultats d'une requête SQL. Pour permettre le filtrage des résultats par nom de journal, une clause WHERE a été ajoutée, qui fait référence à la variable nommée LogName :

"plotType": "STACKED_BAR",
"targetAxis": "Y1",
"timeSeriesQuery": {
  "opsAnalyticsQuery": {
    "queryExecutionRules": {},
    "queryHandle": "",
    "sql": "SELECT\n timestamp, severity, resource.type, log_name, text_payload, proto_payload, json_payload\n
            FROM\n `my-project.global._Default._Default`\n
            WHERE \n IF (@LogName = \"*\", TRUE, log_name=@LogName)\nLIMIT 10000"
  }
}

La variable LogName émet également une requête pour déterminer la liste des noms de journaux possibles :

"dashboardFilters": [
  {
    "filterType": "VALUE_ONLY",
    "templateVariable": "LogName",
    "valueType": "STRING",
    "timeSeriesQuery": {
      "opsAnalyticsQuery": {
        "savedQueryId": "",
        "sql": "SELECT log_name FROM `my-project.global._Default._Default` GROUP BY log_name LIMIT 1000",
        "queryHandle": ""
      },
      "unitOverride": "",
      "outputFullDuration": false
    }
  }
],

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

Graphiques avec des requêtes de filtre Monitoring

Pour mettre à jour un graphique dont la requête se présente sous la forme d'un filtre Monitoring afin qu'il dépende d'une variable basée sur un libellé, suivez les instructions de la section Syntaxe générale.

Console

Si vous utilisez la console Google Cloud pour créer vos graphiques et si vous utilisez l'interface basée sur des menus, vous pouvez mettre à jour la requête du graphique à l'aide du champ Appliquer aux graphiques de la variable ou en modifiant le widget et en sélectionnant la variable basée sur l'étiquette dans le menu Filtre. Le menu Filtre liste toutes les variables basées sur des étiquettes et toutes les clés d'étiquette.

Pour mettre à jour la requête d'un graphique afin qu'elle dépende d'une variable basée sur une valeur, procédez comme suit :

Modifier le graphique
Dans le volet de requête, cliquez sur Ajouter un filtre, puis sélectionnez une clé d'étiquette. Par exemple, vous pouvez sélectionner zone.
Dans le menu Valeur, sélectionnez votre variable de valeur uniquement.
Cliquez sur Appliquer.
Pour enregistrer votre tableau de bord modifié, cliquez sur Enregistrer dans la barre d'outils.

Par exemple, le code JSON suivant illustre une requête qui repose sur une variable basée sur un libellé, my_label_based_variable, qui est résolue en une expression de filtre :

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance" ${my_label_based_variable}"

Les widgets qui utilisent une requête sous la forme d'un filtre Monitoring ne peuvent pas filtrer les séries temporelles en fonction de la valeur d'une variable basée sur une étiquette. Toutefois, vous pouvez filtrer par variables basées sur une valeur uniquement. Par exemple, la requête suivante affiche la valeur du champ Filters d'une requête qui filtre par zone, en fonction de la valeur d'une variable de valeur uniquement :

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance"
resource.label."zone"=monitoring.regex.full_match(${my_value_only_variable})

REST

Par exemple, le code JSON suivant illustre une requête qui repose sur une variable basée sur un libellé, my_label_based_variable, qui est résolue en une expression de filtre :

"timeSeriesQuery": {
  "timeSeriesFilter": {
    "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
              resource.type=\"gce_instance\"
              ${my_label_based_variable} ",
    "aggregation": {
      "alignmentPeriod": "60s",
      "perSeriesAligner": "ALIGN_MEAN",
      "groupByFields": []
    }
  },
  "unitOverride": "",
  "outputFullDuration": false
},

Les widgets qui utilisent une requête sous la forme d'un filtre Monitoring ne peuvent pas filtrer les séries temporelles en fonction de la valeur d'une variable basée sur une étiquette. Toutefois, vous pouvez filtrer par variables basées sur une valeur uniquement. Par exemple, la requête suivante affiche le champ "filter" d'une requête qui filtre par zone, en fonction de la valeur d'une variable de valeur uniquement :

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
          resource.type=\"gce_instance\"
          resource.labels.\"zone\"=monitoring.regex.full_match(${my_value_only_variable})"

Le tableau suivant illustre la façon dont les exemples de variables sont résolus par le filtre Monitoring. Comme indiqué précédemment, lorsque seule la valeur d'une variable est utilisée, vous devez utiliser une expression régulière comme opérateur de comparaison :

Syntaxe	Valeur sélectionnée	Expression de filtre résolue
`${my_label_based_variable}`	`12345`	`resource.instance_id == "12345"` L'exemple de variable est basé sur l'étiquette de ressource `instance_id`.
`${my_label_based_variable}`	`*`	Omission
`${my_label_based_variable.value}`	`12345`	Non compatible
`${my_label_based_variable.value}`	`*`	Non compatible
`${my_value_based_variable}`	`12345`	`"12345"`
`${my_value_based_variable}`	`*`	`".*"`

Modifier un filtre ou une variable épinglés

Pour modifier temporairement la valeur d'un filtre ou d'une variable épinglés affichés dans la barre d'outils du tableau de bord, cliquez sur le nom du filtre ou de la variable, puis saisissez une valeur ou effectuez une sélection dans le menu.

Si votre tableau de bord contient un tableau qui affiche des données de séries temporelles, vous pouvez ajouter des filtres temporaires ou modifier des filtres et des variables permanents à l'aide du bouton Filtrer le tableau de bord sur cette valeur d'une cellule. Lorsque vous sélectionnez ce bouton, il applique un nouveau filtre temporaire ou met à jour la valeur d'un filtre ou d'une variable existants. Les filtres et variables existants sont mis à jour lorsque la clé d'étiquette de la colonne de la table correspond à la clé d'étiquette d'un filtre ou d'une variable.

Pour modifier la configuration d'un filtre épinglé ou d'une variable, procédez comme suit :

Dans la console Google Cloud , accédez à la page Tableaux de bord :
Accéder à la page Tableaux de bord

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Monitoring.
Dans la barre d'outils de la console Google Cloud , sélectionnez votre projet Google Cloud . Pour les configurations App Hub, sélectionnez le projet hôte ou le projet de gestion App Hub.
Dans la barre d'outils du tableau de bord, cliquez sur Paramètres.
Recherchez le filtre ou la variable que vous souhaitez modifier, puis développez sa définition.
Une fois les modifications terminées, cliquez sur Appliquer.
Pour enregistrer votre tableau de bord modifié, cliquez sur Enregistrer dans la barre d'outils.

Supprimer un filtre ou une variable épinglés

Pour supprimer un filtre épinglé ou une variable, procédez comme suit :

Dans la console Google Cloud , accédez à la page Tableaux de bord :
Accéder à la page Tableaux de bord

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Monitoring.
Dans la barre d'outils de la console Google Cloud , sélectionnez votre projet Google Cloud . Pour les configurations App Hub, sélectionnez le projet hôte ou le projet de gestion App Hub.
Dans la barre d'outils du tableau de bord, cliquez sur Paramètres.
Recherchez le filtre ou la variable que vous souhaitez supprimer, puis cliquez sur Supprimer.
Cliquez sur Appliquer.
Pour enregistrer votre tableau de bord modifié, cliquez sur Enregistrer dans la barre d'outils.

Limites

Les filtres au niveau du tableau de bord s'appuient sur le filtrage des données par paires clé/valeur. Ces filtres ne s'appliquent pas lorsque les données ne sont pas compatibles avec les paires clé/valeur ou lorsqu'elles ne sont pas compatibles avec la clé spécifique. Par exemple, vous ne pouvez pas utiliser un filtre au niveau du tableau de bord pour modifier les données affichées par un widget de trace.
Pour appliquer une variable à un widget, vous devez modifier la requête du widget. Tous les widgets ne sont pas modifiables.

Créer et gérer des variables et des filtres épinglés Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

À propos des filtres épinglés

À propos des variables

Avant de commencer

Créer et épingler un filtre

Créer une variable

Ajouter un widget pour gérer la valeur d'une variable

Définir la visibilité d'un widget

Limites

Mettre à jour la requête d'un widget

Créer des filtres et des variables

Console

REST

Syntaxe générale pour déréférencer une variable

Widgets du panneau des journaux

Console

REST

Graphiques avec des requêtes PromQL

Console

REST

Graphiques avec des requêtes SQL

Console

REST

Graphiques avec des requêtes de filtre Monitoring

Console

REST

Modifier un filtre ou une variable épinglés

Supprimer un filtre ou une variable épinglés

Limites

Étapes suivantes

Créer et gérer des variables et des filtres épinglés