Ce document explique comment créer et gérer des tableaux de bord personnalisés, ainsi que les widgets qu'ils contiennent à l'aide de la ressource Dashboard
de l'API Cloud Monitoring.
Les exemples de cette page montrent comment gérer vos tableaux de bord en appelant l'API à l'aide de curl
et comment utiliser la Google Cloud CLI.
Bien que vous puissiez également gérer vos tableaux de bord personnalisés via la console Google Cloud, l'API vous offre une méthode programmatique 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 :
dashboards.create
: crée un tableau de bord.dashboards.delete
: supprime le tableau de bord spécifié.dashboards.list
: récupère la liste de tous les tableaux de bord d'un projet donné.dashboards.get
: récupère le tableau de bord spécifié.dashboards.patch
: met à jour la structure du tableau de bord spécifié.
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.
Avant de commencer
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 filtres permanents à votre 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
:
Widgets de graphique et de tableau:
XyChart
(graphique x-y) : affiche les données suivant les axes X et Y. Les graphiques suivants sont des instances du widgetXyChart
:Graphiques en courbes
Graphique à barres
Graphiques en aires empilées
Cartes de densité
Graphiques d'Analyse de journaux
Widgets de SLO, mais la création de graphiques de SLO à l'aide de l'API n'est pas acceptée.
Si vous créez un graphique en courbes, un graphique à barres empilées ou un graphique en aires empilées, vous pouvez spécifier une métrique faisant référence à l'axe y à gauche ou à droite. Lorsque plusieurs métriques sont représentées dans un graphique, vous pouvez utiliser les deux axes Y.
PieChart
: affiche la dernière valeur d'une métrique, où chaque série temporelle contribue à une tranche du graphique.Scorecard
(tableau de données) : affiche la valeur la plus récente d'une métrique et sa position par rapport à un ou plusieurs seuils.TimeSeriesTable
(graphique de série temporelle) : affiche la valeur la plus récente d'une métrique. Vous pouvez trier le tableau en fonction des colonnes, le filtrer et ajouter ou supprimer des colonnes dans l'affichage.
Graphique d'alerte et widgets d'incident:
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 la liste des incidents. Vous pouvez configurer le widget de façon à afficher les incidents pour des règles d'alerte spécifiques ou des types de ressources spécifiques.
Widgets de journal et d'erreur:
ErrorReportingPanel
: affiche les groupes d'erreurs stockés dans le projet Google Cloud sélectionné.LogsPanel
(panneau des journaux) : affiche les entrées de journal à l'échelle du projet stockées dans le projet Google Cloud actuel. Vous pouvez configurer le widget pour afficher les entrées de journal stockées dans des projets Google Cloud accessibles via le champ d'application des métriques actuel.
Widgets de texte et d'organisation:
Pour inclure ces widgets dans un tableau de bord, celui-ci doit comporter un
MosaicLayout
.CollapsibleGroup
: affiche une collection de widgets. Vous pouvez réduire l'affichage 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.Text
(texte) : affiche du contenu textuel sous forme de texte brut ou de chaîne Markdown.
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"
}
}
}
]
}
}
Filtres du tableau de bord
Lorsque vous concevez un tableau de bord, vous pouvez identifier plusieurs façons d'afficher les données qu'il affiche. Par exemple, lorsqu'un tableau de bord affiche des métriques pour des instances de machine virtuelle (VM), vous pouvez consulter les métriques de toutes les VM ou d'une zone spécifique. Dans ce type de situation, nous vous recommandons de créer un filtre permanent et de définir la valeur par défaut de ce filtre sur 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 les 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 à l'échelle du tableau de bord s'appliquent à tous les widgets d'un tableau de bord qui acceptent le libellé de filtre et qui ne spécifient pas de valeur pour ce libellé.
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 du tableau de bord portant 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 au niveau 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 au niveau du tableau de bord avec la clé de libellé 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 elle s'applique. À la place, vous associez un widget à une variable de modèle en modifiant la requête du widget pour inclure une référence à la variable. Lorsque le widget est affiché sur le tableau de bord, la valeur de la variable de modèle est résolue.
Consultez les sections suivantes pour découvrir comment annoter les panneaux et les graphiques des journaux:
- Panneau "Journaux"
- Graphiques et tables définis par MQL
- Graphiques et tables définis par PromQL
- Graphiques et tables définis avec des filtres de séries temporelles
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 en fonction de la valeur de la variable de modèle iid
:
${iid}
Avant que le panneau des journaux interroge les journaux à afficher, la variable de modèle est résolue. 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 avez sélectionné le bouton permettant d'ouvrir l'explorateur de journaux, les variables de modèle sont résolues avant l'ouverture de l'explorateur.
Le tableau suivant montre comment la variable de modèle est résolue par le panneau des journaux:
Syntaxe | Valeur sélectionnée |
Expression du panneau "Journaux résolus" |
---|---|---|
${iid} |
12345 |
resource.labels."instance_id"="12345" |
${iid} |
* |
"" |
${iid.value} |
12345 |
12345 |
${iid.value} |
* |
.* |
Graphiques et tables définis par MQL
Lorsque vous utilisez le langage MQL (Monitoring Query Language) pour configurer un graphique, ajoutez une barre verticale 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ésolue. Dans cet exemple, si la valeur de la variable de modèle est "12345"
, ${iid}
est remplacé par l'instruction filter (resource.instance_id == '12345')
. Ce filtre fait correspondre les séries temporelles portant un libellé nommé resource.instance_id
, et uniquement lorsque la valeur de ce libellé est exactement 12345
.
Lorsque vous souhaitez filtrer des séries temporelles à l'aide d'une expression régulière, configurez la requête pour n'inclure que la valeur de la variable de modèle.
Pour illustrer la syntaxe, voici comment utiliser une expression régulière pour déterminer si la valeur du libellé 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 | Valeur sélectionnée |
Expression MQL résolue |
---|---|---|
${iid} |
12345 |
filter (resource.instance_id == '12345') |
${iid} |
* |
filter (true) |
${iid.value} |
12345 |
12345 |
${iid.value} |
* |
.* |
Graphiques et tables définis par PromQL
Lorsque vous définissez un graphique à l'aide de PromQL, ajoutez à la chaîne de requête la variable encapsulée par des accolades:
compute_googleapis_com:instance_cpu_utilization { project_id="my-project", ${iid} }
Avant que le graphique n'interroge 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"
, ${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 de n'utiliser la valeur que dans le cadre d'un filtre défini avec une expression régulière. Pour illustrer la syntaxe, voici comment utiliser une expression régulière pour déterminer si la valeur de l'étiquette 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 | Valeur sélectionnée |
Expression PromQL résolue |
---|---|---|
${iid} |
12345 |
instance_id == '12345' |
${iid} |
* |
noop_filter=~".*" |
${iid.value} |
12345 |
12345 |
${iid.value} |
* |
.+ |
Graphiques et tables définis avec des 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 | Valeur sélectionnée |
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 commande 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:
- Suivez les étapes de la section Obtenir le tableau de bord pour télécharger la définition du tableau de bord d'origine.
- Modifiez le fichier JSON renvoyé pour supprimer les champs
etag
etname
, puis changez la valeur du champdisplayName
. - Exécutez la commande ci-dessous pour 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 via la console Google Cloud.
Pour découvrir d'autres configurations de tableaux de bord, consultez la section Exemples de tableaux de bord et de mises en page.
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 référence 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 la commande 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 référence 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 référence 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
.
Étapes suivantes
- Exemples de tableaux de bord et de mises en page
- Créer et gérer des tableaux de bord personnalisés avec la console Google Cloud