Journalisation

Lorsque vous développez n'importe quel type d'application, consignez des informations de journalisation pour faciliter le diagnostic des erreurs pendant le développement, identifier et diagnostiquer les problèmes des clients, et à d'autres fins.

Google Apps Script fournit trois mécanismes de journalisation différents :

Le journal d'exécution Apps Script intégré. Ce journal est léger et diffusé en temps réel, mais il n'est conservé que pendant une courte période.
L'interface Cloud Logging de la console pour les développeurs, qui fournit des journaux conservés pendant plusieurs jours après leur création.
L'interface Error Reporting de la console pour les développeurs, qui collecte et enregistre les erreurs qui se produisent lors de l'exécution de votre script.

Ces mécanismes sont décrits dans les sections suivantes. En plus de ces mécanismes, créez votre propre code de journalisation qui, par exemple, écrit des informations dans une feuille de calcul de journalisation Spreadsheet ou JDBC database.

Utiliser le journal d'exécution Apps Script

Une approche de base de la journalisation dans Apps Script consiste à utiliser le journal d'exécution intégré. Pour afficher ces journaux, en haut de l'éditeur, cliquez sur Journal d'exécution. Lorsque vous exécutez une fonction ou utilisez le débogueur, les journaux sont diffusés en temps réel.

Utilisez les services de journalisation Logger ou console dans le journal d'exécution intégré.

Ces journaux sont destinés à des vérifications pendant le développement et le débogage, et ne sont pas conservés très longtemps.

Par exemple, considérez la fonction suivante :

utils/logging.gs

Afficher sur GitHub

/**
 * Logs Google Sheet information.
 * @param {number} rowNumber The spreadsheet row number.
 * @param {string} email The email to send with the row data.
 */
function emailDataRow(rowNumber, email) {
  console.log(`Emailing data row ${rowNumber} to ${email}`);
  const sheet = SpreadsheetApp.getActiveSheet();
  const data = sheet.getDataRange().getValues();
  const rowData = data[rowNumber - 1].join(" ");
  console.log(`Row ${rowNumber} data: ${rowData}`);
  MailApp.sendEmail(email, `Data in row ${rowNumber}`, rowData);
}

Lorsque ce script est exécuté avec les entrées "2" et "john@example.com", les journaux suivants sont écrits :

> [16-09-12 13:50:42:193 PDT] Emailing data row 2 to john@example.com
> [16-09-12 13:50:42:271 PDT] Row 2 data: Cost 103.24

Cloud Logging

Apps Script fournit également un accès partiel au service Google Cloud Cloud Logging. Lorsque vous avez besoin d'une journalisation conservée pendant plusieurs jours ou d'une solution de journalisation plus complexe pour un environnement de production multi-utilisateur, Cloud Logging est le choix privilégié. Consultez les quotas et limites de Cloud Logging pour la conservation des données et d'autres informations sur les quotas.

Pour demander un quota de journalisation plus élevé, envoyez une demande de quota Google Cloud. Pour cela, vous devez avoir accès au projet Cloud Platform utilisé par votre script.

Cloud Logging fournit un certain nombre de services au-delà du stockage des journaux, tels que des alertes et des métriques. Ces services ne sont pas disponibles à partir d'Apps Script.

Utiliser Cloud Logging

Les journaux Cloud sont associés au projet Google Cloud associé à votre Apps Script. Affichez une version simplifiée de ces journaux dans le tableau de bord Apps Script.

Pour profiter pleinement de Cloud Logging et de ses fonctionnalités, utilisez un projet Google Cloud standard avec votre projet de script. Vous pouvez ainsi accéder directement aux journaux Cloud dans la console Google Cloud et bénéficier de plus d'options d'affichage et de filtrage.

Si vous utilisez l'environnement d'exécution Rhino, Cloud Logging n'est pas compatible avec le service Apps Script Logger. Utilisez plutôt le console service.

Lors de la journalisation, il est recommandé de ne pas enregistrer d'informations personnelles sur l'utilisateur, telles que des adresses e-mail. Les journaux Cloud sont automatiquement libellés avec des clés d'utilisateur actif pour localiser les messages de journal d'un utilisateur spécifique si nécessaire.

Consignez des chaînes de journal, des chaînes mises en forme et même des objets JSON à l'aide des fonctions fournies par le service Apps Script console.

L'exemple suivant montre comment utiliser le console service pour consigner des informations dans Cloud Operations.

utils/logging.gs

Afficher sur GitHub

/**
 * A placeholder function to be timed.
 * @param {Object} parameters
 */
function myFunction(parameters) {
  // Placeholder for the function being timed.
}

/**
 * Logs the time taken to execute 'myFunction'.
 */
function measuringExecutionTime() {
  // A simple INFO log message, using sprintf() formatting.
  console.info("Timing the %s function (%d arguments)", "myFunction", 1);

  // Log a JSON object at a DEBUG level. The log is labeled
  // with the message string in the log viewer, and the JSON content
  // is displayed in the expanded log structure under "jsonPayload".
  const parameters = {
    isValid: true,
    content: "some string",
    timestamp: new Date(),
  };
  console.log({ message: "Function Input", initialData: parameters });
  const label = "myFunction() time"; // Labels the timing log entry.
  console.time(label); // Starts the timer.
  try {
    myFunction(parameters); // Function to time.
  } catch (e) {
    // Logs an ERROR message.
    console.error(`myFunction() yielded an error: ${e}`);
  }
  console.timeEnd(label); // Stops the timer, logs execution duration.
}

Clés d'utilisateur actif

Les clés d'utilisateur actif temporaires permettent d'identifier facilement les utilisateurs uniques dans les entrées de journal Cloud sans révéler leur identité. Les clés sont propres à chaque script et changent environ une fois par mois pour renforcer la sécurité si un utilisateur révèle son identité à un développeur, par exemple lors du signalement d'un problème.

Les clés d'utilisateur actif temporaires sont supérieures aux identifiants de journalisation tels que les adresses e-mail, car :

Vous n'avez rien à ajouter à votre journalisation : elles sont déjà là !
Elles ne nécessitent pas d'autorisation de l'utilisateur.
Elles protègent la confidentialité des utilisateurs.

Pour trouver des clés d'utilisateur actif temporaires dans vos entrées de journal Cloud, consultez vos journaux Cloud dans la console Google Cloud. Ne procédez ainsi que si votre projet de script utilise un projet Google Cloud standard auquel vous avez accès. Une fois que vous avez ouvert le projet Google Cloud dans la console, sélectionnez une entrée de journal qui vous intéresse et développez-la pour afficher métadonnées > libellés > script.googleapis.com/user_key.

Pour obtenir la clé d'utilisateur actif temporaire, appelez Session.getTemporaryActiveUserKey dans votre script. Vous pouvez par exemple afficher la clé à l'utilisateur pendant qu'il exécute votre script. Les utilisateurs peuvent ensuite choisir d'inclure leurs clés lorsqu'ils signalent des problèmes pour vous aider à identifier les journaux pertinents.

Journalisation des exceptions

La journalisation des exceptions envoie les exceptions non gérées dans le code de votre projet de script à Cloud Logging, ainsi qu'une trace de la pile.

Pour afficher les journaux d'exceptions, procédez comme suit :

Ouvrez le projet Apps Script.
Sur la gauche, cliquez sur Exécutions .
En haut de la page, cliquez sur Ajouter un filtre > État.
Cochez les cases Échec et Délai dépassé.

Affichez les exceptions consignées dans la console Google Cloud si votre projet de script utilise un projet Google Cloud standard auquel vous avez accès.

Activer la journalisation des exceptions

La journalisation des exceptions est activée par défaut pour les nouveaux projets. Pour activer la journalisation des exceptions pour les anciens projets, procédez comme suit :

Ouvrez le projet de script.
Sur la gauche, cliquez sur Paramètres du projet .
Cochez la case Consigner les exceptions non détectées dans Cloud Operations.

Error Reporting

La journalisation des exceptions s'intègre automatiquement à Cloud Error Reporting, un service qui agrège et affiche les erreurs générées dans votre script. Affichez vos rapports d'erreurs Cloud dans la console Google Cloud. Vous n'avez pas besoin de configurer manuellement Error Reporting ni de créer des entrées de trace. Apps Script renseigne automatiquement les champs obligatoires lorsqu'une exception est générée ou lorsque vous utilisez console.error avec un objet Error. Si vous êtes invité à "Configurer Error Reporting", c'est parce que votre script n'a pas encore consigné d'exceptions. Aucune configuration n'est requise en plus de l'activation de la journalisation des exceptions.

Exigences concernant la journalisation

Aucune exigence n'est requise pour utiliser le journal d'exécution intégré.

Affichez une version simplifiée des journaux Cloud dans le tableau de bord Apps Script. Toutefois, pour tirer le meilleur parti de Cloud Logging et d'Error Reporting, vous devez avoir accès au projet Google Cloud du script. Cela n'est possible que si votre projet de script utilise un projet Google Cloud standard.

Journalisation Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.