Registro

Cuando desarrollas cualquier tipo de app, a menudo es necesario registrar información que ayude a diagnosticar fallas durante el desarrollo, identificar y diagnosticar problemas de los clientes y para otros fines.

Apps Script proporciona tres mecanismos diferentes para el registro:

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

• La interfaz de Cloud Logging en Developer Console, que proporciona registros que persisten durante muchos días después de su creación.

• La interfaz de Error Reporting de Developer Console, que recopila y registra los errores que se producen mientras se ejecuta la secuencia de comandos

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

Usa el registro de ejecución de Apps Script

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

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

Estos registros están diseñados para verificaciones simples durante el desarrollo y la depuración, y no persisten mucho.

Por ejemplo, considera esta función:

utils/logging.gs

Ver en 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);
  }
}

Cuando se ejecuta esta secuencia de comandos con las entradas "2" y "[e-mail]", se escriben los siguientes registros:

[16-09-12 13:50:42:193 PDT] Emailing data row 2 to [e-mail]
[16-09-12 13:50:42:271 PDT] Datos de la fila 2: Costo 103.24

Cloud Logging

Apps Script también proporciona acceso parcial al servicio Cloud Logging de Google Cloud Platform (GCP). Cuando necesitas registros que persisten durante varios días o necesitas 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 información sobre la retención de datos y otros detalles de las cuotas.

Si necesitas una cuota de registro mayor, puedes enviar una solicitud de cuota de Google Cloud Platform. Esto requiere que tengas acceso al proyecto de Cloud Platform que usa tu secuencia de comandos.

Nota: Cloud Logging proporciona una serie de servicios más allá del almacenamiento de registros, como alertas y métricas. En este momento, estos servicios no están disponibles desde Apps Script.

Usa Cloud Logging

Los registros de Cloud se adjuntan al proyecto de GCP asociado con Apps Script. Puedes ver una versión simplificada de estos registros en el panel de Apps Script.

Para aprovechar al máximo Cloud Logging y sus funciones, utiliza un proyecto de GCP estándar con tu proyecto de secuencia de comandos. Esto te permite acceder a los registros de Cloud directamente en GCP Console y más opciones para ver y filtrar.

Nota: Si usas el entorno de ejecución de Rhino, Cloud Logging no es compatible con el servicio Logger de Apps Script. En su lugar, usa el servicio console.

Para el registro, se recomienda evitar el registro de cualquier información personal sobre el usuario, como las direcciones de correo electrónico. Los registros de Cloud se etiquetan de forma automática con claves de usuario activas, que puedes usar para ubicar los mensajes de registro de un usuario específico cuando sea necesario.

Puedes registrar strings, strings 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 las operaciones en la nube.

utils/logging.gs

Ver en 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.
}

Claves de usuario activas

Las claves de usuario temporales activas proporcionan una forma conveniente de detectar usuarios únicos en las entradas de Cloud Logging sin revelar las identidades de esos usuarios. Las claves se usan por secuencia de comandos y cambian aproximadamente una vez al mes para proporcionar seguridad adicional en caso de que un usuario revele su identidad a un desarrollador, por ejemplo, mientras informa un problema.

Las claves de usuario temporales activas son superiores a los identificadores de registro como direcciones de correo electrónico debido a lo siguiente:

• No es necesario que agregues nada a tus registros, ya están ahí.
• 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 GCP Console. Puedes hacer esto solo si tu proyecto de secuencia de comandos usa un proyecto de GCP estándar al que tienes acceso. Una vez que hayas abierto el proyecto de GCP en la consola, selecciona una entrada de registro de interés y expándela para ver metadata > labels > script.googleapis.com/user_key.

También puedes llamar a Session.getTemporaryActiveUserKey() en tu secuencia de comandos para obtener la clave de usuario temporal activa. 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 relevantes.

Registro de excepciones

El registro de excepciones envía 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 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 Error y Se agotó el tiempo de espera.

También puedes ver las excepciones registradas en GCP Console si tu proyecto de secuencia de comandos usa un proyecto de GCP estándar al que tienes acceso.

Habilitar 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 la secuencia de comandos.
2. En el lado izquierdo, haz clic en Configuración del proyecto .
3. Selecciona la casilla de verificación Registrar excepciones no detectadas en Cloud Operations.

Informes de errores

El registro de excepciones se integra de forma automática en Cloud Error Reporting, un servicio que agrega y muestra los errores que se producen en tu secuencia de comandos. Puedes ver los informes de errores de Cloud en GCP Console. Si se te solicita "Configurar Error Reporting", esto se debe a que tu secuencia de comandos todavía no registró ninguna excepción. No se requiere configuración más allá de la habilitación del registro de excepciones.

Requisitos de registro

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

Puedes 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 los informes de errores, debes tener acceso al proyecto de GCP de la secuencia de comandos. Esto solo es posible si tu proyecto de secuencia de comandos usa un proyecto de GCP estándar.