Écrire et afficher les journaux

La journalisation est un outil important pour déboguer et surveiller le code. Cloud Functions vous permet d'utiliser le SDK de l'enregistreur pour Node.js ou Python, ou l'objet console standard pour le développement Web.

Cloud Logging est un service payant. Vous pouvez être facturé si vous dépassez le quota sans frais. Pour en savoir plus, consultez la section sur les tarifs de Cloud Logging.

Écrire des journaux

Utiliser le SDK de l'enregistreur Cloud Functions

Le SDK de journalisation Cloud Functions fournit une interface standard permettant de signaler l'état des fonctions à Cloud Logging. Vous pouvez utiliser ce SDK pour consigner des événements avec des données structurées, ce qui facilite l'analyse et la surveillance.

Importez à partir du sous-package logger :

Node.js

// All available logging functions
const {
  log,
  info,
  debug,
  warn,
  error,
  write,
} = require("firebase-functions/logger");
index.js

Python

from firebase_functions import logger
main.py

  • Les commandes logger.log() ont le niveau de journalisation INFO.

  • Les commandes logger.info() ont le niveau de journalisation INFO.

  • Les commandes logger.warn() ont le niveau de journalisation WARNING.

  • Les commandes logger.error() ont le niveau de journalisation ERROR.

  • Les commandes logger.debug() ont le niveau de journalisation DEBUG.

  • Les messages système internes ont le niveau de journalisation DEBUG.

Cet exemple montre une fonction qui écrit un journal de base :

Node.js

exports.helloWorld = onRequest((request, response) => {
  // sends a log to Cloud Logging
  log("Hello logs!");

  response.send("Hello from Firebase!");
});
index.js

Python

@https_fn.on_request()
def hello_world(req: https_fn.Request) -> https_fn.Response:
    # sends a log to Cloud Logging
    logger.log("Hello logs!")

    return https_fn.Response("Hello from Firebase!")
main.py

Utilisez différents niveaux de journalisation pour différents types de journaux dans le code de votre fonction. Les données structurées peuvent être associées à un journal en tant que dernier argument. Voici un exemple d'utilisation de chaque type de journal par une fonction :

Node.js

exports.getInspirationalQuote = onRequest(async (request, response) => {
  const db = getFirestore();
  const today = new Date();
  const quoteOfTheMonthRef = db
      .collection("quotes")
      .doc(`${today.getFullYear()}`)
      .collection("months")
      .doc(`${today.getMonth()}`);

  const DEFAULT_QUOTE =
      "You miss 100% of the shots you don't take. -Wayne Gretzky";
  let quote;
  try {
    const quoteOfTheMonthDocSnap = await quoteOfTheMonthRef.get();

    // Attach relevant debugging information with debug()
    debug("Monthly quote fetch result", {
      docRef: quoteOfTheMonthRef.path,
      exists: quoteOfTheMonthDocSnap.exists,
      createTime: quoteOfTheMonthDocSnap.createTime,
    });

    if (quoteOfTheMonthDocSnap.exists) {
      quote = quoteOfTheMonthDocSnap.data().text;
    } else {
      // Use warn() for lower-severity issues than error()
      warn("Quote not found for month, sending default instead", {
        docRef: quoteOfTheMonthRef.path,
        dateRequested: today.toLocaleDateString("en-US"),
      });

      quote = DEFAULT_QUOTE;
    }
  } catch (err) {
    // Attach an error object as the second argument
    error("Unable to read quote from Firestore, sending default instead",
        err);

    quote = DEFAULT_QUOTE;
  }

  // Attach relevant structured data to any log
  info("Sending a quote!", {quote: quote});
  response.json({inspirationalQuote: quote});
});
index.js

Python

@https_fn.on_request()
def get_inspirational_quote(req: https_fn.Request) -> https_fn.Response:
    firestore_client = firestore.client()
    today = datetime.date.today()
    quote_of_the_month_ref = (firestore_client.collection("quotes").doc(str(
        today.year)).collection("months").doc(str(today.month)))

    default_quote = "Python has been an important part of Google since the beginning, and remains so as the system grows and evolves."

    quote = None
    try:
        quote_of_the_month = quote_of_the_month_ref.get()

        # Attach relevant debugging information with debug()
        logger.debug(
            "Monthly quote fetch result",
            docRef=quote_of_the_month.path,
            exists=quote_of_the_month.exists,
            createTime=quote_of_the_month.createTime,
        )

        if quote_of_the_month.exists:
            quote = quote_of_the_month.to_dict()["text"]
        else:
            # Use warn() for lower-severity issues than error()
            logger.warn(
                "Quote not found for month, sending default instead",
                doc_reference=quote_of_the_month.path,
                date_requested=today.strftime("%Y-%m-%d"),
            )
            quote = default_quote
    except:
        e = sys.exc_info()[0]
        # Attach an error object as the second argument
        logger.error("Unable to read quote from Firestore, sending default instead", error=e)
        quote = default_quote

    # Attach relevant structured data to any log
    logger.info("Sending a quote!", quote=quote)
    return https_fn.Response("Hello from Firebase!")
main.py

Avec logger.write(), vous pouvez écrire des entrées de journal avec des niveaux de gravité supplémentaires : CRITICAL, ALERT et EMERGENCY. Consultez LogSeverity.

Node.js

exports.appHasARegression = onRegressionAlertPublished((event) => {
  write({
    // write() lets you set additional severity levels
    // beyond the built-in logger functions
    severity: "EMERGENCY",
    message: "Regression in production app",
    issue: event.data.payload.issue,
    lastOccurred: event.data.payload.resolveTime,
  });
});
index.js

Python

@crashlytics_fn.on_regression_alert_published()
def app_has_regression(alert: crashlytics_fn.CrashlyticsRegressionAlertEvent) -> None:
    logger.write(
        severity="EMERGENCY",
        message="Regression in production app",
        issue=alert.data.payload.issue,
        last_occurred=alert.data.payload.resolve_time,
    )
    print(alert)
main.py

Utiliser console.log

La solution recommandée pour la journalisation à partir d'une fonction consiste à utiliser le SDK du journaliseur pour votre plate-forme. Avec Node.js, vous pouvez utiliser des appels de journalisation JavaScript standards tels que console.log et console.error, mais vous devez d'abord exiger un module spécial pour corriger les méthodes standards afin qu'elles fonctionnent correctement :

require("firebase-functions/logger/compat");

Une fois que vous avez requis le module de compatibilité de l'enregistreur, vous pouvez utiliser les méthodes console.log() normalement dans votre code :

exports.helloError = functions.https.onRequest((request, response) => {
  console.log('I am a log entry!');
  response.send('Hello World...');
});
index.js
  • Les commandes console.log() ont le niveau de journalisation INFO.
  • Les commandes console.info() ont le niveau de journalisation INFO.
  • Les commandes console.warn() ont le niveau de journalisation ERROR.
  • Les commandes console.error() ont le niveau de journalisation ERROR.
  • Les messages système internes ont le niveau de journalisation DEBUG.

Afficher les journaux

Les journaux de Cloud Functions sont visibles dans la console Google Cloud, dans l'interface utilisateur Cloud Logging ou à l'aide de l'outil de ligne de commande firebase.

Utiliser la CLI Firebase

Pour afficher les journaux à l'aide de l'outil firebase, utilisez la commande functions:log :

firebase functions:log

Pour afficher les journaux d'une fonction spécifique, indiquez le nom de la fonction en tant qu'argument :

firebase functions:log --only <FUNCTION_NAME>

Pour consulter la liste complète des options d'affichage des journaux, consultez l'aide sur functions:log :

firebase help functions:log

Utiliser la console Google Cloud

Vous pouvez afficher les journaux des fonctions dans la console Google Cloud.

Utiliser l'UI Cloud Logging

Vous pouvez afficher les journaux de Cloud Functions dans l'interface utilisateur Cloud Logging.

Analyser des journaux

Cloud Logging propose une suite performante d'outils d'analyse des journaux que vous pouvez utiliser pour surveiller vos Cloud Functions.

Graphiques et alertes

Une fois que vous avez créé des métriques basées sur les journaux pour surveiller vos fonctions, vous pouvez créer des graphiques et des alertes basés sur ces métriques. Par exemple, vous pouvez créer un graphique pour visualiser la latence au fil du temps ou une alerte pour vous avertir si une certaine erreur se produit trop souvent.

Pour en savoir plus sur l'utilisation des métriques basées sur les journaux dans les graphiques et les règles d'alerte, consultez Créer des graphiques et des alertes.

Comprendre et utiliser les ID d'exécution

Par défaut, Cloud Run Functions (2e génération) permet l'exécution simultanée de plusieurs requêtes dans une même instance de fonction. Cela signifie que les journaux de différentes requêtes peuvent être entrelacés, ce qui rend plus difficile le suivi du flux d'une seule exécution.

Pour vous aider, les fonctions déployées à l'aide de la CLI Firebase version 13.33.0 et ultérieures sont automatiquement déployées avec la possibilité d'associer un ID d'exécution à chaque entrée de journal émise lors du traitement de cette exécution.

L'ID d'exécution identifie de manière unique tous les journaux associés à une même requête traitée par votre fonction. Aucune modification de code n'est requise. L'ID d'exécution sera automatiquement ajouté à vos journaux.

Pour désactiver la journalisation de l'ID d'exécution dans vos entrées de journal, définissez la variable d'environnement LOG_EXECUTION_ID sur "false" dans votre fichier .env.

Rechercher et corréler des journaux par ID d'exécution

Vous pouvez inspecter et corréler les journaux par ID d'exécution dans l'explorateur de journaux Cloud.

  1. Développez l'entrée de journal de votre fonction. L'ID d'exécution se trouve dans les données de journal structurées, imbriquées sous les libellés en tant que labels.execution_id.

  2. Cliquez sur la valeur de execution_id et sélectionnez "Afficher les entrées correspondantes" dans le menu déroulant pour afficher tous les autres journaux associés à la même exécution de fonction.

En utilisant l'ID d'exécution, vous pouvez regrouper tous les messages de journaux liés à une même requête, même si votre fonction gère plusieurs requêtes simultanément.

Améliorer la visibilité des journaux avec des champs de résumé personnalisés

Pour rendre l'ID d'exécution plus visible dans l'explorateur de journaux, vous pouvez l'ajouter en tant que [champ récapitulatif personnalisé][cloud-logging-preference]. Une fois que vous avez ajouté l'ID d'exécution en tant que champ récapitulatif, chaque entrée de journal affiche l'ID d'exécution sous forme de chip au début de la ligne de journal, comme le faisaient les fonctions de première génération pour tous les journaux.

Pour ajouter l'ID d'exécution au champ de résumé :

  1. Cliquez sur la valeur de l'ID d'exécution dans l'entrée de journal structurée sous labels.execution_id.

  2. Sélectionnez "Ajouter un champ à la ligne récapitulative" dans le menu déroulant.

Chaque entrée de journal affiche désormais executionId de manière visible dans le champ "Résumé", ce qui permet d'identifier et de regrouper plus facilement les journaux associés à un ID d'exécution spécifique.