Journalisation

Lorsque vous développez n'importe quel type d'application, vous avez souvent besoin de consigner des informations diagnostiquer les défaillances pendant le développement, 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 diffuse les données en temps réel, mais ne persiste que pendant peu de temps.

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

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

Celles-ci sont décrites 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 à une feuille de calcul de journalisation ou base de données JDBC.

Utiliser le journal d'exécution d'Apps Script

Pour vous connecter à Apps Script, vous pouvez utiliser la fonction intégrée journal d'exécution. Pour afficher ces journaux, de l'éditeur, cliquez sur Journal d'exécution. Lorsque vous exécutez une fonction ou utilisez la les journaux sont diffusés en temps réel.

Vous pouvez utiliser la méthode Logger ou services de journalisation console dans la un journal d'exécution intégré.

Ces journaux servent à 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:

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);
  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 "[e-mail]" la les journaux suivants sont écrits:

[16-09-12 13:50:42:193 PDT] Envoi de la ligne de données 2 par e-mail à [e-mail]
[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 à Google Cloud Platform (GCP). Service Cloud Logging. Lorsque vous nécessitent une journalisation plus complexe ; adaptée à un environnement de production multi-utilisateur, Cloud Logging est la solution de prédilection de votre choix. Consultez la page sur les quotas et limites de Cloud Logging. pour en savoir plus sur la conservation des données et d'autres informations sur les 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 Projet Cloud Platform que votre script utilise.

Remarque :Cloud Logging fournit un certain nombre de services, en plus du stockage des journaux, tels que des alertes et des métriques. Ces services ne sont pas disponibles pour le moment depuis Apps Script.

Utiliser Cloud Logging

Les journaux Cloud sont associés au projet Google Cloud associées à votre script Apps Script. Vous pouvez consulter une version simplifiée de ces 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 Console GCP et vous offre plus d'options d'affichage et de filtrage.

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

Lors de la consignation, une bonne pratique en matière de confidentialité est d'éviter d'enregistrer des données d'informations sur l'utilisateur, telles que son adresse e-mail. Les journaux cloud sont automatiquement étiquetées avec clés utilisateur actives vous pouvez utiliser pour 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 de la classe fournies par Apps Script Service console.

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

utils/logging.gs

Afficher sur GitHub

/**
 * 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 d'utilisateurs actifs temporaires constituent un moyen pratique de repérer les utilisateurs uniques dans les entrées Cloud Log sans révéler l'identité de ces utilisateurs. Clés par script et sont modifiés environ une fois par mois pour renforcer Un utilisateur doit-il révéler son identité à un développeur, par exemple lorsqu'il signale un problème.

Les clés utilisateur actives temporaires sont plus efficaces que les identifiants de journalisation tels que l'adresse e-mail pour les raisons suivantes:

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

Pour trouver des clés utilisateur actives temporaires dans vos entrées Cloud Log, 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 auxquelles vous avez accès. Une fois le projet Google Cloud ouvert dans la console, sélectionnez une entrée de journal qui vous intéresse et développez-la pour afficher métadonnées > étiquettes > script.googleapis.com/user_key.

Vous pouvez également obtenir la clé d'utilisateur actif 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'ils exécutent votre script. Les utilisateurs peuvent ensuite choisir d'inclure leurs clés lorsque vous signalez des problèmes pour vous aider à identifier les journaux pertinents.

Journalisation des exceptions

La journalisation des exceptions envoie des 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:

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 Failed (Échec) et Timed out (Expiration du délai).

Vous pouvez également afficher les exceptions consignées dans la console GCP. si votre projet de script utilise projet Google Cloud standard auxquelles 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 une exception des 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 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 produites dans votre script. Vous pouvez Afficher vos rapports d'erreurs Cloud dans la console Google Cloud 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 au-delà Activer la journalisation des exceptions

Exigences concernant la journalisation

L'utilisation du journal d'exécution intégré n'est pas obligatoire.

Vous pouvez afficher une version simplifiée des journaux Cloud dans la Tableau de bord Apps Script Toutefois, pour pour exploiter pleinement Cloud Logging et 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 ;