Logowanie

Podczas tworzenia dowolnego rodzaju aplikacji rejestruj informacje, które pomogą Ci w diagnozowaniu błędów na etapie programowania, identyfikowaniu i rozwiązywaniu problemów klientów oraz w innych celach.

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

Wbudowany dziennik wykonania Apps Script. Ten dziennik jest lekki i przesyłany strumieniowo w czasie rzeczywistym, ale jest przechowywany tylko przez krótki czas.
Interfejs Cloud Logging w Konsoli Play, który zawiera logi przechowywane przez wiele dni po ich utworzeniu.
Interfejs Raportowanie błędów w Konsoli Play, który zbiera i rejestruje błędy występujące podczas działania skryptu.

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

Korzystanie z dziennika wykonywania Apps Script

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

W wbudowanym dzienniku wykonania możesz używać usług rejestrowania Logger lub console.

Te logi są przeznaczone do sprawdzania podczas programowania i debugowania i nie są przechowywane zbyt długo.

Weźmy na przykład tę funkcję:

utils/logging.gs

Wyświetl w GitHubie

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

Gdy ten skrypt jest uruchamiany z danymi wejściowymi „2” i „john@example.com”, zapisywane są te dzienniki:

> [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 zapewnia też częściowy dostęp do usługi Google Cloud Cloud Logging. Jeśli potrzebujesz rejestrowania, które będzie trwało kilka dni, lub bardziej złożonego rozwiązania do rejestrowania w środowisku produkcyjnym z wieloma użytkownikami, lepszym wyborem będzie Cloud Logging. Więcej informacji o czasie przechowywania danych i innych limitach znajdziesz w artykule Limity i limity Cloud Logging.

Aby poprosić o dodatkowy limit logowania, prześlij prośbę o zwiększenie limitu w Google Cloud. Wymaga to dostępu do projektu Cloud Platform, z którego korzysta skrypt.

Cloud Logging oferuje wiele usług poza przechowywaniem logów, takich jak alerty i dane. Te usługi są niedostępne w Apps Script.

Korzystanie z Cloud Logging

Dzienniki Cloud są dołączone do projektu Google Cloud powiązanego z Twoim skryptem 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 funkcji, używaj w projekcie skryptu standardowego projektu Google Cloud. Dzięki temu możesz uzyskać dostęp do logów Cloud bezpośrednio w konsoli Google Cloud i masz więcej opcji wyświetlania i filtrowania.

Jeśli używasz środowiska wykonawczego Rhino, Cloud Logging nie obsługuje usługi Apps ScriptLogger. Zamiast tego użyj usługi console.

Podczas logowania warto unikać zapisywania jakichkolwiek danych osobowych użytkownika, takich jak adresy e-mail. Dzienniki w chmurze są automatycznie oznaczane kluczami aktywnych użytkowników, aby w razie potrzeby można było znaleźć wiadomości w dzienniku konkretnego użytkownika.

Ciągi logu, sformatowane ciągi znaków, a nawet obiekty JSON przy użyciu funkcji udostępnianych przez usługę console Apps Script.

Poniższy przykład pokazuje, jak używać usługi console do rejestrowania informacji w Cloud Operations.

utils/logging.gs

Wyświetl w GitHubie

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

Aktywne klucze użytkownika

Tymczasowe klucze aktywnych użytkowników to wygodny sposób na identyfikowanie unikalnych użytkowników we wpisach w 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 zabezpieczenie w sytuacji, gdy użytkownik ujawni swoją tożsamość deweloperowi, np. podczas zgłaszania problemu.

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

Nie musisz niczego dodawać do logowania – te informacje już tam są.
Nie wymagają autoryzacji użytkownika.
Chronią prywatność użytkowników.

Aby znaleźć tymczasowe klucze aktywnych użytkowników w swoich wpisach w logach Cloud, wyświetl logi Cloud w konsoli Google Cloud. Zrób to tylko wtedy, gdy projekt skryptu korzysta ze standardowego projektu w chmurze Google, do którego masz dostęp. Po otwarciu projektu w chmurze Google Cloud w konsoli wybierz interesujący Cię wpis logu i rozwiń go, aby wyświetlić metadane > etykiety > script.googleapis.com/user_key.

Aby uzyskać tymczasowy klucz aktywnego użytkownika, wywołaj w skrypcie funkcję Session.getTemporaryActiveUserKey. Jednym ze sposobów użycia tej metody jest wyświetlanie klucza użytkownikowi podczas działania skryptu. Użytkownicy mogą wtedy dołączyć swoje klucze podczas zgłaszania problemów, aby ułatwić Ci identyfikację odpowiednich dzienników.

Rejestrowanie wyjątków

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

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

Otwórz projekt Apps Script.
Po lewej stronie kliknij Wykonania .
U góry kliknij Dodaj filtr > Stan.
Zaznacz pola wyboru Nieudane i Przekroczono limit czasu.

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

Włącz logowanie 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:

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

Error Reporting

Rejestrowanie wyjątków jest automatycznie integrowane z Cloud Error Reporting, czyli usługą, która agreguje i wyświetla błędy generowane w skrypcie. Wyświetlaj raporty o błędach w Cloud w konsoli Google Cloud. Nie musisz ręcznie konfigurować raportowania błędów ani tworzyć wpisów śledzenia. Apps Script automatycznie wypełnia wymagane pola, gdy zostanie zgłoszony wyjątek lub gdy użyjesz console.error z obiektem Error. Jeśli pojawi się prośba o „Skonfigurowanie raportowania błędów”, oznacza to, że skrypt nie zarejestrował jeszcze żadnych wyjątków. Nie wymaga konfiguracji poza włączeniem logowania wyjątków.

Wymagania dotyczące rejestrowania

Korzystanie z wbudowanego dziennika wykonania nie wymaga spełnienia żadnych warunków.

Wyświetlać uproszczoną wersję dzienników Cloud w panelu Apps Script. Aby jednak w pełni korzystać z Cloud Logging i raportowania błędów, musisz mieć dostęp do projektu w chmurze Google Cloud, w którym znajduje się skrypt. Jest to możliwe tylko wtedy, gdy projekt skryptu korzysta ze standardowego projektu w chmurze Google.

Logowanie Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.