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

Ce document explique comment épingler des filtres au niveau du tableau de bord afin qu'ils soient permanents. Les filtres épinglés, qui vous permettent de modifier les données affichées par un tableau de bord sans avoir à modifier chaque widget, ont un état par défaut et peuvent s'appliquer à l'ensemble du tableau de bord ou uniquement à des widgets spécifiques. La barre d'outils du tableau de bord affiche chaque filtre épinglé, ainsi qu'un menu qui vous permet de modifier temporairement la valeur du filtre.

Les variables sont semblables aux filtres épinglés, mais elles ne s'appliquent qu'à des widgets spécifiques. Ce document explique comment créer des variables et comment les appliquer à l'aide d'un widget. La barre d'outils du tableau de bord affiche chaque variable, ainsi qu'un menu qui vous permet de modifier temporairement la valeur de la variable.

Ce document explique comment utiliser la console Google Cloud pour créer des variables et des filtres épinglés. Pour en savoir plus sur l'utilisation de l'API Cloud Monitoring, consultez la page Créer et gérer des tableaux de bord à l'aide d'API: Filtres de tableau de bord.

Pour savoir comment ajouter et modifier des regroupements et des filtres temporaires, qui ne s'appliquent qu'à la 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 dynamiquement des données de séries temporelles affichées dans votre tableau de bord. Pour en savoir plus sur la structure d'un filtre, consultez DashboardFilter.

Vous n'appliquez pas de filtre épinglé avec 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 qu'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 associées à un libellé cluster_name dont la valeur est mycluster. De même, les requêtes sur les widgets de votre panneau de journaux sont modifiées pour devenir resource.labels."cluster_name"="mycluster", et vos graphiques n'affichent automatiquement que les séries temporelles qui incluent le libellé dans le filtre épinglé.

• Un filtre épinglé est ignoré par un widget lorsqu'il inclut un filtre pour la même clé de libellé ou lorsque les données affichées par le widget ne contiennent pas la clé de libellé spécifiée dans le filtre épinglé.

À propos des variables

Une variable possède un nom et un type. Une variable est appliquée à un widget particulier en modifiant la requête qu'il contient. Pour en savoir plus sur la structure d'un filtre, consultez DashboardFilter.

Les variables peuvent être basées sur des libellés ou n'avoir qu'une valeur:

• Les variables basées sur des étiquettes sont comme 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 dynamiquement des données de séries temporelles affichées dans votre tableau de bord.

• Les variables à valeur unique 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 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 valeur uniquement: Personnalisée, Saisie de texte et Requête SQL.

  • Personnalisé: utilisez cette option 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 la valeur par défaut sur prod.

  • Saisie de texte: utilisez-la lorsque vous ne connaissez pas toutes les valeurs possibles. Par exemple, vous pouvez vouloir filtrer par URL, mais lorsque vous créez la variable, vous ne connaissez pas la liste exacte des URL. Ensuite, lorsque vous utilisez le menu de filtrage du widget, vous pouvez saisir de nouvelles URL, puis enregistrer les modifications pour la session en cours ou pour la définition de la variable.

  • 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 de Log Analytics.

    Pour ces variables, assurez-vous que le résultat de la requête est une table avec 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 `TABLE_NAME_OF_LOG_VIEW`
    GROUP BY log_name
    

    La variable doit interroger la même table que le graphique.

Pour appliquer une variable à un widget, vous devez modifier la requête qu'il contient. Si vous utilisez la console Google Cloud, vous pouvez effectuer cette association à l'aide d'une sélection de menu pour les variables basées sur des libellés et certains types de widgets. Toutefois, vous pouvez toujours modifier la requête du widget pour appliquer une variable. Pour en savoir plus, consultez la section Appliquer une variable à un widget.

Avant de commencer

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 la page 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 la section 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:

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

2. Dans la barre d'outils du tableau de bord, cliquez sur settings Paramètres.
3. Dans la section Filtres, cliquez sur Ajouter un filtre.
4. Cliquez sur arrow_drop_down Libellé, puis sélectionnez un libellé. Par exemple, vous pouvez sélectionner zone.
5. Pour autoriser un utilisateur à sélectionner plusieurs valeurs dans le menu des valeurs de la variable, sélectionnez Sélection multiple. Lorsque la sélection multiple n'est pas activée, les utilisateurs ne peuvent sélectionner qu'une seule option dans le menu des valeurs.

6. Cliquez sur arrow_drop_down Valeur par défaut, puis sélectionnez la ou les valeurs par défaut du libellé. Pour correspondre à toutes les valeurs, sélectionnez *.

   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, puis effectuez une sélection dans le menu.

7. Cliquez sur OK, puis sur Appliquer.

8. Pour enregistrer le 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:

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

2. Dans la barre d'outils du tableau de bord, cliquez sur settings Paramètres.
3. Dans la section Variables, cliquez sur Ajouter une variable.

4. Sélectionnez le type de variable, puis remplissez la boîte de dialogue.

   Pour créer une variable basée sur un libellé, sélectionnez Libellé. Utilisez cette option lorsque vous souhaitez qu'une variable comporte une clé et une valeur d'étiquette, et qu'elle puisse être utilisée comme un filtre. La liste de toutes les valeurs possibles est dérivée dynamiquement des données de séries temporelles affichées dans votre tableau de bord.

   Pour les variables à valeur unique, vous avez les 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 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 à 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.

5. Attribuez un nom à la variable. Le nom s'affiche dans la barre d'outils du tableau de bord.

6. Cliquez sur OK, puis sur Appliquer.

7. Appliquez la variable aux widgets du panneau des journaux et aux widgets configurés avec SQL, MQL ou PromQL. Pour en savoir plus, consultez la section Appliquer une variable à un widget.

8. Pour enregistrer le tableau de bord modifié, cliquez sur Enregistrer dans la barre d'outils.

Appliquer une variable à un widget

Pour appliquer une variable à un widget, vous devez modifier la requête utilisée par le widget:

• Pour les graphiques qui utilisent des requêtes SQL, PromQL ou MQL, et pour les widgets de 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.

Pour savoir comment appliquer une variable basée sur un libellé ou une variable de valeur uniquement à un widget, consultez les sections suivantes:

• Syntaxe générale pour désadresser une variable
• Widgets du panneau "Journaux"
• Graphiques avec des requêtes PromQL
• Graphiques avec des requêtes SQL
• Graphiques avec des requêtes MQL

• Graphiques avec des requêtes de filtre Monitoring

  Lorsque vous utilisez l'interface à menus pour créer un graphique qui affiche des données de séries temporelles, vos sélections sont converties en filtre de surveillance.

Créer des filtres et des variables

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

Syntaxe générale pour désadresser 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 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 à valeur unique, 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 sous Syntaxe générale.

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

severity =~ "${value_only_severity_variable}"

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

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

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

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

Si vous avez configuré une requête pour le panneau des journaux, puis sélectionné 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:

Graphiques avec des requêtes PromQL

Pour appliquer une variable basée sur un libellé à un graphique contenant une requête PromQL, suivez les instructions de la section Syntaxe générale.

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

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

zone=~"${my_value_only_variable}"

"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:

Graphiques avec des requêtes SQL

Lorsque vous souhaitez appliquer une variable à un widget défini en SQL, mettez à jour la clause WHERE pour faire référence à la valeur de la variable. Pour toutes les variables, préfixez le nom de la variable avec le signe "at", par exemple : @variable_name. Pour les variables basées sur des libellés, 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 sécurisée contre les injections SQL. Pour en savoir plus, consultez la section Exécuter des requêtes paramétrées.

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

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

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

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

"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 MQL

Pour appliquer une variable basée sur un libellé à un graphique contenant une requête MQL, ajoutez un pipe, (|), puis suivez les instructions indiquées dans la section Syntaxe générale.

Lorsque vous utilisez l'interface à menus pour créer un graphique qui affiche des données de séries temporelles, vos sélections sont converties en filtre de surveillance.

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| every 1m
| ${my_label_based_variable}

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| filter resource.instance_id=~'${my_label_based_variable.value}'
| group_by 1m, [value_utilization_mean: mean(value.utilization)]
| every 1m

resource.zone=~'${my_value_only_variable}'

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n
    | ${my_label_based_variable}",
  "unitOverride": "",
  "outputFullDuration": false
},

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | filter resource.instance_id=~'${my_label_based_variable.value}'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n",
  "unitOverride": "",
  "outputFullDuration": false
},

resource.zone=~'${my_value_only_variable}'

Le tableau suivant illustre la façon dont les exemples de variables sont résolus par le MQL. 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:

Graphiques avec des requêtes de filtres de surveillance

Pour appliquer une variable basée sur des étiquettes à un graphique contenant une requête sous la forme d'un filtre de surveillance, suivez les instructions de la section Syntaxe générale.

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

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

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

"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 de surveillance. 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:

Modifier un filtre ou une variable épinglés

Pour modifier temporairement la valeur de n'importe quel filtre affiché dans la barre d'outils du tableau de bord, cliquez sur le nom du filtre, 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érie temporelle, vous pouvez ajouter des filtres temporaires ou modifier des filtres et des variables permanents à l'aide du bouton filter_list Filtrer le tableau de bord selon cette valeur d'une cellule. Lorsque ce bouton est sélectionné, il applique un nouveau filtre temporaire ou met à jour la valeur d'un filtre ou d'une variable existante. 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:

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

2. Dans la barre d'outils du tableau de bord, cliquez sur settings Paramètres.
3. Recherchez le filtre ou la variable que vous souhaitez modifier, puis développez sa définition.
4. Une fois les modifications effectuées, cliquez sur Appliquer.
5. Pour enregistrer le 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:

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

2. Dans la barre d'outils du tableau de bord, cliquez sur settings Paramètres.
3. Recherchez le filtre ou la variable que vous souhaitez supprimer, puis cliquez sur delete Supprimer.
4. Cliquez sur Appliquer.
5. Pour enregistrer le tableau de bord modifié, cliquez sur Enregistrer dans la barre d'outils.

Étape suivante

• Explorer les données représentées graphiquement
• Accéder aux tableaux de bord spécifiques aux ressources