Logowanie

Opracowując aplikacje, warto np. zapisywać informacje, które pomogą nam zdiagnozować błędy podczas programowania, zidentyfikować i zdiagnozować problemy klientów oraz realizować inne cele.

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

• Wbudowany dziennik wykonywania Apps Script. Ten dziennik jest mały i można go odtwarzać w czasie rzeczywistym, ale działa on tylko przez krótki czas.

• Interfejs Cloud Logging w konsoli programisty udostępnia logi, które są przechowywane przez wiele dni po utworzeniu.

• Interfejs Raportowanie błędów w Konsoli programisty, który zbiera i rejestruje błędy występujące podczas działania skryptu.

Zostały one opisane w poniższych sekcjach. Oprócz tych mechanizmów możesz też 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 logu wykonywania. Aby wyświetlić te logi, u góry edytora kliknij Dziennik wykonywania. Gdy uruchomisz funkcję lub użyjesz debugera, logi będą przesyłane strumieniowo w czasie rzeczywistym.

W wbudowanym logu wykonawczym możesz używać usług logowania Logger lub console.

Te logi są przeznaczone do prostych testów podczas programowania i debugowania, a ponadto nie są trwałe.

Przykład:

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);
  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 danymi wejściowymi „2” i „[e-mail]” zapisywane są te logi:

[16-09-12 13:50:42:193 PDT] E-mail dotyczący wiersza 2 wysłany na adres [e-mail]
[16-09-12 13:50:42:271 PDT] Dane w wierszu 2: 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 trwającego kilka dni lub potrzebujesz bardziej złożonego sposobu logowania w środowisku produkcyjnym wielu użytkowników, Cloud Logging jest dobrym rozwiązaniem. Zobacz Limity Cloud Logging, aby dowiedzieć się więcej o przechowywaniu danych i innych limitach.

Jeśli potrzebujesz więcej miejsca na logowanie, możesz przesłać prośbę o zwiększenie limitu w Google Cloud Platform. W tym celu musisz mieć dostęp do projektu Cloud Platform używanego przez Twój skrypt.

Uwaga: Cloud Logging zapewnia wiele innych usług niż przechowywanie logów, takich jak alerty i wskaźniki. Obecnie nie są one dostępne w Apps Script.

Korzystanie z Cloud Logging

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

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

Uwaga: jeśli używasz środowiska wykonawczego Rhino, Cloud Logging nie obsługuje usługi Apps Script Logger. Zamiast tego użyj usługi console.

Przy logowaniu należy unikać zapisywania danych osobowych użytkowników, takich jak adresy e-mail. Logi Cloud są automatycznie oznaczane aktywnymi kluczami użytkowników, które w razie potrzeby można zlokalizować.

Korzystając z funkcji dostępnych w usłudze Apps Script console, możesz rejestrować ciągi tekstowe, sformatowane ciągi znaków, a nawet obiekty JSON.

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

utils/logging.gs

Wyświetl w GitHubie

/**
 * 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żytkowników

Tymczasowe klucze aktywnych użytkowników to wygodny sposób na identyfikowanie unikalnych użytkowników we wpisach Cloud Logging bez ujawniania tożsamości tych użytkowników. Klucze są podzielone według skryptu i zmieniają się mniej więcej raz w miesiącu, aby zapewnić większe bezpieczeństwo, na przykład gdy użytkownik ujawni deweloperowi swoją tożsamość, na przykład podczas zgłaszania problemu.

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

• Nie musisz dodawać niczego do dziennika – są już one dostępne.
• Nie wymagają autoryzacji użytkownika.
• Chronią prywatność użytkowników.

Aby znaleźć tymczasowe aktywne klucze użytkowników we wpisach Cloud Logging, wyświetl logi Cloud w konsoli GCP. Możesz to zrobić tylko wtedy, gdy projekt skryptu korzysta ze standardowego projektu GCP, do którego masz dostęp. Po otwarciu projektu GCP w konsoli wybierz odpowiedni wpis logu i rozwiń go, aby wyświetlić metadane > etykiety > script.googleapis.com/user_key.

Możesz też uzyskać tymczasowy aktywny klucz użytkownika, wywołując skrypt Session.getTemporaryActiveUserKey() w swoim skrypcie. Jednym ze sposobów użycia tej metody jest wyświetlanie klucza użytkownikowi podczas wykonywania skryptu. Następnie użytkownicy mogą uwzględnić klucze podczas zgłaszania problemów, aby pomóc w zidentyfikowaniu odpowiednich logów.

Rejestrowanie wyjątków

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

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

1. Otwórz projekt Apps Script.
2. Po lewej stronie kliknij Uruchomienia .
3. U góry kliknij Dodaj filtr > Stan.
4. Zaznacz pola wyboru Failed (Niepowodzenie) i użyj limitu czasu.

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

Włącz logowanie wyjątków

Rejestrowanie wyjątków jest domyślnie włączone w nowych projektach. Aby włączyć logowanie 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 Zarejestruj nieobsłużone wyjątki dla operacji Cloud.

Raportowanie błędów

Rejestrowanie wyjątków automatycznie integruje się z Cloud Error Reporting, która gromadzi i wyświetla błędy wygenerowane w skrypcie. Raporty o błędach Cloud możesz wyświetlić w konsoli GCP Jeśli pojawi się prośba o skonfigurowanie usługi Error Reporting, oznacza to, że skrypt nie zarejestrował jeszcze żadnych wyjątków. Nie musisz nic konfigurować oprócz włączenia 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 w pełni wykorzystać możliwości 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 GCP.