Ghi nhật ký

Khi phát triển bất kỳ loại ứng dụng nào, hãy ghi nhật ký thông tin để giúp chẩn đoán lỗi trong quá trình phát triển, xác định và chẩn đoán các vấn đề của khách hàng cũng như cho các mục đích khác.

Google Apps Script cung cấp 3 cơ chế ghi nhật ký:

Nhật ký thực thi Apps Script tích hợp sẵn. Nhật ký này có dung lượng nhẹ và phát trực tuyến theo thời gian thực, nhưng chỉ tồn tại trong một thời gian ngắn.
Giao diện Cloud Logging trong Bảng điều khiển dành cho nhà phát triển, cung cấp nhật ký tồn tại trong nhiều ngày sau khi được tạo.
Giao diện Error Reporting trong Bảng điều khiển dành cho nhà phát triển, thu thập và ghi lại các lỗi xảy ra khi tập lệnh của bạn đang chạy.

Những nội dung này được mô tả trong các phần sau. Ngoài các cơ chế này, hãy tạo mã trình ghi nhật ký của riêng bạn, chẳng hạn như ghi thông tin vào Bảng tính ghi nhật ký hoặc cơ sở dữ liệu JDBC.

Sử dụng nhật ký thực thi Apps Script

Một phương pháp cơ bản để ghi nhật ký trong Apps Script là sử dụng nhật ký thực thi tích hợp sẵn. Để xem các nhật ký này, ở đầu trình chỉnh sửa, hãy nhấp vào Nhật ký thực thi. Khi bạn chạy một hàm hoặc sử dụng trình gỡ lỗi, nhật ký sẽ phát trực tuyến theo thời gian thực.

Sử dụng một trong hai dịch vụ ghi nhật ký Logger hoặc console trong nhật ký thực thi tích hợp sẵn.

Các nhật ký này dùng để kiểm tra trong quá trình phát triển và gỡ lỗi, đồng thời không tồn tại quá lâu.

Ví dụ: hãy xem xét hàm này:

utils/logging.gs

Xem trên 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}`);
  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);
}

Khi tập lệnh này chạy với các giá trị đầu vào "2" và "john@example.com", các nhật ký sau sẽ được ghi:

> [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 cũng cung cấp quyền truy cập một phần vào dịch vụ Google Cloud Cloud Logging. Khi bạn cần ghi nhật ký tồn tại trong vài ngày hoặc cần một giải pháp ghi nhật ký phức tạp hơn cho môi trường sản xuất nhiều người dùng, thì Cloud Logging là lựa chọn ưu tiên. Xem hạn mức và giới hạn Cloud Logging để biết thông tin về thời gian lưu giữ dữ liệu và các thông tin khác về hạn mức.

Để yêu cầu tăng hạn mức ghi nhật ký, hãy gửi yêu cầu về hạn mức của Google Cloud. Bạn phải có quyền truy cập vào dự án Cloud Platform mà tập lệnh của bạn sử dụng.

Cloud Logging cung cấp một số dịch vụ ngoài việc lưu trữ nhật ký, chẳng hạn như cảnh báo và chỉ số. Bạn không thể sử dụng các dịch vụ này từ Apps Script.

Sử dụng Cloud Logging

Nhật ký trên đám mây được đính kèm vào dự án Google Cloud liên kết với Apps Script của bạn. Xem phiên bản đơn giản hoá của các nhật ký này trong trang tổng quan Apps Script.

Để tận dụng tối đa Cloud Logging và các tính năng của dịch vụ này, hãy sử dụng một dự án Google Cloud tiêu chuẩn với dự án tập lệnh của bạn. Điều này cho phép bạn truy cập trực tiếp vào nhật ký trên Cloud trong bảng điều khiển Cloud của Google và cung cấp cho bạn nhiều lựa chọn xem và lọc hơn.

Nếu bạn sử dụng môi trường thời gian chạy Rhino, thì Cloud Logging sẽ không hỗ trợ dịch vụ của Apps Script Logger. Thay vào đó, hãy sử dụng dịch vụ console.

Khi ghi nhật ký, bạn nên tuân thủ các biện pháp bảo mật quyền riêng tư để tránh ghi lại bất kỳ thông tin cá nhân nào về người dùng, chẳng hạn như địa chỉ email. Nhật ký trên đám mây sẽ tự động được gắn nhãn bằng các khoá người dùng đang hoạt động để xác định vị trí thông báo nhật ký của một người dùng cụ thể khi cần.

Ghi nhật ký chuỗi, chuỗi được định dạng và thậm chí cả đối tượng JSON bằng các hàm do dịch vụ console của Apps Script cung cấp.

Ví dụ sau đây cho biết cách sử dụng dịch vụ console để ghi nhật ký thông tin trong Cloud Operations.

utils/logging.gs

Xem trên GitHub

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

Khoá người dùng đang hoạt động

Khoá người dùng đang hoạt động tạm thời cung cấp một cách thuận tiện để phát hiện người dùng duy nhất trong các mục nhập Nhật ký trên đám mây mà không tiết lộ danh tính của những người dùng đó. Khoá này được tính theo từng tập lệnh và thay đổi khoảng một lần mỗi tháng để tăng cường bảo mật trong trường hợp người dùng tiết lộ danh tính của họ cho nhà phát triển, chẳng hạn như khi báo cáo vấn đề.

Khoá người dùng đang hoạt động tạm thời vượt trội hơn so với các giá trị nhận dạng ghi nhật ký như địa chỉ email vì:

Bạn không phải thêm bất cứ thứ gì vào nhật ký của mình; chúng đã có sẵn!
Chúng không yêu cầu người dùng uỷ quyền.
Chúng bảo vệ quyền riêng tư của người dùng.

Để tìm khoá người dùng đang hoạt động tạm thời trong các mục nhập nhật ký trên đám mây, hãy xem nhật ký trên đám mây trong bảng điều khiển Google Cloud. Chỉ thực hiện việc này nếu dự án tập lệnh của bạn đang sử dụng một dự án trên đám mây Google Cloud tiêu chuẩn mà bạn có quyền truy cập. Sau khi mở dự án trên đám mây của Google Cloud trong bảng điều khiển, hãy chọn một mục nhập nhật ký mà bạn quan tâm rồi mở rộng mục nhập đó để xem metadata > labels > script.googleapis.com/user_key.

Để lấy khoá người dùng đang hoạt động tạm thời, hãy gọi Session.getTemporaryActiveUserKey trong tập lệnh của bạn. Một cách để sử dụng phương thức này là hiển thị khoá cho người dùng trong khi họ đang chạy tập lệnh của bạn. Sau đó, người dùng có thể chọn đưa khoá của họ vào khi báo cáo vấn đề để giúp bạn xác định nhật ký có liên quan.

Ghi nhật ký ngoại lệ

Tính năng ghi nhật ký ngoại lệ sẽ gửi các ngoại lệ chưa được xử lý trong mã dự án tập lệnh của bạn đến Cloud Logging, cùng với dấu vết ngăn xếp.

Để xem nhật ký ngoại lệ, hãy làm theo các bước sau:

Mở dự án Apps Script.
Ở bên trái, hãy nhấp vào Thực thi .
Ở trên cùng, hãy nhấp vào Thêm bộ lọc > Trạng thái.
Chọn hộp đánh dấu Không thành công và Hết thời gian.

Xem các ngoại lệ đã ghi nhật ký trong bảng điều khiển Cloud nếu dự án tập lệnh của bạn đang sử dụng một dự án Google Cloud tiêu chuẩn mà bạn có quyền truy cập.

Bật tính năng ghi nhật ký ngoại lệ

Tính năng ghi nhật ký ngoại lệ được bật theo mặc định cho các dự án mới. Để bật tính năng ghi nhật ký ngoại lệ cho các dự án cũ hơn, hãy làm theo các bước sau:

Mở dự án tập lệnh.
Ở bên trái, hãy nhấp vào biểu tượng Cài đặt dự án .
Chọn hộp đánh dấu Ghi các ngoại lệ chưa nắm bắt được vào Cloud Operations.

Error Reporting

Tính năng ghi nhật ký ngoại lệ sẽ tự động tích hợp với Cloud Error Reporting, một dịch vụ tổng hợp và hiển thị các lỗi được tạo trong tập lệnh của bạn. Xem báo cáo lỗi trên đám mây trong bảng điều khiển Cloud. Bạn không cần định cấu hình Error Reporting theo cách thủ công hoặc tạo các mục nhập dấu vết. Apps Script sẽ tự động điền các trường bắt buộc khi một ngoại lệ được đưa ra hoặc khi bạn sử dụng console.error với một đối tượng Error. Nếu bạn được nhắc "Thiết lập Error Reporting", thì điều này có nghĩa là tập lệnh của bạn chưa ghi nhật ký bất kỳ ngoại lệ nào. Bạn không cần thiết lập gì ngoài việc bật tính năng ghi nhật ký ngoại lệ.

Yêu cầu về ghi nhật ký

Không có yêu cầu nào về việc sử dụng nhật ký thực thi tích hợp sẵn.

Xem phiên bản đơn giản hoá của nhật ký trên đám mây trong trang tổng quan Apps Script. Tuy nhiên, để tận dụng tối đa Cloud Logging và tính năng báo cáo lỗi, bạn phải có quyền truy cập vào dự án trên đám mây của tập lệnh trong Google Cloud. Bạn chỉ có thể thực hiện việc này nếu dự án tập lệnh của bạn đang sử dụng một dự án trên đám mây Google Cloud tiêu chuẩn.

Ghi nhật ký Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.