Logowanie

Tworząc aplikację dowolnego rodzaju, często warto zapisywać w dzienniku informacje, które pomagają diagnozować błędy na etapie programowania, wykrywać i diagnozować problemy klientów oraz do innych celów.

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

  • Wbudowany dziennik wykonywania Apps Script. Ten dziennik jest niewielki i przesyła się strumieniowo w czasie rzeczywistym, ale istnieje tylko przez krótki czas.

  • interfejs Cloud Logging w konsoli programisty, który udostępnia logi przechowywane przez wiele dni po ich utworzeniu.

  • Interfejs Raportowanie błędów w Konsoli Play, który zbiera i zapisuje błędy występujące, gdy skrypt działa.

Opisujemy je w kolejnych sekcjach. Oprócz tych mechanizmów możesz też utworzyć własny kod rejestratora, który na przykład zapisuje informacje w arkuszu kalkulacyjnym logowania lub bazie danych JDBC.

Korzystanie z dziennika wykonywania Apps Script

Podstawowym sposobem logowania w Apps Script jest użycie wbudowanego logu wykonywania. Aby wyświetlić te logi, u góry edytora kliknij Dziennik wykonywania. Gdy uruchamiasz funkcję lub używasz debugera, logi są przesyłane strumieniowo w czasie rzeczywistym.

Możesz użyć usług logowania Logger lub console we wbudowanym logu wykonywania.

Te logi są przeznaczone do prostych kontroli podczas programowania i debugowania oraz nie są trwałe.

Przyjrzyjmy się na przykład tej funkcji:

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

Po uruchomieniu tego skryptu z wpisami „2” i „john@example.com” zapisywane są te logi:

[16-09-12 13:50:42:193 PDT] Wysyłanie e-mailem wiersza danych 2 na adres jan@example.com
[16-09-12 13:50:42:271 PDT] Wiersz 2 dane: 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 wymagasz logowania, które działa przez kilka dni, lub bardziej złożonego rozwiązania do logowania w środowisku produkcyjnym z wieloma użytkownikami, Cloud Logging jest najlepszym wyborem. Przeczytaj artykuł o limitach Cloud Logging, aby dowiedzieć się więcej o limitach przechowywania danych i innych danych.

Jeśli potrzebujesz większego limitu logowania, możesz przesłać prośbę dotyczącą limitu w 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łączone do projektu Google Cloud powiązanego z Twoim Apps Script. Uproszczoną wersję tych dzienników możesz wyświetlić w panelu Apps Script.

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

Podczas rejestrowania warto unikać zapisywania danych osobowych użytkownika, np. adresów e-mail. Logi Cloud są automatycznie oznaczane etykietami aktywnych kluczy użytkownika, za pomocą których w razie potrzeby możesz znaleźć komunikaty logu konkretnego użytkownika.

Za pomocą funkcji dostępnych w usłudze Apps Script console możesz rejestrować ciągi tekstowe, sformatowane ciągi tekstowe, a nawet obiekty JSON.

Z przykładu poniżej dowiesz się, jak użyć usługi console do logowania informacji 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 aktywnych użytkowników

Tymczasowe aktywne klucze użytkowników to wygodny sposób na wykrywanie unikalnych użytkowników we wpisach Cloud Log bez ujawniania ich tożsamości. Klucze są przypisane do skryptu i zmieniają się mniej więcej raz w miesiącu, aby zapewnić dodatkowe bezpieczeństwo, jeśli użytkownik ujawni swoją tożsamość deweloperowi (np. podczas zgłaszania problemu).

Tymczasowe klucze aktywnych użytkowników są lepsze od rejestrowania identyfikatorów, takich jak adresy e-mail, ponieważ:

  • Nie musisz niczego dodawać do swoich logów. Te dane są już tam dostępne.
  • Nie wymagają one autoryzacji użytkownika.
  • Chronią prywatność użytkownika.

Aby znaleźć tymczasowe aktywne klucze użytkowników we wpisach Cloud Log, wyświetl logi Cloud w konsoli Google Cloud. Możesz to zrobić tylko wtedy, gdy 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 logu i rozwiń go, aby wyświetlić metadane > etykiety > script.googleapis.com/user_key.

Możesz też uzyskać tymczasowy klucz aktywnego użytkownika, wywołując w skrypcie Session.getTemporaryActiveUserKey(). Jednym ze sposobów użycia tej metody jest wyświetlenie klucza użytkownikowi, gdy uruchamia on skrypt. Użytkownicy mogą wtedy uwzględnić klucze podczas zgłaszania problemów, aby zidentyfikować odpowiednie logi.

Logowanie wyjątków

Logowanie wyjątków wysyła nieobsłużone wyjątki w kodzie projektu skryptu do Cloud Logging wraz ze zrzutem stosu.

Aby wyświetlić dzienniki wyjątków, wykonaj te czynności:

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

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

Włącz logowanie wyjątków

Logowanie wyjątków jest domyślnie włączone w nowych projektach. Aby włączyć rejestrowanie wyjątków w starszych projektach, wykonaj te czynności:

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

Raportowanie błędów

Logowanie wyjątków automatycznie integruje się z usługą Cloud Error Reporting, która agreguje i wyświetla błędy wygenerowane w Twoim skrypcie. Raporty o błędach Google Cloud możesz wyświetlać w konsoli Google Cloud. Jeśli zobaczysz prośbę o skonfigurowanie usługi Error Reporting, oznacza to, że Twój skrypt nie zarejestrował jeszcze żadnych wyjątków. Nie jest wymagana żadna konfiguracja poza włączeniem logowania wyjątków.

Wymagania dotyczące logowania

Nie ma wymagań dotyczących korzystania z wbudowanego dziennika wykonywania.

Uproszczoną wersję logów Cloud możesz wyświetlić w panelu Apps Script. Aby jednak w pełni wykorzystać możliwości usługi Cloud Logging i raportowania błędów, musisz mieć dostęp do projektu GCP skryptu. Jest to możliwe tylko wtedy, gdy projekt skryptu korzysta ze standardowego projektu Google Cloud.