Journalisation

Lorsque vous développez un type d'application, vous souhaitez généralement consigner des informations afin de diagnostiquer les défaillances lors du développement, d'identifier et de diagnostiquer les problèmes des clients, ainsi qu'à d'autres fins.

Apps Script propose trois mécanismes différents pour la journalisation:

  • Le journal d'exécution d'Apps Script intégré Ce journal est léger et diffuse en temps réel, mais ne dure que peu de temps.

  • L'interface Cloud Logging dans la console développeur, qui fournit des journaux qui sont conservés plusieurs jours après leur création.

  • L'interface Error Reporting de la console développeur, qui collecte et enregistre les erreurs qui se produisent pendant l'exécution du script

Ces fonctionnalités sont décrites dans les sections suivantes. Outre ces mécanismes, vous pouvez également créer votre propre code enregistreur qui, par exemple, écrit des informations dans une feuille de calcul ou une base de données JDBC Logging.

Utiliser le journal d'exécution Apps Script

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

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

Ces journaux sont destinés à des vérifications simples lors du développement et du débogage et ne persistent pas très longtemps.

Prenons l'exemple de la fonction suivante:

utilitaires/logging.gs
/**
 * 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);
  try {
    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);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed with error %s', err.message);
  }
}

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

16/09/2013:50:42:193

Cloud Logging

Apps Script fournit également un accès partiel au service Cloud Logging de Google Cloud Platform (GCP). Lorsque vous avez besoin d'une journalisation persistante pendant plusieurs jours ou d'une solution de journalisation plus complexe pour un environnement de production multi-utilisateur, Cloud Logging est la solution de choix. Consultez la page Quotas et limites de Cloud Logging pour en savoir plus sur la conservation des données et les autres détails des quotas.

Si vous avez besoin d'un quota de journalisation plus important, vous pouvez envoyer une demande de quota Google Cloud Platform. Pour cela, vous devez avoir accès au projet Cloud Platform utilisé par votre script.

Utiliser Cloud Logging

Les journaux cloud sont associés au projet GCP associé à votre script Apps Script. Vous pouvez afficher une version simplifiée de ces journaux dans le tableau de bord Apps Script.

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

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

Vous pouvez consigner des chaînes, des chaînes formatées et même des objets JSON à l'aide des fonctions fournies par le service Apps Script console.

L'exemple suivant montre comment utiliser le service console pour consigner des informations dans la suite d'opérations Cloud.

utilitaires/logging.gs
/**
 * 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 utilisateur actives

Les clés utilisateur temporaires temporaires constituent un moyen pratique de repérer les utilisateurs uniques dans les entrées Cloud Log sans révéler leur identité. Les clés sont fournies par script et changent environ une fois par mois pour renforcer la sécurité au cas où un utilisateur révèle son identité à un développeur, par exemple lorsqu'il signale un problème.

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

  • Vous n'avez pas besoin d'ajouter quoi que ce soit à votre journalisation, elles sont déjà présentes !
  • Elles ne nécessitent pas d'autorisation utilisateur.
  • Elles protègent la confidentialité des utilisateurs.

Pour rechercher des clés utilisateur actives temporaires dans vos entrées Cloud Log, affichez vos journaux Cloud dans la console GCP. Vous ne pouvez le faire que si votre projet de script utilise un projet GCP standard auquel vous avez accès. Une fois que vous avez ouvert le projet GCP dans la console, sélectionnez une entrée de journal qui vous intéresse et développez-la pour afficher metadata > labels > script.googleapis.com/user_key.

Vous pouvez également obtenir la clé utilisateur temporaire temporaire en appelant Session.getTemporaryActiveUserKey() dans votre script. Pour utiliser cette méthode, vous pouvez afficher la clé auprès de l'utilisateur lorsqu'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 à Cloud Logging des exceptions non gérées dans le code de votre projet de script, ainsi qu'une trace de la pile.

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

  1. Ouvrez le projet Apps Script.
  2. À gauche, cliquez sur Exécutions .
  3. En haut, cliquez sur Ajouter un filtre > État.
  4. Cochez les cases Échec et Expiration du délai.

Vous pouvez également afficher les exceptions journalisées dans la console GCP si votre projet de script utilise un projet GCP 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:

  1. Ouvrez le projet de script.
  2. À gauche, cliquez sur Paramètres du projet .
  3. Cochez la case Consigner les exceptions non détectées dans la suite 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. Vous pouvez afficher vos rapports d'erreurs Cloud dans la console GCP. Si vous êtes invité à "Configurer Error Reporting", cela signifie que votre script n'a pas encore enregistré d'exceptions. Aucune configuration n'est nécessaire au-delà de l'activation de la journalisation des exceptions.

Exigences concernant la journalisation

Aucune exigence n'est requise concernant l'utilisation du journal d'exécution intégré.

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