Journalisation

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

Apps Script propose trois mécanismes de journalisation différents:

  • Le journal d'exécution Apps Script intégré. Ce journal est léger et est diffusé en temps réel, mais ne persiste que pendant une courte période.

  • L'interface Cloud Logging de la Play Console, qui fournit des journaux conservés pendant plusieurs jours après leur création.

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

Ceux-ci sont décrits dans les sections suivantes. En plus de ces mécanismes, vous pouvez également créer votre propre code d'enregistreur qui, par exemple, écrit des informations dans une feuille de calcul de journalisation ou une base de données JDBC.

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, cliquez sur Execution log (Journal d'exécution) en haut de l'éditeur. Lorsque vous exécutez une fonction ou utilisez le débogueur, les journaux sont transmis 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 pendant le développement et le débogage. Ils ne conservent pas leur état très longtemps.

Prenons l'exemple de la fonction suivante:

utils/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-12 13:50:42:193 PDT] Envoi de données de ligne 2 à john@example.com
[16-09-12 13:50:42:271 PDT] Données de ligne 2: Coût 103,24

Cloud Logging

Apps Script fournit également un accès partiel au service Cloud Logging de Google Cloud Platform (GCP). Si vous avez besoin d'une journalisation qui persiste pendant plusieurs jours ou si vous avez besoin d'une solution de journalisation plus complexe pour un environnement de production multi-utilisateur, Cloud Logging est l'option à privilégier. Consultez la section Quotas et limites de Cloud Logging pour en savoir plus sur la conservation des données et les quotas.

Si vous avez besoin d'un quota de journalisation supérieur, vous pouvez envoyer une demande de quota Google Cloud Platform. Cette opération nécessite que vous ayez accès au projet Cloud Platform utilisé par votre script.

Utiliser Cloud Logging

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

Pour tirer pleinement parti de Cloud Logging et de ses fonctionnalités, utilisez un projet Google Cloud standard avec votre projet de script. Cela vous permet d'accéder aux journaux Cloud directement dans la console GCP et vous offre davantage d'options d'affichage et de filtrage.

Lors de la journalisation, il est recommandé d'éviter d'enregistrer des informations personnelles sur l'utilisateur, comme ses adresses e-mail. Les journaux Cloud sont automatiquement libellés avec des clés utilisateur actives. Vous pouvez les utiliser pour localiser les messages de journal d'un utilisateur spécifique si nécessaire.

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

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

utils/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 actives temporaires constituent un moyen pratique de repérer les utilisateurs uniques dans les entrées de journaux Cloud sans révéler leur identité. Les clés sont définies par script et changent environ une fois par mois pour renforcer la sécurité d'un utilisateur si un utilisateur révèle son identité à un développeur, par exemple lorsqu'il signale un problème.

Les clés utilisateur actives temporaires sont supérieures à la journalisation des identifiants tels que les adresses e-mail, pour les raisons suivantes:

  • Vous n'avez rien à ajouter à votre journalisation, les données sont déjà là.
  • Elles ne nécessitent pas l'autorisation de l'utilisateur.
  • Elles protègent la confidentialité des utilisateurs.

Pour rechercher des clés utilisateur temporaires actives dans vos entrées de journaux Cloud, affichez vos journaux Cloud dans la console Google Cloud. Vous ne pouvez effectuer cette opération 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 metadata > étiquettes > script.googleapis.com/user_key.

Vous pouvez également obtenir la clé utilisateur active temporaire en appelant Session.getTemporaryActiveUserKey() dans votre script. Une façon d'utiliser cette méthode consiste à présenter 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 afin de vous aider à identifier les journaux pertinents.

Journalisation des exceptions

La journalisation des exceptions envoie les exceptions non gérées du 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:

  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 Délai expiré.

Vous pouvez également afficher les exceptions enregistrées dans la console GCP 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 projets plus anciens, procédez comme suit:

  1. Ouvrez le projet de script.
  2. Sur la gauche, cliquez sur Paramètres du projet .
  3. Cochez la case Journaliser 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 regroupe et affiche les erreurs générées dans votre script. Vous pouvez consulter vos rapports d'erreurs Cloud dans la console Google Cloud. Si vous êtes invité à "Configurer Error Reporting", cela signifie que votre script n'a pas encore enregistré d'exceptions. Aucune configuration n'est requise en plus de l'activation de la journalisation des exceptions.

Exigences concernant la journalisation

Aucune condition requise pour utiliser le journal d'exécution intégré.

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