Créer et gérer des tableaux de bord à l'aide d'API

Ce document explique comment créer et gérer des tableaux de bord personnalisés et leurs widgets à l'aide de la ressource Dashboard de l'API Cloud Monitoring. Les exemples ci-dessous montrent comment gérer vos tableaux de bord à l'aide de curl pour appeler l'API et comment utiliser la CLI Google Cloud. Vous pouvez aussi gérer vos tableaux de bord personnalisés via console Google Cloud, l'API vous fournit pour gérer de nombreux tableaux de bord en même temps.

Le point de terminaison accepte les méthodes suivantes pour la gestion et la configuration des tableaux de bord :

Vous pouvez appeler l'API directement à l'aide de l'utilitaire curl ou de la Google Cloud CLI.

Vous ne pouvez pas récupérer, modifier ni supprimer des tableaux de bord prédéfinis.

À propos des tableaux de bord

Lorsque vous créez un tableau de bord, vous devez spécifier les composants ou widgets que vous souhaitez afficher ainsi que leur disposition. Vous pouvez également ajouter des libellés et des filtres à votre tableau de bord. Les libellés peuvent vous aider à trouver un tableau de bord ou indiquer le type de contenu sur le tableau de bord.

Dispositions de tableaux de bord

La disposition ou mise en page d'un tableau de bord définit la façon dont ses composants sont organisés. L'API fournit les dispositions suivantes :

  • GridLayout (en grille) : partage l'espace disponible en colonnes verticales de même largeur et organise l'ensemble de widgets ligne par ligne.

  • MosaicLayout (en grille) : divise l'espace disponible en grille. Chaque widget peut occuper un ou plusieurs blocs de type grille.

  • RowLayout (en mosaïque) : partage l'espace disponible en lignes et organise l'ensemble de widgets horizontalement sur chaque ligne.

  • ColumnLayout (en colonne) : partage l'espace disponible en colonnes verticales et organise l'ensemble de widgets verticalement dans chaque colonne.

Par exemple, voici la représentation JSON d'un tableau de bord en disposition RowLayout avec trois widgets Text :

{
  "displayName": "Row-layout example",
  "rowLayout": {
    "rows": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  }
}

Widgets de tableau de bord

Un widget contient un unique composant de tableau de bord, ainsi que la configuration définissant comment présenter ce composant dans le tableau de bord. Un tableau de bord peut comporter plusieurs widgets. Il existe plusieurs types d'objets Widget :

  • Le widget XyChart affiche les données sur les axes X et Y.

    Ce widget affiche un ensemble de données pouvant être des données de séries temporelles ou générées par une requête SQL. Ce widget vous permet d'associer les données du graphique à l'axe Y de gauche ou de droite. Quand ? si plusieurs types de métriques sont représentés dans un graphique, vous pouvez utiliser les deux axes Y. Le widget XyChart accepte les styles d'affichage suivants:

    • Graphiques en courbes
    • Graphique à barres
    • Graphiques en aires empilées
    • Cartes de densité

  • Widgets qui s'affichent à partir d'une dimension, comme la dernière valeur :

    • PieChart : affiche les dernières valeurs d'une collection de séries temporelles, où chaque série temporelle contribue à une tranche du graphique en secteurs.

    • Scorecard (tableau de données) : affiche la valeur la plus récente d'une série temporelle et sa position par rapport à un ou plusieurs seuils.

    • TimeSeriesTable: affiche la dernière valeur ou une pour chaque série temporelle. Les tableaux sont compatibles avec la personnalisation. Par exemple, vous pouvez attribuer un code couleur aux cellules, et configurer les noms de colonnes et l'alignement des données.

  • Widgets affichant des règles d'alerte ou des informations sur les incidents:

    • AlertChart (graphique d'alerte) : affiche un résumé d'une règle d'alerte à une seule condition. Ce widget affiche les données sous la forme d'un graphique en courbes, affiche le seuil et indique le nombre d'incidents ouverts.

    • IncidentList : affiche une liste d'incidents. Vous pouvez configurer le widget pour afficher les incidents pour des règles d'alerte spécifiques ou pour des types de ressources spécifiques.

  • Les widgets qui affichent les entrées de journal et les erreurs:

  • Widgets de texte et d'organisation:

    • CollapsibleGroup: affiche un ensemble de widgets. Vous pouvez réduire la vue d'un groupe.

    • SingleViewGroup : affiche un widget dans une collection de widgets. Vous pouvez sélectionner le widget à afficher.

    • SectionHeader : crée un séparateur horizontal dans votre tableau de bord et une entrée dans la table des matières du tableau de bord.

    • Text (texte) : affiche du contenu textuel sous forme de texte brut ou de chaîne Markdown.

    Pour inclure les widgets de texte et d'organisation dans un tableau de bord, celui-ci doit comporter un MosaicLayout.

Outre ces objets, vous pouvez également ajouter à un tableau de bord un espace réservé vide.

Par exemple, voici la représentation JSON d'un widget XyChart dont l'axe Y droit est configuré:

{
  "displayName": "Demo dashboard",
  "gridLayout": {
    "widgets": [
      {
        "title": "Sample line chart",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesFilter": {
                  "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
                  "aggregation": {
                    "perSeriesAligner": "ALIGN_MEAN",
                    "crossSeriesReducer": "REDUCE_MAX",
                    "groupByFields": [
                      "resource.label.zone"
                    ]
                  }
                },
                "unitOverride": "1"
              },
              "plotType": "LINE"
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

Étiquettes du tableau de bord

Les libellés peuvent vous aider à gérer et à organiser vos tableaux de bord. Par exemple, vous pouvez ajouter un libellé nommé prod pour indiquer que le tableau de bord affiche des données de série temporelle et des données de journal pour vos ressources de production. Vous pouvez également ajouter le libellé playbook pour indiquer que le tableau de bord contient des informations pour vous aider à résoudre les échecs.

L'ajout de libellés à un tableau de bord est facultatif.

Par exemple, l'exemple suivant montre un objet Dashboard qui spécifie l'étiquette nommée playbook.

{
  "displayName": "Example",
  "mosaicLayout": {
    "columns": 12,
    "tiles": [
      ...
    ]
  },
  "dashboardFilters": [],
  "labels": {
    "playbook": ""
  }
}

Comme l'illustre l'exemple précédent, le champ labels est implémenté en tant que map, où les champs key et value correspondent à des chaînes. Lorsque vous ajoutez un libellé à un tableau de bord, définissez key sur le nom du libellé et le champ value sur une chaîne vide.

Filtres du tableau de bord

Lorsque vous concevez un tableau de bord, vous pouvez identifier plusieurs façons d'afficher les données affichées par le tableau de bord. Par exemple, supposons qu'un tableau de bord affiche des données de séries temporelles pour vos instances de machines virtuelles (VM). Vous voudrez peut-être pour afficher les données de séries temporelles pour toutes les VM. Vous pouvez aussi afficher uniquement pour les données qui se trouvent dans une zone spécifique. Dans ce nous vous recommandons de créer un filtre permanent et de définir la valeur de ce filtre à la vue la plus couramment utilisée. Les filtres permanents peuvent s'appliquer à certains ou à tous les widgets du tableau de bord. Lorsque vous affichez le tableau de bord avec la console Google Cloud, la barre d'outils du tableau de bord affiche vos filtres permanents et un menu que vous pouvez utiliser pour modifier temporairement la valeur du filtre.

Il existe plusieurs types de filtres de tableau de bord permanents :

  • Les filtres applicables à l'ensemble du tableau de bord s'appliquent à tous les widgets d'un tableau de bord qui prennent en charge le libellé de filtre et qui ne spécifient pas de valeur pour cette étiquette.

    Par exemple, lorsqu'un graphique inclut le filtre zone = us-central1-a, il ignore un filtre de tableau de bord basé sur le libellé zone. De même, Les graphiques sans libellé zone ignorent les filtres de tableau de bord associés à ce libellé.

  • Les variables de modèle sont des variables nommées qui s'appliquent à des widgets spécifiques. Chaque variable correspond à une étiquette et à une valeur spécifiques. Vous déterminez les widgets auxquels une variable de modèle s'applique.

Tous les types de filtres sont représentés par la même structure de données. Pour en savoir plus, consultez la page DashboardFilter.

Par exemple, voici la représentation JSON partielle d'un tableau de bord qui définit une variable de modèle et un filtre à l'échelle du tableau de bord :

{
  "dashboardFilters": [
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "templateVariable": "iid"
      },
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "zone"
      }
    ],
  "displayName": "Illustrate Template Variables",
  ...

Dans le fichier JSON affiché, la première entrée de la structure dashboardFilters correspond à une variable de modèle nommée iid et à un filtre pour l'ensemble du tableau de bord avec la clé d'étiquette zone. La variable de modèle est un alias du libellé instance_id.

La structure de données d'une variable de modèle ne répertorie pas les widgets auxquels s'applique. Pour associer un widget à une variable de modèle, modifier la requête du widget pour inclure une référence à la variable. Lorsque le widget est affiché dans le tableau de bord, la valeur de la variable de modèle est résolue.

Pour savoir comment annoter les panneaux et les graphiques des journaux, consultez les sections suivantes :

Panneau des journaux

Pour configurer un panneau de journaux afin de filtrer l'affichage en fonction de la valeur d'une variable de modèle, ajoutez la variable au volet de requête. L'exemple suivant illustre une requête qui filtre selon la valeur de la variable de modèle iid :

${iid}

Avant que le panneau des journaux n'interroge les journaux à afficher, la variable de modèle est résolu. Dans cet exemple, si la valeur de la variable de modèle est "12345", ${iid} est remplacé par l'instruction resource.labels."instance_id"="12345".

Vous pouvez également n'inclure que la valeur d'une variable de modèle dans une requête. Nous vous recommandons de n'utiliser la valeur que dans le cadre d'un filtre défini avec une expression régulière. Par exemple, la requête suivante utilise une expression régulière pour faire correspondre les entrées de journal dont la charge utile JSON contient la chaîne décrite :

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

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 de modèle sont résolues avant l'explorateur de journaux est ouvert.

Le tableau suivant montre comment la variable de modèle est résolue par le panneau des journaux :

Syntaxe Selected
Value		 Expression du panneau des journaux résolus
${iid} 12345 resource.labels."instance_id"="12345"
${iid} * ""
${iid.value} 12345 12345
${iid.value} * .*

Graphiques et tableaux définis par MQL

Lorsque vous utilisez le langage MQL (Monitoring Query Language) pour configurer un graphique, ajoutez un pipe et la variable à la chaîne de requête :

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

Avant que le graphique n'interroge la série temporelle à afficher, la variable de modèle est résolu. Dans cet exemple, si la valeur de la variable de modèle est "12345", alors ${iid} est remplacé par l'instruction filter (resource.instance_id == '12345') Ce filtre correspond à la période comportant une étiquette nommée resource.instance_id, et uniquement lorsque la valeur de cette étiquette est exactement 12345.

Lorsque vous souhaitez filtrer des séries temporelles à l'aide d'une expression régulière, configurer la requête pour n'inclure que la valeur de la variable de modèle. Pour illustrer la syntaxe, les éléments suivants montre comment utiliser une expression régulière pour déterminer si la valeur de la L'étiquette resource.instance_id contient la valeur de la variable de modèle iid:

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

Le tableau suivant montre comment la variable de modèle est résolue pour les requêtes MQL :

Syntaxe Selected
Value		 Expression MQL résolue
${iid} 12345 filter (resource.instance_id == '12345')
${iid} * filter (true)
${iid.value} 12345 12345
${iid.value} * .*

Graphiques et tableaux définis en PromQL

Lorsque vous définissez un graphique à l'aide de PromQL, ajoutez à la chaîne de requête le encapsulée par des accolades:

compute_googleapis_com:instance_cpu_utilization {
    project_id="my-project", ${iid}
}

Avant que le graphique ne demande la série temporelle à afficher, la variable de modèle est résolue. Dans cet exemple, si la valeur de la variable de modèle est "12345", alors ${iid} est remplacé par l'instruction instance_id == '12345'

Comme pour MQL, lorsque vous définissez un widget avec PromQL, la requête ne peut extraire que la valeur de la variable de modèle. Nous vous recommandons n'utilisez la valeur que dans le cadre d'un filtre défini avec une expression régulière. Pour illustrer la syntaxe, l'exemple suivant montre comment utiliser une expression régulière pour déterminer si la valeur du libellé instance_id contient la valeur de la variable de modèle iid :

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

Le tableau suivant montre comment la variable de modèle est résolue pour les requêtes PromQL :

Syntaxe Selected
Value		 Expression PromQL résolue
${iid} 12345 instance_id == '12345'
${iid} * noop_filter=~".*"
${iid.value} 12345 12345
${iid.value} * .+

Graphiques et tableaux définis à l'aide de filtres de séries temporelles

Lorsque vous définissez un graphique à l'aide de filtres de séries temporelles, ajoutez la variable à la chaîne de filtre:

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
           resource.type=\"gce_instance\" ${iid}"

Contrairement aux graphiques définis par MQL et PromQL, vous ne pouvez pas utiliser la valeur d'une variable de modèle dans un filtre de série temporelle.

Le tableau suivant montre comment la variable de modèle est résolue:

Syntaxe Selected
Value		 Expression de filtre résolue
${iid} 12345 resource.instance_id == "12345"
${iid} * Omission
${iid.value} 12345 Non compatible
${iid.value} * Non compatible

Créer un tableau de bord

Pour créer un tableau de bord personnalisé, appelez la méthode dashboards.create en lui fournissant la disposition du tableau de bord et les widgets à y afficher.

Lorsque vous créez un tableau de bord, l'API génère automatiquement l'identifiant dashboard_id. Si vous souhaitez spécifier un identifiant dashboard_id personnalisé, vous pouvez définir le champ name d'un objet Dashboard. Le format du champ de nom se présente ainsi :

"name": "projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}"

Protocole

Pour créer un tableau de bord, envoyez une requête POST au point de terminaison Dashboard.

curl -d @my-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X POST https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

gcloud

Pour créer un tableau de bord dans un projet, utilisez la gcloud monitoring dashboards create.

gcloud monitoring dashboards create --config-from-file=my-dashboard.json

Par exemple, si vous souhaitez dupliquer un tableau de bord, procédez comme suit:

  1. Suivez la procédure de la section Obtenir un tableau de bord pour télécharger la définition du tableau de bord d'origine.
  2. Modifiez le code JSON renvoyé pour supprimer les champs etag et name, et modifiez la valeur du champ displayName.
  3. Exécutez la commande permettant de créer le tableau de bord.

Pour en savoir plus, consultez la référence gcloud monitoring dashboards create.

Les exemples présentés ici créent un tableau de bord à l'aide du fichier my-dashboard.json. Vous pouvez gérer votre tableau de bord depuis la console Google Cloud.

Pour voir d'autres configurations de tableau de bord, consultez la page Exemples de tableaux de bord et de dispositions.

Supprimer des tableaux de bord

Pour supprimer un tableau de bord personnalisé, appelez la méthode dashboards.delete en spécifiant le tableau de bord à supprimer.

Protocole

Pour supprimer un tableau de bord personnalisé, envoyez une requête DELETE au point de terminaison Dashboard incluant l'ID du tableau de bord à supprimer.

curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Si l'opération réussit, l'API renvoie une réponse vide. Sinon, l'appel renvoie une erreur.

gcloud

Pour supprimer un tableau de bord personnalisé, utilisez gcloud monitoring dashboards delete et spécifiez l'ID complet du tableau de bord à supprimer :

gcloud monitoring dashboards delete projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Pour en savoir plus, consultez la référence gcloud monitoring dashboards delete.

Répertorier les tableaux de bord

Pour lister tous les tableaux de bord associés à un projet, appelez la méthode dashboards.list en spécifiant l'ID du projet.

Protocole

Pour répertorier tous les tableaux de bord personnalisés d'un projet, envoyez l'ID du projet au point de terminaison Dashboard.

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

gcloud

Pour répertorier tous les tableaux de bord personnalisés d'un projet, utilisez la commande gcloud monitoring dashboards list :

gcloud monitoring dashboards list

Pour en savoir plus, consultez la documentation de référence sur gcloud monitoring dashboards list.

Les exemples renvoient les tableaux de bord personnalisés associés à votre projet.

Paginer la réponse de List

La méthode dashboards.list permet la pagination, ce qui vous permet d'afficher les résultats page par page et non en un seul bloc.

Protocole

Pour la première page de la liste de résultats, spécifiez le paramètre pageSize (taille de page) dans la requête :

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards?page_size=1

La méthode renvoie la première page de la liste ainsi que le jeton nextPageToken. Exemple :

{
  "dashboards" : [
    {
       "displayName" : "Grid Layout Example",
       "gridLayout" : {
         "widgets" : [
            { ... },
            { ... },
            { ... },
          ]
       }
    }
  ]
},
"nextPageToken": "ChYqFDEyMzkzMzUwNzg0OTE1MDI4MjM3"

Pour chacune des pages restantes, vous devez inclure le jeton nextPageToken correspondant dans la requête.

gcloud

Pour spécifier le nombre de ressources par page, transmettez l'option --page-size à l'aide de la commande. Exemple :

gcloud monitoring dashboards list --page-size=1

Obtenir un tableau de bord

Pour obtenir un tableau de bord personnalisé spécifique pour un projet, appelez la méthode dashboards.get en spécifiant l'ID du tableau de bord.

Protocole

Pour récupérer un tableau de bord personnalisé spécifique, envoyez l'ID du tableau de bord au point de terminaison Dashboard.

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

La méthode renvoie une réponse semblable à l'exemple ci-dessous :

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

gcloud

Pour obtenir un tableau de bord personnalisé spécifique, utilisez le gcloud monitoring dashboards describe et spécifiez l'ID du tableau de bord:

gcloud monitoring dashboards describe ${DASHBOARD_ID} --format=json

La commande renvoie le tableau de bord demandé :

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

Pour en savoir plus, consultez la documentation de référence sur gcloud monitoring dashboards describe.

Mettre à jour le tableau de bord

Pour mettre à jour un tableau de bord personnalisé existant, appelez la méthode dashboards.patch. Pour obtenir la valeur etag actuelle, vous pouvez appeler la méthode dashboards.get : la valeur figure dans la réponse.

Protocole

Pour mettre à jour un tableau de bord personnalisé, envoyez une requête PATCH au point de terminaison Dashboard et fournissez l'objet Dashboard révisé et la valeur etag de la dernière réponse dashboards.get.

curl -d @my-updated-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X PATCH https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

gcloud

Pour mettre à jour un tableau de bord personnalisé, utilisez gcloud monitoring dashboards update, spécifiez l'ID du tableau de bord à mettre à jour et effectuez les modifications.

gcloud monitoring dashboards update ${DASHBOARD_ID} --config-from-file=my-updated-dashboard.json

Pour en savoir plus, consultez la documentation de référence sur gcloud monitoring dashboards update.

Les exemples mettent à jour un tableau de bord personnalisé existant à l'aide du fichier my-updated-dashboard.json et renvoient une copie de la liste de tableaux de bord mise à jour. Les données de retour incluent une nouvelle valeur etag.

Étape suivante