ロギング

あらゆる種類のアプリを開発する際は、開発中の障害の診断、お客様の事象の特定と診断、その他の目的のためにログ情報を記録します。

Google Apps Script には、次の 3 つのロギングメカニズムがあります。

組み込みの Apps Script 実行ログ。このログは軽量でリアルタイムでストリーミングされますが、保持されるのは短時間のみです。
デベロッパーコンソールの Cloud Logging インターフェース。作成後数日間保持されるログを提供します。
デベロッパーコンソールの Error Reporting インターフェース。スクリプトの実行中に発生したエラーを収集して記録します。

これらについては、以下のセクションで説明します。これらのメカニズムに加えて、たとえば、ロギングスプレッドシートや JDBC データベースに情報を書き込む独自のロガーコードを作成します。

Apps Script 実行ログを使用する

Apps Script でロギングを行う基本的な方法は、組み込みの実行ログを使用することです。これらのログを表示するには、エディタの上部にある [実行ログ] をクリックします。関数を実行するか、デバッガを使用すると、ログがリアルタイムでストリーミングされます。

組み込みの実行ログで Logger ロギングサービスまたは console ロギングサービスを使用します。

これらのログは、開発とデバッグ中のチェックを目的としており、保持される期間は長くありません。

たとえば、次の関数について考えてみましょう。

utils/logging.gs

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

このスクリプトを「2」と「john@example.com」の入力で実行すると、次のログが書き込まれます。

> [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 では、Google Cloud Cloud Loggingサービスへの部分的なアクセスも提供されます。数日間保持されるロギングが必要な場合や、マルチユーザーの本番環境でより複雑なロギングソリューションが必要な場合は、Cloud Logging を選択することをおすすめします。データの保持とその他の割り当ての詳細については、Cloud Logging の割り当てと上限をご覧ください。

ロギングの割り当ての増加をリクエストするには、 Google Cloud の割り当てリクエストを送信します。これを行うには、スクリプトで使用する Cloud Platform プロジェクトへのアクセス権が必要です。

Cloud Logging には、ログの保存以外にも、アラートや指標など、さまざまなサービスが用意されています。これらのサービスは Apps Script からは使用できません。

Cloud Logging を使用する

Cloud ログは、Apps Script に関連付けられた Google Cloud プロジェクトに添付されます。これらのログの簡略版は、Apps Script ダッシュボードで確認できます。

Cloud Logging とその機能を最大限に活用するには、スクリプトプロジェクトで標準の Google Cloud クラウドプロジェクトを使用します。これにより、 Google Cloud コンソールで Cloud ログに直接アクセスでき、表示とフィルタリングのオプションが増えます。

Rhino ランタイムを使用する場合、Cloud Logging は Apps Script Logger サービスをサポートしていません。代わりに、 console サービスを使用してください。

ロギングを行う際は、メールアドレスなど、ユーザーの個人情報を記録しないようにすることがプライバシー保護の観点から望ましいです。Cloud ログには、必要に応じて特定のユーザーのログメッセージを特定するために、有効なユーザーキーが自動的にラベル付けされます。

Apps Script のサービスで提供される関数を使用して、ログ文字列、書式設定された文字列、JSON オブジェクトを記録します。console

次の例は、 console サービスを使用して Cloud Operations に情報を記録する方法を示しています。

utils/logging.gs

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

有効なユーザーキー

一時的な有効なユーザーキーを使用すると、ユーザーの身元を明らかにすることなく、Cloud ログエントリで一意のユーザーを簡単に特定できます。キーはスクリプトごとに設定され、ユーザーがデベロッパーに身元を明かす場合（たとえば、問題を報告する場合）にセキュリティを強化するため、1 か月に 1 回程度変更されます。

一時的な有効なユーザーキーは、メールアドレスなどのロギング識別子よりも優れています。

ロギングに何も追加する必要はありません。すでに存在しています。
ユーザーの承認は必要ありません。
ユーザーのプライバシーを保護します。

Cloud ログエントリで一時的な有効なユーザーキーを見つけるには、 Google Cloud コンソールで Cloud ログを表示します。これは、スクリプトプロジェクトがアクセス権のある標準の Google Cloud プロジェクトを使用している場合にのみ行ってください。コンソールで Google Cloud プロジェクトを開いたら、目的のログエントリを選択して展開し、[メタデータ > ラベル > script.googleapis.com/user_key] を表示します。

一時的な有効なユーザーキーを取得するには、スクリプトで Session.getTemporaryActiveUserKey を呼び出します。このメソッドを使用する方法の 1 つは、ユーザーがスクリプトを実行しているときにキーを表示することです。ユーザーは、問題を報告する際にキーを含めることで、関連するログを特定できます。

例外ロギング

例外ロギングは、スクリプトプロジェクトコードで処理されなかった例外をスタックトレースとともに Cloud Logging に送信します。

例外ログを表示する手順は次のとおりです。

Apps Script プロジェクトを開きます。
左側の [実行] をクリックします。
上部の [フィルタを追加 > ステータス] をクリックします。
[失敗] チェックボックスと [タイムアウト] チェックボックスをオンにします。

スクリプトプロジェクトがアクセス権のある標準の Google Cloud プロジェクトを使用している場合は、 Google Cloud コンソールで記録された例外を表示します。

例外ロギングを有効にする

新しいプロジェクトでは、例外ロギングがデフォルトで有効になっています。古いプロジェクトで例外ロギングを有効にする手順は次のとおりです。

スクリプトプロジェクトを開きます。
左側の [Project Settings] をクリックします。
[キャッチされなかった例外を Cloud Operations に記録する] チェックボックスをオンにします。

Error Reporting

例外ロギングは、Cloud Error Reporting と自動的に統合されます。これは、スクリプトで発生したエラーを集計して表示するサービスです。Cloud エラーレポートは Google Cloud コンソールで確認できます。Error Reporting を手動で構成したり、トレースエントリを作成したりする必要はありません。例外がスローされた場合や、Error オブジェクトで console.error を使用した場合、Apps Script は必要なフィールドを自動的に入力します。[Error Reporting を設定] というメッセージが表示される場合は、スクリプトで例外が記録されていないことが原因です。例外ロギングを有効にする以外に設定は必要ありません。

ロギングの要件

組み込みの実行ログを使用するための要件はありません。

Cloud ログの簡略版は、 Apps Script ダッシュボードで確認できます。ただし、Cloud Logging と Error Reporting を最大限に活用するには、スクリプトの Google Cloud プロジェクトへのアクセス権が必要です。これは、スクリプトプロジェクトが標準の Google Cloud プロジェクトを使用している場合にのみ可能です。

ロギング コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。