ロギング

あらゆる種類のアプリを開発する際に、開発中の障害の診断、お客様の問題の特定と診断、その他の目的で情報をログに記録することがよくあります。

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

  • 組み込みの Apps Script 実行ログ。このログは軽量でリアルタイムでストリーミングされますが、短時間しか保持されません。

  • Developer Console の Cloud Logging インターフェース。作成後数日間保持されるログを提供します。

  • デベロッパー コンソールの Error Reporting インターフェース。スクリプトの実行中に発生したエラーを収集して記録します。

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

Apps Script の実行ログを使用する

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

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

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

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

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

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

ロギング割り当てがさらに必要な場合は、Google Cloud Platform の割り当てリクエストを送信できます。これには、スクリプトで使用する Cloud Platform プロジェクトへのアクセス権が必要です。

Cloud Logging の使用

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

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

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

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

次の例は、console サービスを使用して 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.
}

アクティブなユーザーキー

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

一時的なアクティブ ユーザーキーは、メールアドレスなどのロギング識別子よりも優れています。理由は次のとおりです。

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

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

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

例外のロギング

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

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

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

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

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

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

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

Error Reporting

例外ロギングは、スクリプトで発生したエラーを集計して表示するサービスである Cloud Error Reporting と自動的に統合されます。Google Cloud コンソールで Cloud エラーレポートを表示できます。「Error Reporting を設定」というメッセージが表示された場合は、スクリプトでまだ例外がログに記録されていないことが原因です。例外ロギングを有効にする以外の設定は必要ありません。

ロギングの要件

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

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