1. 始める前に
スマートホームのデバッグ Codelab で説明したとおり、スマートホーム プロジェクトに指標とログをパブリッシュします。これらの指標は、スマートホーム アクションに問題があるかどうかを識別する際に役立ちます。またログは、そうした問題を解決するための詳細を確認するのに便利です。
プロジェクトに公開される指標に加え、Google Cloud Platform のログベースの指標を使用して独自の指標を生成することもできます。これにより、ログ内の特定のパターンをモニタリングし、品質の問題を効率的にデバッグできます。
前提条件
- Works with Smart Home を統合している
- スマートホームのデバッグの Codelab を完了している
学習内容
- スマートホーム エラーログを効果的にフィルタできるクエリを作成する方法
- ログベースの指標を作成してクエリから指標を生成する方法
- モニタリング用のログベースの指標からグラフやダッシュボードを作成する方法
2. ログを活用する
スマートホームの Codelab のデバッグで簡単に説明したように、ログを扱うことはプロジェクトを成功に導く鍵となります。Google Cloud Platform には、ログのモニタリングと分析に役立つ便利なツールが用意されています。プロジェクトで使用可能なすべてのログにアクセスするには、ログ エクスプローラを使用します。
ログにアクセスする
ログにアクセスするには、まず Google Cloud Platform にログインしてプロジェクトを選択します。次に、サイドメニューで [オペレーション] > [ロギング] > [ログ エクスプローラ] を選択して [ログ エクスプローラ] に移動します。ツールを開くと、次のような画面が表示されます。
ログ エクスプローラは、2 つの主なセクションで構成されています。上部のクエリビルダーにクエリを記述すると、クエリに一致する結果が下部のクエリ結果に表示されます。
デフォルトでは、Google のさまざまなコンポーネントからのログがプロジェクトに書き込まれます。スマートホーム統合からのログを識別して対処するには、カスタムクエリを記述する必要があります。
クエリを記述する
プロジェクトに公開されるログは、リソースタイプで識別できるようになっています。各リソースタイプは、Google 内のさまざまなプラットフォームを表します。スマートホーム プラットフォームからのログは、assistant_action_project リソースタイプとしてプロジェクトに公開されます。
また、ログの作成時には必ず重大度が割り当てられます。スマートホーム ログでは、エラーと例外を表すログには ERROR レベルを使用し、それ以外のログには DEBUG レベルを使用します。
一例として、下の図に記述されているのは、スマートホーム プラットフォームから出力されたエラー ログのみをフィルタするクエリです。
クエリの入力が完了したら、[クエリを実行] ボタンをクリックしてクエリを開始します。クエリを実行すると、スマートホーム統合からのエラーが表示されるはずです。
このログを見ると、ここ 1 時間ほどの間に何度もエラーが発生しています。1 つのエラーログが 1 つの行で表されています。個々のログをクリックすると、ネストされたフィールドが展開して詳しい情報が表示されます。
ヒストグラムを使用する
ログ エクスプローラはヒストグラム機能を備えており、クエリに一致するログの時間分布を簡単に表示できます。ヒストグラム機能を有効にするには、右上の [ページレイアウト] ボタンをクリックして [ヒストグラム] チェックボックスをオンにします。
有効にすると、クエリに一致するログの時間分布が表示されます。
上の図を見ると、ここ 1 時間ほどの間にエラーがまとまって発生している時間帯があり、午後 1 時 45 分頃、午後 2 時頃、午後 2 時 15 分頃に繰り返し発生しているようです。ヒストグラムは、タイムスタンプだけでは気付きにくいパターンを検出するのに便利です。
現在実行しているクエリでは、スマートホーム統合からのエラーがすべて表示されているだけで、ログは細かく識別されていません。しかし、特定のデバイスタイプやトレイトに起因するエラーパターンを追跡したい場合など、エラーを識別する必要に迫られることはよくあります。そうした場合に必要な、高度なクエリの作成方法を見ていきましょう。
高度なクエリ
スマートホームのイベントログをよく見ると、以下に挙げるようなさまざまなフィールドが含まれていることがわかります。
action
trait: ユーザーがターゲットとするデバイス トレイト（OnOff、StartStop、Brightness など）。actionType: トレイトの詳しい状態（On、Off、Pause、Stop、Resume など）
device
deviceType: ユーザーがターゲットとするデバイスタイプ（ライト、スイッチ、洗濯機など）
status
isSuccess: アクションの結果が成功したと見なされるかどうか（true または false）statusType: アクション結果のステータス コード（成功しなかった場合はエラーコード）externalDebugString: アクションのデバッグ文字列（エラーの詳細を示す）
その他のフィールド
以下の追加フィールドから情報を得ることもできます。
requestId: リクエストに関連付けられた固有の ID（Google による自動生成）executionType: リクエストで使用されているパス（Cloud または Local）latencyMsec: Google サーバー上のリクエストで検出されたレイテンシ（ミリ秒単位）locale: リクエストの送信元の言語 / 地域ペア（en-US、ja-JP など）
上記のトレイト フィールドを使用することで、ログを細かく識別することができます。次に示すクエリ例は、OnOff トレイトから送信されたエラーのみが含まれるように修正したものです。
resource.type="assistant_action_project" AND severity=ERROR AND jsonPayload.executionLog.executionResults.actionResults.action.trait="TRAIT_ON_OFF"
修正したクエリを実行すると、システムによってログが識別されて対応する結果が表示されます。
ここまでは、すべてのクエリを手動で実行してきました。この方法はエラーの状態を手早くチェックしたい場合には便利ですが、エラーパターンの推移をモニタリングしたい場合はあまり実用的ではありません。この処理を自動化してより長期間のデータをキャプチャするには、ログベースの指標を作成します。
3. ログベースの指標
ログベースの指標を使用すると、クエリに一致するログの数を時系列でカウントできます。これにより、ログ全体を通じたパターンを把握し、内在する問題を効果的に分析できます。
ログベースの指標を作成する
ログベースの指標を作成するには、[オペレーション] > [ロギング] > [ログベースの指標] に移動します。すでにプロジェクトで利用できるログベースの指標の一覧が表示されます。[指標を作成] ボタンをクリックすると、ログベースの指標の作成画面が表示されます。
主な指標タイプは 2 つあります。カウンタ指標は、クエリに一致するログの数をカウントします。分布指標は、基礎となる分布を追跡し、平均、中央値、95 パーセンタイルなどの統計演算を可能にします。
作成画面を下にスクロールすると、クエリを入力するためのフィルタ セクションが表示されます。
前のセクションで作成したクエリを、[フィルタの作成] のテキスト領域に貼り付けます。
resource.type="assistant_action_project" AND severity=ERROR AND jsonPayload.executionLog.executionResults.actionResults.action.trait="TRAIT_ON_OFF"
[ログをプレビュー] ボタンをクリックすると、フィルタに一致する過去のログを簡単に確認できます。完了したら、[指標を作成] ボタンをクリックして次のセクションに進みます。
ログベースの指標を表示する
これでログベースの指標が作成されました。作成した指標は、[ログベースの指標] ページの [ユーザー定義の指標] に表示されます。
ログベースの指標のその他メニューから [Metrics Explorer で表示する] を選択すると、ログベースの指標で収集されたデータを確認できます。
新たにエラーが発生すると、ログベースの指標によってキャプチャされ、Metrics Explorer のグラフ ウィンドウに表示されます。
カスタム ダッシュボードを使用したモニタリング
新しいログベースの指標が想定どおりに機能していることを確認したら、そのグラフビューをカスタム ダッシュボードに保存します。保存するには、[Metrics Explorer] の右上にある [グラフを保存] ボタンをクリックします。プロンプトが表示され、グラフの名前と保存先のダッシュボードを指定できます。
ダッシュボードに保存すると、グラフに簡単にアクセスできるようになります。プロジェクトで利用可能なダッシュボードを一覧で表示するには、[オペレーション] > [モニタリング] > [ダッシュボード] に移動します。
ここでは、「Codelab Dashboard」というダッシュボードに保存します。これを開くと、次の図のように表示されます。
ログベースの指標を表すグラフが表示され、新たに収集されたデータが描画されます。スマートホーム ログは、リアルタイムでプロジェクトに公開されます。新しいログが生成されると、直ちにログベースの指標に反映されます。
4. 完了
以上で、クエリをログベースの指標に変換し、モニタリング用にカスタム ダッシュボードに保存する方法を習得できました。
次のステップ
この Codelab で学んだことを活かして、追加リソースを参照しながら以下の演習に挑戦してみましょう。
- レイテンシなどの数値フィールドでログベースの指標を作成するには、分布指標の作成ガイドをご覧ください。
- Google Cloud が提供するサンプルクエリ ライブラリで、ログベースの指標に使用できる複雑なフィルタを確認する。