← Google Cloud pour les devs : gcloud et Cloud Logging

Des logs au tableau de bord : métriques, graphiques et alertes

≈ 35 minutes · Jalon M4 · Prérequis : Écrire des logs structurés depuis Python

Le gain du jour : transformer les logs de ton API en un tableau de bord de quatre graphiques que l’équipe ouvre vraiment, versionné dans git, avec une alerte qui ne sonne que quand il faut.

Un tableau de bord, c’est quoi ?

Un tableau de bord (dashboard) est une page qui regroupe des graphiques. Chaque graphique répond à une question : « combien d’erreurs ? », « est-ce lent ? ». Dans Google Cloud, ils vivent dans Cloud Monitoring, pas dans Cloud Logging.

Un graphique a besoin d’une série temporelle (des chiffres dans le temps). Un log est une ligne de texte. Il faut un pont. On construit le chemin pas à pas.

D’abord, tes logs arrivent dans Cloud Logging :

 🐍 API  ──▶  🗂 Cloud Logging

Ensuite, une métrique basée sur les logs compte les entrées qui correspondent à un filtre et produit une série temporelle :

 🐍 API  ──▶  🗂 Cloud Logging  ──▶  🔢 Métrique basée sur les logs
                                      (1 point par minute)

Puis Cloud Monitoring dessine cette série dans un graphique :

 🐍 API  ──▶  🗂 Cloud Logging  ──▶  🔢 Métrique  ──▶  📈 Graphique
                                                        (tableau de bord)

Enfin, une alerte surveille la même série et te prévient :

 🐍 API  ──▶  🗂 Cloud Logging  ──▶  🔢 Métrique  ──▶  📈 Graphique
                                         │
                                         └──▶  🔔 Alerte ──▶ 📨 Canal (mail, Slack…)

La leçon 2 a présenté métriques et alertes en deux lignes. Ici, on les construit pour de bon.

Les métriques basées sur les logs en détail

Il en existe deux familles :

• Système : fournies par Google, en lecture seule. Exemple : logging.googleapis.com/log_entry_count, le nombre d’entrées par log et par sévérité.
• Définies par l’utilisateur (user-defined) : celles que tu crées. Leur type Cloud Monitoring est toujours logging.googleapis.com/user/NOM.

Une métrique utilisateur a l’un de ces deux types :

Un compteur simple se crée en une commande :

gcloud logging metrics create api_5xx_count \
  --description="Réponses 5xx de api-commandes" \
  --log-filter='resource.type="cloud_run_revision"
resource.labels.service_name="api-commandes"
httpRequest.status>=500'

gcloud logging metrics list
gcloud logging metrics describe api_5xx_count

Pour une distribution ou des labels, il faut un fichier de configuration (YAML ou JSON, au format LogMetric) passé avec --config-from-file. Voici la latence de l’API, découpée par code HTTP :

# latence.yaml
name: api_latency
description: Latence des requêtes de api-commandes (secondes)
filter: |
  resource.type="cloud_run_revision"
  resource.labels.service_name="api-commandes"
  httpRequest.latency:*
valueExtractor: REGEXP_EXTRACT(httpRequest.latency, "([0-9.]+)s")
labelExtractors:
  status: EXTRACT(httpRequest.status)
bucketOptions:
  exponentialBuckets:
    numFiniteBuckets: 64
    growthFactor: 2.0
    scale: 0.01
metricDescriptor:
  metricKind: DELTA
  valueType: DISTRIBUTION
  unit: s
  labels:
    - key: status
      valueType: STRING

gcloud logging metrics create api_latency --config-from-file=latence.yaml

• valueExtractor : la valeur à ranger. EXTRACT(champ) prend tout le champ, REGEXP_EXTRACT(champ, regex) en garde le groupe capturant. Une valeur qui ne se convertit pas en nombre est ignorée.
• labelExtractors : une série par valeur distincte. Ici, une par code HTTP.
• bucketOptions : les tranches de l’histogramme (10 ms, 20 ms, 40 ms…).

Une métrique ne compte qu’à partir de sa création, jamais les logs déjà stockés. Génère un peu de trafic, attends quelques minutes, puis vérifie via le menu ⋮ de la page Log-based Metrics, entrée View in Metrics Explorer.

Construire le tableau de bord dans la console

Le chemin dans la console Google Cloud :

1. Monitoring > Dashboards, puis Create custom dashboard.
2. Add widget, type Metric, puis cherche logging/user/api_5xx_count.
3. Règle l’agrégation (somme par minute, ou 95e percentile pour la latence), puis Apply.
4. Add widget encore, cette fois un widget de logs : les entrées d’un filtre, affichées dans le tableau de bord.
5. Save.

Depuis Metrics Explorer, Save as > Dashboard chart fait la même chose.

Le tableau de bord en code

Pour l’équipe, mieux vaut un fichier JSON dans git : relu en revue, recréé à l’identique ailleurs. Le squelette, avec les 5xx et le panneau de logs :

{
  "displayName": "api-commandes : santé",
  "mosaicLayout": {
    "columns": 48,
    "tiles": [
      {
        "width": 24, "height": 16,
        "widget": {
          "title": "Réponses 5xx par minute",
          "xyChart": {
            "dataSets": [{
              "plotType": "LINE",
              "minAlignmentPeriod": "60s",
              "timeSeriesQuery": {
                "timeSeriesFilter": {
                  "filter": "metric.type=\"logging.googleapis.com/user/api_5xx_count\" resource.type=\"cloud_run_revision\"",
                  "aggregation": {
                    "alignmentPeriod": "60s",
                    "perSeriesAligner": "ALIGN_DELTA",
                    "crossSeriesReducer": "REDUCE_SUM"
                  }
                }
              }
            }]
          }
        }
      },
      {
        "xPos": 24, "width": 24, "height": 16,
        "widget": {
          "title": "Erreurs récentes",
          "logsPanel": {
            "filter": "resource.labels.service_name=\"api-commandes\" severity>=ERROR",
            "resourceNames": ["projects/mon-projet-dev"]
          }
        }
      }
    ]
  }
}

# Valider sans rien créer, puis créer
gcloud monitoring dashboards create --config-from-file=dashboard.json --validate-only
gcloud monitoring dashboards create --config-from-file=dashboard.json

La grille mosaicLayout fait ici 48 colonnes. Chaque tuile a une position (xPos, yPos), une taille et un widget. Pour la latence : api_latency et ALIGN_PERCENTILE_95.

Le tableau de bord concret d’une API

Quatre graphiques, quatre questions. Pas plus pour commencer.

Le troisième graphique vient d’Observability Analytics, vu en leçon 3. Tu écris la requête, tu affiches le résultat en graphique, puis Save to dashboard :

SELECT JSON_VALUE(json_payload.message) AS message, COUNT(*) AS nb
FROM `mon-projet-dev.global._Default._AllLogs`
WHERE severity = 'ERROR'
GROUP BY message
ORDER BY nb DESC
LIMIT 10

Pas de métrique, donc pas de risque de cardinalité. Attention : les filtres au niveau du tableau de bord ne s’appliquent pas à ces graphiques SQL.

Alerte sur un log ou alerte sur une métrique ?

Deux sortes d’alertes se créent à partir des logs :

Les deux envoient vers des canaux de notification (notification channels) : e-mail, Slack, PagerDuty, webhook, Pub/Sub. On les configure une fois dans Monitoring > Alerting, puis on les réutilise.

Contre la fatigue d’alerte (les alertes qu’on finit par ignorer) :

• Alerte sur un symptôme vu par l’utilisateur (taux de 5xx, latence), pas sur chaque ligne ERROR.
• Limite les notifications d’une alerte basée sur les logs : une toutes les 5 minutes au plus, pas une par entrée.
• Mets une durée au seuil d’une alerte métrique, pour ignorer un pic isolé.
• Écris la documentation de l’alerte : quoi regarder, quel tableau de bord ouvrir.

Les bonnes pratiques

• Peu de graphiques, chacun répond à une question.
• Nomme les métriques de façon régulière (api_5xx_count, api_latency) : on les retrouve d’un coup dans Metrics Explorer.
• Versionne dashboard.json et les fichiers de métriques dans git, et teste d’abord sur un projet de dev avec --validate-only.

Vérifie ta compréhension

À toi de jouer

1. Crée le compteur api_5xx_count avec gcloud logging metrics create et —log-filter, puis vérifie-le avec gcloud logging metrics describe.

2. Génère quelques erreurs, attends quelques minutes, puis ouvre la métrique avec View in Metrics Explorer.

3. Crée la distribution api_latency depuis un fichier YAML et affiche son 95e percentile.

4. Écris dashboard.json, valide-le avec —validate-only, crée-le, puis commite le fichier.

5. Ajoute le top 10 des messages d’erreur avec Save to dashboard depuis Observability Analytics.

6. Crée une alerte sur api_5xx_count avec un seuil et une durée, reliée à un canal de notification.

🗂 Fiche de référence associée : Google Cloud et Cloud Logging — antisèche.