Logging

Saat mengembangkan aplikasi apa pun, catat informasi log untuk membantu mendiagnosis kesalahan selama pengembangan, untuk mengidentifikasi dan mendiagnosis masalah pelanggan, dan untuk tujuan lainnya.

Google Apps Script menyediakan tiga mekanisme berbeda untuk logging:

  • Log eksekusi Apps Script bawaan. Log ini ringan dan di-streaming secara real time, tetapi hanya bertahan dalam waktu singkat.

  • Antarmuka Cloud Logging di Konsol Developer, yang menyediakan log yang tetap ada selama beberapa hari setelah dibuat.

  • Antarmuka Error Reporting di Konsol Developer, yang mengumpulkan dan mencatat error yang terjadi saat skrip Anda berjalan.

Hal ini dijelaskan di bagian berikut. Selain mekanisme ini, buat kode logger Anda sendiri yang, misalnya, menulis informasi ke Spreadsheet atau database JDBC.

Menggunakan log eksekusi Apps Script

Pendekatan dasar untuk mencatat aktivitas login di Apps Script adalah dengan menggunakan log eksekusi bawaan. Untuk melihat log ini, di bagian atas editor, klik Log eksekusi. Saat Anda menjalankan fungsi atau menggunakan debugger, log akan di-streaming secara real time.

Gunakan layanan logging Logger atau console di log eksekusi bawaan.

Log ini ditujukan untuk pemeriksaan selama pengembangan dan proses debug, dan tidak bertahan lama.

Misalnya, perhatikan fungsi ini:

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

Saat skrip ini dijalankan dengan input "2" dan "john@example.com", log berikut akan ditulis:

> [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 juga memberikan akses sebagian ke layanan Cloud Logging Google Cloud. Jika Anda memerlukan pencatatan log yang tetap ada selama beberapa hari, atau memerlukan solusi pencatatan log yang lebih kompleks untuk lingkungan produksi multi-pengguna, Cloud Logging adalah pilihan yang lebih baik. Lihat kuota dan batas Cloud Logging untuk mengetahui retensi data dan detail kuota lainnya.

Untuk meminta kuota logging yang lebih besar, kirim permintaan kuota Google Cloud. Hal ini mengharuskan Anda memiliki akses ke project Cloud Platform yang digunakan skrip Anda.

Cloud Logging menyediakan sejumlah layanan di luar penyimpanan log, seperti pemberitahuan dan metrik. Layanan ini tidak tersedia dari Apps Script.

Menggunakan Cloud Logging

Log cloud dilampirkan ke project Google Cloud yang terkait dengan Apps Script Anda. Lihat versi sederhana dari log ini di dasbor Apps Script.

Untuk memanfaatkan sepenuhnya Cloud Logging dan kemampuannya, gunakan project Google Cloud standar dengan project skrip Anda. Dengan begitu, Anda dapat mengakses log Cloud secara langsung di Konsol Google Cloud dan mendapatkan lebih banyak opsi penayangan dan pemfilteran.

Jika Anda menggunakan runtime Rhino, Cloud Logging tidak mendukung layanan Logger Apps Script. Sebagai gantinya, gunakan layanan console.

Saat mencatat aktivitas, sebaiknya hindari pencatatan informasi pribadi tentang pengguna, seperti alamat email. Log cloud secara otomatis diberi label dengan kunci pengguna aktif untuk menemukan pesan log pengguna tertentu jika diperlukan.

String log, string yang diformat, dan bahkan objek JSON menggunakan fungsi yang disediakan oleh layanan console Apps Script.

Contoh berikut menunjukkan cara menggunakan layanan console untuk mencatat informasi di 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.
}

Kunci pengguna aktif

Kunci pengguna aktif sementara memberikan cara mudah untuk menemukan pengguna unik dalam entri Cloud Log tanpa mengungkapkan identitas pengguna tersebut. Kunci ini bersifat per skrip dan berubah kira-kira sebulan sekali untuk memberikan keamanan tambahan jika pengguna mengungkapkan identitasnya kepada developer, misalnya saat melaporkan masalah.

Kunci pengguna aktif sementara lebih unggul daripada ID logging seperti alamat email karena:

  • Anda tidak perlu menambahkan apa pun ke logging; semuanya sudah ada di sana.
  • Tidak memerlukan otorisasi pengguna.
  • Mereka melindungi privasi pengguna.

Untuk menemukan kunci pengguna aktif sementara di entri Cloud Log Anda, lihat log Cloud Anda di konsol Google Cloud. Lakukan ini hanya jika project skrip Anda menggunakan project Google Cloud standar yang dapat Anda akses. Setelah membuka project Google Cloud di konsol, pilih entri log yang menarik dan luaskan untuk melihat metadata > label > script.googleapis.com/user_key.

Untuk mendapatkan kunci pengguna aktif sementara, panggil Session.getTemporaryActiveUserKey dalam skrip Anda. Salah satu cara untuk menggunakan metode ini adalah dengan menampilkan kunci kepada pengguna saat mereka menjalankan skrip Anda. Kemudian, pengguna dapat memilih untuk menyertakan kunci mereka saat melaporkan masalah untuk membantu Anda mengidentifikasi log yang relevan.

Logging pengecualian

Pencatatan pengecualian mengirimkan pengecualian yang tidak tertangani dalam kode project skrip Anda ke Cloud Logging, beserta stack trace.

Untuk melihat log pengecualian, ikuti langkah-langkah berikut:

  1. Buka project Apps Script.
  2. Di sebelah kiri, klik Eksekusi .
  3. Di bagian atas, klik Tambahkan filter > Status.
  4. Centang kotak Gagal dan Waktu habis.

Lihat pengecualian yang dicatat dalam log di konsol Google Cloud jika project skrip Anda menggunakan project Google Cloud standar yang aksesnya Anda miliki.

Mengaktifkan logging pengecualian

Logging pengecualian diaktifkan secara default untuk project baru. Untuk mengaktifkan logging pengecualian untuk project lama, ikuti langkah-langkah berikut:

  1. Buka project skrip.
  2. Di sebelah kiri, klik Setelan Project .
  3. Pilih kotak centang Log uncaught exceptions to Cloud Operations.

Error Reporting

Pencatatan pengecualian otomatis terintegrasi dengan Cloud Error Reporting, layanan yang menggabungkan dan menampilkan error yang dihasilkan dalam skrip Anda. Lihat laporan error Cloud Anda di konsol Google Cloud. Anda tidak perlu mengonfigurasi Error Reporting secara manual atau membuat entri rekaman aktivitas. Apps Script otomatis mengisi kolom yang diperlukan saat pengecualian terjadi atau saat Anda menggunakan console.error dengan objek Error. Jika Anda diminta untuk "Menyiapkan Pelaporan Error", hal ini karena skrip Anda belum mencatat pengecualian apa pun. Tidak ada penyiapan yang diperlukan selain mengaktifkan logging pengecualian.

Persyaratan pencatatan log

Tidak ada persyaratan untuk menggunakan log eksekusi bawaan.

Melihat versi sederhana log Cloud di dasbor Apps Script. Namun, untuk memaksimalkan Cloud Logging dan pelaporan error, Anda harus memiliki akses ke project Google Cloud dari skrip. Hal ini hanya dapat dilakukan jika project skrip Anda menggunakan project Google Cloud standar.