Logowanie

Podczas tworzenia aplikacji często chcesz rejestrować informacje, aby diagnozować błędy podczas tworzenia, identyfikować i diagnozować problemy klientów oraz w innych celach.

Apps Script udostępnia 3 różne mechanizmy rejestrowania:

  • wbudowany dziennik wykonania Apps Script; Ten dziennik jest lekki i przesyła dane w czasie rzeczywistym, ale przechowywany jest tylko przez krótki czas.

  • Interfejs Cloud Logging w Konsoli programisty, który udostępnia dzienniki, które są przechowywane przez wiele dni po ich utworzeniu.

  • interfejs zgłaszania błędów w Konsoli programisty, który zbiera i rejestruje błędy występujące podczas działania skryptu;

Opisują je kolejne sekcje. Oprócz tych mechanizmów możesz też tworzyć własny kod rejestrujący, który na przykład zapisuje informacje w arkuszu kalkulacyjnym lub bazie danych JDBC.

Korzystanie z dziennika wykonywania Apps Script

Podstawowym podejściem do rejestrowania w Apps Script jest korzystanie z wbudowanego dziennika wykonania. Aby wyświetlić te logi, u góry edytora kliknij Dziennik wykonywania. Gdy uruchomisz funkcję lub użyjesz debugera, dzienniki będą przesyłane w czasie rzeczywistym.

Wbudowany dziennik wykonania może korzystać z usług rejestrowania Logger lub console.

Te logi są przeznaczone do prostych kontroli podczas tworzenia i debugowania. Nie są one przechowywane zbyt długo.

Weź pod uwagę na przykład tę funkcję:

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

Gdy ten skrypt jest uruchamiany z danymi wejściowymi „2” i „john@example.com”, generuje następujące logi:

[16-09-12 13:50:42:193 PDT] Wysyłanie e-maila z danymi z drugiego wiersza na adres john@example.com
[16-09-12 13:50:42:271 PDT] Dane z drugiego wiersza: koszt 103,24

Cloud Logging

Apps Script zapewnia też częściowy dostęp do usługi Cloud Logging w Google Cloud Platform (GCP). Jeśli potrzebujesz logowania, które trwa kilka dni, lub bardziej złożonego rozwiązania do logowania w środowisku produkcyjnym dla wielu użytkowników, lepszym rozwiązaniem będzie logowanie w chmurze. Więcej informacji o czasie przechowywania danych i innych limitach znajdziesz w limitach i kwotach Cloud Logging.

Jeśli potrzebujesz większej ilości miejsca na logi, możesz przesłać prośbę o limit Google Cloud Platform. Wymaga to dostępu do projektu Cloud Platform, którego używa Twój skrypt.

Korzystanie z Cloud Logging

Logi Cloud są dołączane do projektu Google Cloud powiązanego z Twoim plikiem Apps Script. Uproszczoną wersję tych logów możesz wyświetlić w panelu Apps Script.

Aby w pełni korzystać z Cloud Logging i jego możliwości, użyj standardowego projektu Google Cloud w swoim projekcie skryptu. Dzięki temu możesz uzyskiwać dostęp do logów Cloud bezpośrednio w konsoli GCP i mieć więcej opcji wyświetlania i filtrowania.

Podczas rejestrowania należy unikać rejestrowania jakichkolwiek danych osobowych użytkownika, takich jak adresy e-mail. Dzienniki w chmurze są automatycznie oznaczane kluczami aktywnych użytkowników, których można użyć do znalezienia wiadomości w dzienniku konkretnego użytkownika w razie potrzeby.

Za pomocą funkcji udostępnianych przez usługę Apps Script console możesz rejestrować ciągi znaków, sformatowane ciągi znaków, a nawet obiekty JSON.

Ten przykład pokazuje, jak za pomocą usługi console rejestrować informacje w Cloud Operations.

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

Klucze aktywnego użytkownika

Tymczasowe klucze aktywnych użytkowników umożliwiają wygodne rozpoznawanie poszczególnych użytkowników w rekordach dziennika usługi Cloud, bez ujawniania ich tożsamości. Klucze są generowane dla każdego skryptu i zmieniają się mniej więcej raz w miesiącu, aby zapewnić dodatkowe bezpieczeństwo, gdyby użytkownik ujawnił swoją tożsamość deweloperowi, na przykład podczas zgłaszania problemu.

Tymczasowe klucze aktywnych użytkowników są lepsze niż identyfikatory logowania, takie jak adresy e-mail, ponieważ:

  • Nie musisz nic dodawać do logowania; są już tam dostępne.
  • Nie wymagają one autoryzacji użytkownika.
  • Chronią one prywatność użytkowników.

Aby znaleźć tymczasowo aktywne klucze użytkownika w rekordach logów Cloud, otwórz logi Cloud w konsoli Google Cloud. Możesz to zrobić tylko wtedy, gdy Twój projekt skryptu korzysta ze standardowego projektu Google Cloud, do którego masz dostęp. Po otwarciu projektu Google Cloud w konsoli wybierz interesujący Cię wpis w dzienniku i rozwiń go, aby wyświetlić metadata > labels > script.googleapis.com/user_key.

Możesz też uzyskać tymczasowy klucz aktywnego użytkownika, wywołując funkcję Session.getTemporaryActiveUserKey() w swoim skrypcie. Jedną z możliwości jest wyświetlenie klucza użytkownikowi podczas uruchamiania skryptu. Użytkownicy mogą dołączać klucze podczas zgłaszania problemów, aby ułatwić Ci identyfikację odpowiednich dzienników.

Logowanie wyjątków

Rejestrowanie wyjątków wysyła do Cloud Logging nieobsługiwane wyjątki w kodzie projektu skryptu wraz z wyświetleniem stosu.

Aby wyświetlić dzienniki wyjątków:

  1. Otwórz projekt Apps Script.
  2. Po lewej stronie kliknij Wykonania .
  3. U góry kliknij Dodaj filtr > Stan.
  4. Zaznacz pola wyboru Nieudane i Wystąpił limit czasu.

Jeśli projekt skryptu korzysta z standardowego projektu Google Cloud, do którego masz dostęp, możesz też wyświetlić zarejestrowane wyjątki w konsoli GCP.

Włączanie rejestrowania wyjątków

Rejestrowanie wyjątków jest domyślnie włączone w przypadku nowych projektów. Aby włączyć rejestrowanie wyjątków w starszych projektach:

  1. Otwórz projekt skryptu.
  2. Po lewej stronie kliknij Ustawienia projektu .
  3. Zaznacz pole wyboru Loguj niewykryte wyjątki w Cloud Operations.

Error Reporting

Logowanie wyjątków jest automatycznie integrowane z raportowaniem błędów w chmurze, czyli usługą, która agreguje i wyświetla błędy wygenerowane w skrypcie. Raporty o błędach w usłudze Cloud możesz wyświetlać w konsoli Google Cloud. Jeśli pojawi się prośba o „skonfigurowanie raportowania błędów”, oznacza to, że skrypt nie zapisał jeszcze żadnych wyjątków. Nie musisz nic konfigurować poza włączeniem rejestrowania wyjątków.

Wymagania dotyczące rejestrowania

Korzystanie z wbudowanego dziennika wykonania nie wymaga spełnienia żadnych wymagań.

Uproszczoną wersję logów Cloud możesz wyświetlić w panelu Apps Script. Aby jednak w pełni korzystać z funkcji Cloud Logging i raportowania błędów, musisz mieć dostęp do projektu GCP, w którym znajduje się skrypt. Jest to możliwe tylko wtedy, gdy projekt skryptu korzysta z standardowego projektu Google Cloud.