Telemetry Reporting

はじめに

このページでは、Service Control API v2 を使用して、Service Infrastructure に統合されたマネージド サービスのテレメトリー レポートを作成する方法について説明します。このチュートリアルは、サービスを Google Cloud に深く統合したいと考えているサービス プロデューサーを対象としています。

Service Infrastructure は、デベロッパーが API とサービスを作成、管理、保護、使用するための基盤となるプラットフォームです。シンプルで一般的なサービス使用モデルを使用し、ユーザーはプロデューサーが管理するサービスを消費します。すべての Google API とGoogle Cloud APIは Service Infrastructure の上に構築されているため、このモデルを使用します。

コンシューマがサービスにアクセスすると、サービスは関連するテレメトリー データをプラットフォームにレポートします。このため、コンシューマとプロデューサーの両方がアクセスを監視できます。Service Infrastructure では、このプロセスはテレメトリー レポートと呼ばれ、分析、監査、課金、ロギング、モニタリングが含まれます。

Service Control API v2

Service Control API v2 は、Service Infrastructure と統合されたすべてのサービスにテレメトリー レポートを提供するシンプルな services.report メソッドを提供します。このメソッドを使用すると、1 回のメソッド呼び出しで次のことを行うことができます。

  • 分析
  • 監査
  • 課金
  • ロギング
  • モニタリング

サービスがテレメトリー データを Service Control API にレポートすると、データはサービスの構成に応じて、消費者、プロデューサーのいずれか、または両方に配信されます。テレメトリーの設定の詳細については、google.api.Service のロギングとモニタリングのセクションをご覧ください。

サービスから Service Control API を呼び出すには、プロデューサーはプロデューサー プロジェクトで Service Control API を有効にして、呼び出し元はサービスに対して適切な権限を持っている必要があります。詳細については、Cloud APIs のスタートガイドService Control API のアクセス制御をご覧ください。

リクエストの属性

クライアントがサービスにアクセスするとき、サービスは一連の API リクエストに基づいてアクセスをモデル化し、AttributeContext を使用して各リクエストを記述する必要があります。

Service Control API を使用して API 指標をレポートするには、サービスは次の属性を持つ各リクエストに対して services.report メソッドを呼び出す必要があります。Service Control API は API 指標を生成し、それを Cloud Monitoring に送信します。

属性 説明
origin.ip 発信者の IP アドレス。 "1.2.3.4"
api.service API サービスの名前 "endpointsapis.appspot.com"
api.operation API メソッドの名前 "google.example.hello.v1.HelloService.GetHello"
api.version API バージョンの文字列 "v1"
api.protocol API プロトコルの名前 "https"
request.id 一意のリクエスト ID "123e4567-e89b-12d3-a456-426655440000"
request.time リクエストのタイムスタンプ "2019-07-31T05:20:00Z"
request.method HTTP メソッドの名前 "POST"
request.scheme URL スキーム "https"
request.host HTTP ホストヘッダー "endpointsapis.appspot.com"
request.path URL パス "/v1/hello"
response.code レスポンスのステータス コード 200
response.size レスポンスのサイズ(バイト) 100
response.time レスポンスのタイムスタンプ "2019-07-31T05:20:02Z"
response.backend_latency バックエンドのレイテンシ "0.007s"

テレメトリー レポートの実行

サービス構成を Service Management API にデプロイし、サービスがクライアントからのリクエストを処理する準備ができたら、デプロイされたサービスの services.report の呼び出しを開始できます。サービスがリクエストを受信した後、services.report を呼び出してテレメトリー レポートを実行する必要があります。

テレメトリー レポートをすばやくテストするには、gcurl コマンドを使用して services.report メソッドを呼び出します。初期設定手順については、Service Control API スタートガイドをご覧ください。

次の例は、gcurl コマンドを使用して HTTP 経由で services.report を呼び出す方法を示しています。

gcurl -d '{
  "service_config_id": "latest",
  "operations": [{
    "origin": {
      "ip": "1.2.3.4"
    },
    "api": {
      "service": "endpointsapis.appspot.com",
      "operation", "google.example.endpointsapis.v1.Workspaces.GetWorkspace",
      "version": "v1",
      "protocol": "https"
    },
    "request": {
      "id": "123e4567-e89b-12d3-a456-426655440000",
      "size": 50,
      "time": "2019-07-31T05:20:00Z",
    },
    "response": {
      "size": 100,
      "code": 200,
      "time": "2019-07-31T05:20:02Z",
      "backend_latency": "0.007s"
    },
    "destination": {
      "region_code": "us-central1"
    }
    "resource": {
      "name": "projects/123/locations/us-central1/workspaces/default"
    }
  }]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:report

成功すると、services.report メソッドからのレスポンスは空になります。 失敗した場合、API エラーに詳細なエラー情報が含まれます。エラー処理の詳細については、API 設計ガイド > エラーをご覧ください。

本番環境サービスの場合、Google が提供するクライアントライブラリのいずれかを使用して Service Control API を呼び出す必要があります。このようなライブラリは、優れたユーザビリティを提供し、認証などの一般的な機能を自動的に処理します。詳しくはクライアント ライブラリの説明をご覧ください。