マイクロサービス オブザーバビリティ リファレンス情報

構成データ

環境変数の構成データの定義は次のとおりです。

フィールド 仕様
project_id 文字列

オブザーバビリティ データが送信されるプロジェクトの識別子。空の場合、gRPC オブザーバビリティ プラグインは環境変数またはデフォルトの認証情報からプロジェクト ID を取得します。

見つからない場合、オブザーバビリティの init 関数からエラーが返されます。
cloud_logging オブジェクト

ロギング オプションは、この構成ファイルのテーブルに分類されます。
存在しない場合、ロギングは無効になります。
cloud_logging.client_rpc_events[] リスト

バイナリからの送信 RPC の構成を表す client_rpc_events 構成のリスト。

client_rpc_events 構成はテキスト順に評価され、最初に一致した構成が使用されます。RPC がエントリと一致しない場合、リスト内の次のエントリが照合されます。
cloud_logging.client_rpc_events[].methods[] リスト [文字列]

メソッド識別子のリスト。

デフォルトでは、リストは空で、どのメソッドも一致しません。

メソッドの値は [service]/[method] の形式です。

* は、次のワイルドカードとして使用できます。
  • メソッド名。値が [service]/* の場合、指定されたサービス内のすべてのメソッドと一致します。
  • 任意の [service]/[method] に一致するフィールドの整数値。client_rpc_events[].exclude が true の場合はサポートされません。
  • サービス名にワイルドカード * を単独で使用することはできません。*/[method] はサポートされていません。

サービス名を指定する場合は、パッケージ名を含む完全修飾サービス名にする必要があります。

例:
  • goo.Foo/Bar を使用すると、サービス goo.Foo からメソッド Bar のみが選択されます。ここで、goo はパッケージ名です。
  • goo.Foo/* を使用すると、サービス goo.Foo からすべてのメソッドが選択されます。
  • * を使用すると、すべてのサービスからすべてのメソッドが選択されます。
cloud_logging.client_rpc_events[].exclude ブール

client_rpc_events[].methods[] で示されるメソッドをロギングから除外するかどうか。

デフォルト値は false です。つまり、client_rpc_events[].methods[] で示されるメソッドはログレコードに含まれます。

値が true の場合、client_rpc_events[].methods[]. で整数値としてワイルドカード（*）を使用できません
cloud_logging.client_rpc_events[].max_metadata_bytes 整数

記録するメタデータの最大バイト数。メタデータのサイズが定義済みの上限より大きい場合、上限を超えた Key-Value ペアは記録されません。

デフォルト値は 0 です。つまり、メタデータはログに記録されません。
cloud_logging.client_rpc_events[].max_message_bytes 整数

ログに記録される各メッセージの最大バイト数。メッセージのサイズが定義された上限より大きい場合、上限を超えるコンテンツは切り捨てられます。

デフォルト値は 0 です。メッセージ ペイロードはログに記録されません。
cloud_logging.server_rpc_events[] リスト

server_rpc_events 構成のリスト。バイナリに対する受信 RPC の構成を表します。

server_rpc_events 構成はテキスト順に評価され、最初に一致した構成が使用されます。RPC がエントリと一致しない場合

リスト内の次のエントリが照合されます。
cloud_logging.server_rpc_events[].methods[] リスト [文字列]

メソッドのグループを選択できる文字列のリスト。

デフォルトでは、リストは空で、どのメソッドも一致しません。

メソッドの値は [service]/[method] の形式です。

* は、次のワイルドカードとして使用できます。
  • メソッド名。値が [service]/* の場合、指定されたサービス内のすべてのメソッドと一致します。
  • 任意の [service]/[method] に一致するメソッドの整数値。server_rpc_events[].exclude が true の場合はサポートされません。
  • サービス名にワイルドカード * を単独で使用することはできません。*/[method] はサポートされていません。

サービス名を指定する場合は、パッケージ名を含む完全修飾サービス名にする必要があります。

例:
  • goo.Foo/Bar を使用すると、サービス goo.Foo からメソッド Bar のみが選択されます。ここで、goo はパッケージ名です。
  • goo.Foo/* を使用すると、サービス goo.Foo からすべてのメソッドが選択されます。
  • * を使用すると、すべてのサービスからすべてのメソッドが選択されます。
cloud_logging.server_rpc_events[].exclude ブール

server_rpc_events[].methods[] で示されるメソッドをロギングから除外するかどうか。

デフォルト値は false です。server_rpc_events[].methods[] で示されるメソッドはログに記録されます。

値が true の場合、server_rpc_events[].methods[] のエントリで整数としてワイルドカード（*）を使用できません。
cloud_logging.server_rpc_events[].max_metadata_bytes 整数

記録するメタデータの最大バイト数。メタデータのサイズが定義済みの上限より大きい場合、上限を超えた Key-Value ペアは記録されません。

デフォルト値は 0 です。つまり、メタデータはログに記録されません。
cloud_logging.server_rpc_events[].max_message_bytes 整数

ログに記録される各メッセージの最大バイト数。メッセージのサイズが定義された上限より大きい場合、上限を超えるコンテンツは切り捨てられます。

デフォルト値は 0 です。メッセージ ペイロードはログに記録されません。
cloud_monitoring オブジェクト

Cloud Monitoring を有効にします。構成オプションはありません。空の構成オブジェクトを提供すると、モニタリングが有効になります。構成オブジェクトを指定しない場合、モニタリングは無効になります。

たとえば、他のオプションが指定されていない場合、空の構成セクションでモニタリングが有効になります。
export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_monitoring": {
    }
}'
cloud_trace オブジェクト

空の構成セクションにより、デフォルトの構成オプションを使用したトレースが有効になります。構成オブジェクトを指定しない場合、トレースは無効になります。

たとえば、空の構成セクションにより、デフォルトの構成オプションを使用したトレースが有効になります。
export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_trace": {
    }
}'


トレースが有効になっている場合は、サンプリング レートが「0」であっても、特定のトレースのサンプリングの決定が伝播されます。
cloud_trace.sampling_rate 数値

RPC がトレースされる確率を制御するグローバル設定。例:
  • 値 0.05 は、RPC がトレースされる確率が 5% であることを意味します。
  • 値 1.0 は、すべての呼び出しがトレースされることを意味します。
  • 値 0 は、新しいトレースを開始しないことを意味します。

デフォルトでは、sampling_rate は 0 です。

プラグインはアップストリームでのサンプリングの決定を受け入れます。アップストリームでのサンプリングに RPC が選択されている場合、プラグインはスパンを収集し、プラグインのサンプリング レートの設定に関係なく、バックエンドにデータをアップロードします。
labels オブジェクト

Key-Value ペアのセットを含む JSON オブジェクト。キーと値はどちらも文字列です。

ラベルは、Cloud Logging、Cloud Monitoring、Cloud Trace にまとめて適用されます。

トレースの定義

このセクションでは、トレースについて説明します。

トレース コンテキストの伝播

サービス間でのトレースを機能させるには、サービス オーナーが、アップストリームから受信した（またはそれ自体で開始した）トレース コンテキストをダウンストリームに伝播することを許可する必要があります。トレース コンテキストは、gRPC メタデータを介してサービス間で伝播されます。Cloud Monitoring、Cloud Logging、Cloud Trace API、マイクロサービス API を必ず有効にしてください。これにより、この構成のサービスから適切なサービスにテレメトリー データが報告されるようになります。

伝播がサポートされていない場合、ダウンストリーム サービスはトレースのスパンを生成できません。既存のスパンは影響を受けません。マイクロサービス オブザーバビリティ プラグインは、エンコードとトレース コンテキストのエンコード用に OpenCensus バイナリ形式をサポートしています。

スパン

スパンの名前は次の形式になります。

種類 値の例 使用
RPC スパン [Sent|Recv].helloworld.Greeter.SayHello スパン名は、先頭にスラッシュのない、ドットでつながった完全なメソッド名です。
完全なスパン名の前にあるスパン名の先頭には、Sent.（CLIENT RPC スパンの場合）または Recv.（SERVER RPC スパンの場合）が付きます。
試行スパン Attempt.helloworld.Greeter.SayHello 完全なメソッド名の前に接頭辞 Attempt. を付けます。

スパンラベル

この統合では、複数のスパンラベルが提供されます。

試行スパンの場合、追加の再試行関連の属性（スパンラベル）が 2 つあります。

ラベル 値の例 使用
previous-rpc-attempts 0 再試行は、この RPC の前にカウントされます。
transparent-retry True/False この RPC が透過的な再試行によって開始されるかどうか。

指標の定義

マイクロサービス（gRPC）モニタリングというダッシュボードには、一般的なユーザー ジャーニーの指標として次の指標が表示されます。

gRPC クライアントサイドの指標は次のとおりです。

指標名 説明 種類、型、単位 ラベル
custom.googleapis.com/opencensus/grpc.io/client/started_rpcs クライアント RPC の試行回数（完了していない試行を含む）。 累積、Int64、1 grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/completed_rpcs 完了したクライアント RPC の数（サーバーによってレスポンスが受信または送信された場合など）。 累積、Int64、1 grpc_client_method、grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/roundtrip_latency RPC の試行を完了するまでにかかる時間（サブチャネルの選択に要する時間を含む）。 累積、分布、ミリ秒 grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/api_latency アプリケーションの観点から gRPC ライブラリが RPC を完了するのに要した合計時間。 累積、分布、ミリ秒 grpc_client_method、grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/sent_compressed_message_bytes_per_rpc RPC の試行ごとにすべてのリクエスト メッセージで送信されたバイト数の合計（圧縮、暗号化なし）。 累計、分布、基準 grpc_client_method、grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/received_compressed_message_bytes_per_rpc RPC の試行ごとにすべてのレスポンス メッセージで受信したバイト数の合計（圧縮、暗号化なし）。 累計、分布、基準 grpc_client_method、grpc_client_status

使用できる gRPC サーバーサイドの指標は次のとおりです。

指標名 説明 種類、型、単位 ラベル
custom.googleapis.com/opencensus/grpc.io/server/started_rpcs
サーバーで受信された RPC の数（完了していない RPC を含む）。		 累積、Int64、1 grpc_server_method
custom.googleapis.com/opencensus/grpc.io/server/completed_rpcs
完了した RPC の合計数（サーバーからレスポンスが送信された場合など）。		 累積、Int64、1 grpc_server_method、grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/sent_compressed_message_bytes_per_rpc
RPC あたりのすべてのレスポンス メッセージで送信されたバイト数の合計（圧縮、暗号化なし）。		 累計、分布、基準 grpc_server_method、grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/received_compressed_message_bytes_per_rpc
RPC あたりのすべてのリクエスト メッセージで受信したバイト数の合計（圧縮、暗号化なし）。		 累計、分布、基準 grpc_server_method、grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/server_latency
サーバー トランスポート（HTTP2 / inproc / cronet）の観点から見た RPC の合計時間。		 累積、分布、ミリ秒 grpc_server_method

上の表の各分布には、次のようなバケットを持つヒストグラムが含まれています。

  • サイズ（バイト）: 0、1024、2048、4096、16384、65536、262144、1048576、4194304、16777216、67108864、268435456、1073741824、4294967296

  • レイテンシ（ミリ秒）: 0、0.01、0.05、0.1、0.3、0.6、0.8、1、2、3、4、5、6、8、10、13、16、20、25、30、40、50、65、80、100、130、160、200、250、300、400、500、650、800、1000、2000、5000、10000、20000、50000、100000

タグの説明:

  • grpc_client_method: パッケージ、サービス、メソッドを含む完全な gRPC メソッド名（例: google.bigtable.v2.Bigtable/CheckAndMutateRow）
  • grpc_client_status: 受信した gRPC サーバーのステータス コード（OK、CANCELLED、DEADLINE_EXCEEDED など）
  • grpc_server_method: パッケージ、サービス、メソッドを含む完全な gRPC メソッド名（例: com.exampleapi.v4.BookshelfService/Checkout）
  • grpc_server_status: 返された gRPC サーバーのステータス コード（OK、CANCELLED、DEADLINE_EXCEEDED など）

ログレコードの定義

マイクロサービス オブザーバビリティ ログは、ログ名を使用して Cloud Logging にアップロードされます（PROJECT_ID はプロジェクトを表す文字列のプレースホルダです）。

logName=projects/[PROJECT_ID]/logs/microservices.googleapis.com%2Fobservability%2Fgrpc

生成されたログレコードの JSON 表現は次のとおりです。

{
    "authority": string,
    "callId": string,
    "type": string,
    "logger": string,
    "serviceName": string,
    "methodName": string,
    "peer": {
        "type": string,
        "address": string,
        "ipPort": int
    },
    "payload": {
        "timeout": string,
        "metadata":
            {
                string: string,
                string: string
            },
        "statusCode": string,
        "statusMessage": string,
        "statusDetails": string,
        "message": string,
        "messageLength": int,
    },
    "sequenceId": int
}

次の表に、ログエントリのフィールドの説明を示します。

フィールド 仕様
authority 文字列

1 つのプロセスで、異なる ID を使用して複数の仮想サーバーを実行できます。

認証局がこのようなサーバー ID の名前になります。通常は、URI の host または host:port の部分になります。
callId 文字列

[client/server] 呼び出しを一意に識別します（UUID）。1 回の呼び出しで複数のログエントリが生成される場合があります。これらはすべて同じコール ID を持ちます。
type 文字列

ログイベントの種類。

イベントの種類:
EVENT_TYPE_UNKNOWN
CLIENT_HEADER
SERVER_HEADER
CLIENT_MESSAGE
SERVER_MESSAGE
CLIENT_HALF_CLOSE
SERVER_TRAILER
CANCEL
logger 文字列

イベントロガーの種類。

イベントロガーの種類:
LOGGER_UNKNOWN、CLIENT、SERVER
serviceName 文字列

サービス名。
methodName 文字列

RPC メソッドの名前。
peer オブジェクト

ピアアドレス情報。クライアント側では、ピアはサーバー ヘッダー イベントとトレーラー イベントに記録されます。サーバー側では、ピアは常にクライアント ヘッダー イベントに記録されます。
peer.type 文字列

アドレスの種類。IPv4、IPv6、UNIX のいずれか。
peer.address 文字列

アドレスの内容。
peer.ip_port 整数

アドレスのポート番号。IPv4 アドレスと IPv6 アドレスでのみ使用できます。
payload オブジェクト

ペイロードには、イベントに応じてメタデータ、タイムアウト、メッセージ、ステータスの組み合わせが含まれています。

  • メッセージ イベントの場合、ペイロードは、クライアント / サーバー メッセージとして渡される実際のデータと、メッセージの長さです。
  • ヘッダー イベントの場合、ペイロードにはヘッダー名と値が含まれます。
  • トレーラー イベントの場合、ペイロードにはステータスの詳細とトレーラーのメタデータ（存在する場合）が含まれます。
  • クライアント ヘッダー イベントでタイムアウトが設定されている場合、ペイロードにタイムアウトも含まれます。
payload.timeout 文字列

google.protobuf.Duration を表す文字列（「1.2 s」など）。

RPC タイムアウト値。
payload.metadata Mapping[String, String]

ヘッダー イベントまたはトレーラー イベントで使用されます。
payload.message 文字列（バイト）

メッセージ ペイロード。
payload.messageLength 整数

メッセージ全体がログに記録されるかどうか（たとえば、切り捨てや省略）に関係しない、メッセージのサイズ。
payload.statusCode 文字列

gRPC ステータス コード。
payload.statusMessage 文字列

gRPC ステータス メッセージ。
payload.statusDetails 文字列

grpc-status-details-bin メタデータキーの値（存在する場合）。これは、常にエンコードされた google.rpc.Status メッセージになります。
payloadTruncated ブール

構成オプションにより、メッセージ フィールドまたはメタデータ フィールドが切り捨てられたか省略された場合、true になります。
sequenceId 整数

この呼び出しのメッセージ シーケンス ID。最初のメッセージの値は 1 で、未設定の値と明確に区別されています。このフィールドの目的は、耐久性や順序が保証されていない環境でエントリ不足を検出することです。

リソースラベル

リソースラベルは、オブザーバビリティ データを生成するソースを識別します。リソースラベルは Key-Value ペアです。キーはソース環境（GKE や Compute Engine など）に固有の事前定義の値です。

GKE Deployment の指標とトレースでは、コンテナ名と Namespace 名を除き、リソースラベルがデフォルトで設定されます。欠落している値は、Downward API を使用して挿入できます。

環境変数のキーは次のとおりです。

  • CONTAINER_NAME
  • NAMESPACE

たとえば、次の env セクションには 2 つのリソースラベルが含まれています。

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    run: app1
  name: app1
spec:
  replicas: 2
  selector:
    matchLabels:
      run: app1
  template:
    metadata:
      labels:
        run: app1
    spec:
      containers:
        - image: 'o11y-examples:1.00'
          name: container1
          ports:
            - protocol: TCP
              containerPort: 50051
          env:
            - name: CONTAINER_NAME
              value: container1
            - name: NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace

カスタムラベル

カスタムラベルは、オブザーバビリティ データのユーザー提供の追加情報を表します。ラベルはキーと値で構成されます。Key-Value ペアは、トレースデータ（スパンラベルとして）、指標データ（指標ラベルとして）、ロギングデータ（ログエントリ ラベルとして）に追加されます。カスタムラベルはすべて文字列型です。

構成でカスタムラベルを指定するには、labels の Key-Value ペアのリストを指定します。この実装では、構成を読み取り、Key-Value ペアごとに個別のラベルを作成して、そのラベルをオブザーバビリティ データに関連付けます。例:

"labels": {
    "DATACENTER": "SAN_JOSE_DC",
    "APP_ID": "24512"
  }

各ログエントリには、次のラベルが追加されています。

{
   "DATACENTER": "SAN_JOSE_DC"
   "APP_ID": "24512"
}

次のステップ