モニタリングとロギング

このドキュメントでは、スマートホームアクションの使用状況をモニタリングする方法と、イベントログにアクセスする方法について説明します。Google Cloud プロジェクトからこれらの機能にアクセスし、発生した問題のデバッグを行うことができます。

モニタリング

スマートホームアクションの使用状況に関する有用な指標は、Cloud Monitoring を使用して入手できます。ダッシュボードを作成してアラートを設定し、プログラムから指標データにアクセスできます。

サポートされている指標

Cloud Monitoring は、assistant_action_project リソースタイプをモニタリングして以下の指標を提供します。

指標	種類	説明
`smarthome_action/request_count`	DELTA	`execution_type`、`status`、`trait` とラベル付けされたインテントリクエストの数。 `execution_type`（文字列）: スマートホームインテントのタイプ。 `status`（文字列）: リクエストの結果。 `trait`（文字列）: スマートホームデバイスのトレイト。関連するトレイトがないイベントには、`UNKNOWN` というラベルが付けられます。
`smarthome_action/request_latencies`	CUMULATIVE、DISTRIBUTION	`execution_type`、`status`、`trait` とラベル付けされたインテントリクエストのレイテンシの分布。 `execution_type`（文字列）: スマートホームインテントのタイプ。 `status`（文字列）: リクエストの結果。 `trait`（文字列）: スマートホームデバイスのトレイト。関連するトレイトがないイベントには、`UNKNOWN` というラベルが付けられます。
`smarthome_action/num_active_users`	GAUGE	`trait` とラベル付けされた 1 日のアクティブユーザー。 `trait`（文字列）: スマートホームデバイスのトレイト。関連するトレイトがないイベントには、`UNKNOWN` というラベルが付けられます。
`smarthome_action/seven_day_active_users`	GAUGE	`trait` とラベル付けされた 1 週間のアクティブユーザー。 `trait`（文字列）: スマートホームデバイスのトレイト。関連するトレイトがないイベントには、`UNKNOWN` というラベルが付けられます。
`smarthome_action/twenty_eight_day_active_users`	GAUGE	`trait` とラベル付けされた 1 か月のアクティブユーザー。 `trait`（文字列）: スマートホームデバイスのトレイト。関連するトレイトがないイベントには、`UNKNOWN` というラベルが付けられます。
`smarthome_action/local_event_count`	DELTA	`intent`、`status`、`app version` とラベル付けされたローカルイベントの数。 `intent`（文字列）: ローカルフルフィルメントのインテントタイプ。 `status`（文字列）: イベントの結果。 `version`（文字列）: ローカルフルフィルメントのアプリバージョン。

指標へのアクセス

プロジェクトの Cloud Monitoring にアクセスする手順は次のとおりです。

Cloud Platform Console で、プロジェクトページに移動します。

プロジェクトページに移動
スマートホームプロジェクトを選択します。
[オペレーション] で、[モニタリング] > [Metrics Explorer] を選択します。

スマートホームダッシュボード

スマートホームプロジェクトでは、SmartHome Analytics ダッシュボードを利用できます。このダッシュボードでは、フルフィルメントの使用状況を示す以下の指標をクラウドとローカルに分けてグラフで確認できます。

グラフ	クラウド	ローカル	全体
リクエスト総数
リクエスト成功率
実行の内訳
クエリの内訳
95 パーセンタイルレイテンシ
アクティブユーザー数（1 日、1 週間、1 か月）
スマートホームエラーの内訳
ローカルフルフィルメントエラー（アプリバージョンごと）
リクエストの平均レイテンシ

プロジェクトのスマートホームダッシュボードにアクセスする手順は次のとおりです。

Actions Console でプロジェクトページに移動します。

Actions Console を開く
スマートホームプロジェクトを選択します。
[Analytics]（分析）タブを選択し、[Go to Google Cloud Platform]（Google Cloud Platform に移動）をクリックします。

ロギング

スマートホームアクションのイベントログにアクセスするには、Cloud Logging を使用します。Cloud Console でイベントログを確認したり、Google Cloud Pub/Sub を使用して他のアプリケーションにエクスポートしたりできます。

Cloud Logging は次のリソースタイプを提供します。

リソースタイプ	表示名	説明	ラベル
`assistant_action_project`	Google アシスタントアクションプロジェクト	アシスタントアクションに関連付けられた Google Cloud プロジェクトのコンテナ。	`project_id`: このリソースに関連付けられた Actions プロジェクトの ID（たとえば「my-project」）。

スマートホームイベント

Actions Console プロジェクトでは、Cloud Logging の以下のイベントがサポートされます。

Cloud Logging リソース	イベント
Google アシスタントアクションプロジェクト	SYNC インテントエラー
	QUERY インテントエラー
	EXECUTE インテントエラー
	通知エラー
	アカウントリンクエラー
	Local Home SDK HandlerError

同期ペイロード

次の表に、syncLog エントリのスキーマを示します。

プロパティ	説明
`requestId`	スマートホームインテントのリクエスト ID。
`httpLatencyMsec`	レスポンスを受信するまでにかかった時間。
`status`	インテントレスポンスのステータス。

実行ペイロード

次の表に、executionLog エントリのスキーマを示します。

プロパティ	説明
`requestId`	スマートホームインテントのリクエスト ID。
`latencyMsec`	レスポンスを受信するまでにかかった時間。
`executionType`	リクエストに使用されるトランスポート（「Cloud」、「Local」など）。
`actionType`	（省略可）ユーザーアクションのインジケーター（「QUERY」や「EXECUTE」など）。EXECUTE アクションの場合は、サポートされているトレイトのフルフィルメントのために発行されたコマンドが含まれます。
`trait`	（省略可）このユーザーアクションに関連付けられたトレイト。
`deviceTypes`	イベントの影響を受けるデバイスタイプのリスト。
`isSuccess`	リクエストが正常なレスポンスを受け取ったかどうか。
`fallbackToCloud`	ローカルフルフィルメントからのエラー後に、リクエストをクラウドフルフィルメントに転送するかどうか。
`statusType`	インテントレスポンスのステータス（「SUCCESS」、「PENDING」、「OFFLINE」など）。「ERROR」レスポンスの場合、このプロパティにはフルフィルメントによって提供された `errorCode` が含まれます。
`externalDebugString`	（省略可）このユーザーアクションに関連付けられたデバッグメッセージ。
`locale`	リクエストに関連付けられた言語コード。

通知ペイロード

次の表に、notificationLog エントリのスキーマを示します。

プロパティ	説明
`requestId`	通知リクエスト ID。
`structName`	通知構造体の名前（「ObjectDetection」など）。
`status`	通知のステータス。

ログへのアクセス

プロジェクトの Cloud Logging にアクセスする手順は次のとおりです。

Cloud Platform Console で、プロジェクトページに移動します。

プロジェクトページに移動
スマートホームプロジェクトを選択します。
[オペレーション] で、[ロギング] > [ログエクスプローラ] を選択します。

ロギングデータへのアクセスは、Actions プロジェクトの Identity and Access Management（IAM）で管理されます。ロギングデータの役割と権限について詳しくは、Cloud Logging のアクセス制御をご覧ください。

ログエントリは、Cloud Logging の保持ポリシーに従って 30 日間保持され、スケジュールに沿って削除されます。ログエクスプローラのインターフェースを使用し、必要に応じてエントリを削除することもできます。

ログのクエリ

Google Cloud Platform では、複数のシステムを使用してプロジェクトにログを送信します。必要なログを見つけるには、クエリを作成してログをフィルタする必要があります。クエリを作成するには、「期間」または「リソース」を指定するか、カスタムエントリを記述します。

「期間」を指定する場合は、ログエクスプローラで期間プルダウンをクリックし、いずれかのオプションを選択します。これにより、指定した期間内に発生したログがフィルタされます。

「リソース」を指定する場合は、ログエクスプローラのリソースプルダウンをクリックし、[Google アシスタントアクションプロジェクト] を選択します。これにより、スマートホームプロジェクトで発生したログがフィルタされます。

ログエクスプローラの [クエリ] フィールドを使用して、カスタムエントリを記述することもできます。たとえば次のカスタムエントリは、スマートホームプロジェクトで発生した照明関連のエラーを返します。

resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"

ログを効果的にクエリするその他の例については、クエリライブラリをご覧ください。

ログレベルの設定

スマートホームプロジェクトは、デフォルトでエラーログを受信するよう設定されています。また、成功ログも受け取ることもできます。これは、開発段階において複数のエージェントからすべてのログを収集したい場合に便利です。ロギングの無料割り当てを超過した場合、プロジェクトの追加料金が発生することがあります。

プロジェクトのログレベルは、次の方法で制御できます。

Actions Console でプロジェクトページに移動します。

Actions Console を開く
スマートホームプロジェクトを選択します。
[Develop]（開発）タブを選択し、サイドバーの [Actions]（アクション）をクリックします。
[Log control ingestion]（ログ制御の取り込み）プルダウンリストで [All]（すべて）を選択します。

ログの除外

ロギングクエリ言語を使用してログの除外を設定すると、ログをより柔軟にカスタマイズできます。ロギングクエリ言語はログエクスプローラでも使用されているため、ログエクスプローラを使用してクエリを作成できます。

除外フィルタを作成する手順については、こちらのガイドをご覧ください（_Default シンクの除外フィルタを設定します）。

ログベースの指標

ログベースの指標を使用すると、ログ内のパターンを追跡して分析できます。カスタムチャートを作成し、ログベースの指標にアラートを設定することもできます。

スマートホームのログベースの指標を初めて使用する際は、カウンタ指標の作成でログベースの指標の作成方法を参照してください。

学習用リソース

Google では、モニタリング機能とロギング機能を使用してスマートホームをデバッグする方法を理解するための追加の学習リソースを提供しています。

Codelab: スマートホームのデバッグ: スマートホームのクラウド統合をデバッグするためのクイックスタートガイドです。
Codelab: ローカルホームのデバッグ: スマートホームのローカル統合をデバッグするためのクイックスタートガイドです。

モニタリングとロギング