Registro

Cuando desarrolles cualquier tipo de app, registra información para ayudar a diagnosticar fallas durante el desarrollo, identificar y diagnosticar problemas de los clientes, y para otros fines.

Google Apps Script proporciona tres mecanismos diferentes para el registro:

  • El registro de ejecución de Apps Script integrado Este registro es ligero y se transmite en tiempo real, pero solo persiste durante un período breve.

  • La interfaz de Cloud Logging en la consola para desarrolladores, que proporciona registros que persisten durante muchos días después de su creación

  • La interfaz de Error Reporting en la Consola para desarrolladores, que recopila y registra los errores que se producen mientras se ejecuta tu secuencia de comandos

Estos se describen en las siguientes secciones. Además de estos mecanismos, crea tu propio código de registro que, por ejemplo, escriba información en una hoja de cálculo de registro o una base de datos JDBC.

Cómo usar el registro de ejecución de Apps Script

Un enfoque básico para registrar en Apps Script es usar el registro de ejecución integrado. Para ver estos registros, haz clic en Registro de ejecución en la parte superior del editor. Cuando ejecutas una función o usas el depurador, los registros se transmiten en tiempo real.

Usa los servicios de registro Logger o console en el registro de ejecución integrado.

Estos registros están destinados a las verificaciones durante el desarrollo y la depuración, y no persisten por mucho tiempo.

Por ejemplo, considera esta función:

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}`);
  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);
}

Cuando esta secuencia de comandos se ejecuta con las entradas "2" y "john@example.com", se escriben los siguientes registros:

> [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 también proporciona acceso parcial al servicio de Cloud Logging de Google Cloud. Cuando necesitas registros que persistan durante varios días o una solución de registro más compleja para un entorno de producción multiusuario, Cloud Logging es la opción preferida. Consulta Cuotas y límites de Cloud Logging para obtener detalles sobre la retención de datos y otras cuotas.

Para solicitar más cuota de registro, envía una solicitud de cuota de Google Cloud. Para ello, debes tener acceso al proyecto de Cloud Platform que usa tu secuencia de comandos.

Cloud Logging proporciona varios servicios más allá del almacenamiento de registros, como alertas y métricas. Estos servicios no están disponibles en Apps Script.

Usar Cloud Logging

Los registros de Cloud se adjuntan al proyecto de Google Cloud asociado con tu secuencia de comandos de Apps Script. Consulta una versión simplificada de estos registros en el panel de Apps Script.

Para aprovechar al máximo Cloud Logging y sus capacidades, usa un proyecto estándar de Google Cloud con tu proyecto de secuencia de comandos. Esto te permite acceder a los registros de Cloud directamente en la consola de Google Cloud y te brinda más opciones de visualización y filtrado.

Si usas el entorno de ejecución de Rhino, Cloud Logging no admite el servicio Logger de Apps Script. En su lugar, usa el servicio console.

Cuando se registran datos, es una buena práctica de privacidad evitar registrar cualquier información personal sobre el usuario, como direcciones de correo electrónico. Los registros de Cloud se etiquetan automáticamente con claves de usuario activas para ubicar los mensajes de registro de un usuario específico cuando sea necesario.

Registra cadenas, cadenas con formato y hasta objetos JSON con las funciones que proporciona el servicio console de Apps Script.

En el siguiente ejemplo, se muestra cómo usar el servicio console para registrar información en Cloud Operations.

utils/logging.gs
/**
 * 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.
}

Claves de usuario activas

Las claves de usuario activo temporales proporcionan una forma conveniente de identificar usuarios únicos en las entradas de Cloud Logging sin revelar sus identidades. Las claves son por secuencia de comandos y cambian aproximadamente una vez al mes para brindar seguridad adicional en caso de que un usuario revele su identidad a un desarrollador, por ejemplo, cuando informa un problema.

Las claves de usuario activo temporales son mejores que los identificadores de registro, como las direcciones de correo electrónico, por los siguientes motivos:

  • No es necesario que agregues nada a tus registros, ya están allí.
  • No requieren autorización del usuario.
  • Protegen la privacidad del usuario.

Para encontrar claves de usuario activas temporales en tus entradas de Cloud Logging, consulta tus registros de Cloud en la consola de Google Cloud. Hazlo solo si tu proyecto de secuencia de comandos usa un proyecto estándar de Google Cloud al que tienes acceso. Una vez que hayas abierto el proyecto de Google Cloud en la consola, selecciona una entrada de registro de interés y expándela para ver metadata > labels > script.googleapis.com/user_key.

Para obtener la clave de usuario activo temporal, llama a Session.getTemporaryActiveUserKey en tu secuencia de comandos. Una forma de usar este método es mostrarle la clave al usuario mientras ejecuta tu secuencia de comandos. Luego, los usuarios pueden optar por incluir sus claves cuando informen problemas para ayudarte a identificar los registros pertinentes.

Registro de excepciones

El registro de excepciones envía las excepciones no controladas en el código de tu proyecto de secuencia de comandos a Cloud Logging, junto con un seguimiento de pila.

Para ver los registros de excepciones, sigue estos pasos:

  1. Abre el proyecto de Apps Script.
  2. A la izquierda, haz clic en Ejecuciones .
  3. En la parte superior, haz clic en Agregar un filtro > Estado.
  4. Selecciona las casillas de verificación Con errores y Tiempo agotado.

Consulta las excepciones registradas en la consola de Google Cloud si tu proyecto de secuencia de comandos usa un proyecto estándar de Google Cloud al que tienes acceso.

Habilita el registro de excepciones

El registro de excepciones está habilitado de forma predeterminada para los proyectos nuevos. Para habilitar el registro de excepciones en proyectos más antiguos, sigue estos pasos:

  1. Abre el proyecto de secuencia de comandos.
  2. A la izquierda, haz clic en Configuración del proyecto .
  3. Selecciona la casilla de verificación Registrar excepciones no detectadas en Cloud Operations.

Error Reporting

El registro de excepciones se integra automáticamente con Cloud Error Reporting, un servicio que agrega y muestra los errores que se producen en tu secuencia de comandos. Consulta tus informes de errores de Cloud en la consola de Google Cloud. No es necesario que configures manualmente Error Reporting ni que crees entradas de seguimiento. Apps Script completa automáticamente los campos obligatorios cuando se arroja una excepción o cuando usas console.error con un objeto Error. Si se te solicita que configures la función de informes de errores, es porque tu secuencia de comandos aún no registró ninguna excepción. No se requiere ninguna configuración adicional más allá de habilitar el registro de excepciones.

Requisitos de registro

No hay requisitos para usar el registro de ejecución integrado.

Ver una versión simplificada de los registros de Cloud en el panel de Apps Script Sin embargo, para aprovechar al máximo Cloud Logging y Error Reporting, debes tener acceso al proyecto de Google Cloud de la secuencia de comandos. Esto solo es posible si tu proyecto de secuencia de comandos usa un proyecto estándar de Google Cloud.