無 Proxy gRPC 的觀測能力

無 Proxy gRPC 適用的 Cloud Service Mesh 可觀測性功能，是以現有的 gRPC OpenTelemetry 外掛程式為基礎，可記錄所有啟用 Cloud Service Mesh 的 gRPC 管道和伺服器指標 (延遲時間、訊息大小等)，並提供額外屬性，顯示 Cloud Service Mesh 流量的拓撲網格資訊。如果 gRPC 通道從 Cloud Service Mesh 控制層取得設定，則視為已啟用 Cloud Service Mesh，而所有 gRPC 伺服器都視為已啟用 Cloud Service Mesh。

網格屬性

指標提供下列網格屬性。

當地環境標籤：

csm.mesh_id
- 網格 ID。
其他本機環境屬性則來自 OpenTelemetry 資源。
- Managed Service for Prometheus (GMP) 可以設定為使用 Google 基礎架構儲存指標。如果使用這個方法，系統會自動新增描述應用程式本機環境的資源屬性，做為 MonitoredResource。
- 如果使用非 Google 基礎架構匯出及儲存指標，收集管線應在指標中加入屬性，說明應用程式執行的環境。

遠端環境標籤：

csm.remote_workload_type
- 遠端對等互連的類型。(GKE 為「gcp_kubernetes_engine」)。
系統會根據對等互連類型顯示其他屬性。
- 如果是 GKE 上執行的對等互連節點：
- csm.remote_workload_project_id
  - 與這個資源相關聯的專案 ID，例如「my-project」。
- csm.remote_workload_location * 包含容器的叢集實際位置。
- csm.remote_workload_cluster_name
  - 執行容器的叢集。
- csm.remote_workload_namespace_name
  - The namespace where the container is running.
- csm.remote_workload_name
  - 遠端工作負載的名稱。這應該是包含 Pod 定義的物件名稱 (例如 Deployment、ReplicaSet，或是裸機 Pod 的 Pod 名稱)。

服務標籤：RPC 路由至的後端服務 (xDS 叢集) 相關資訊。請注意，只有透過 Gateway API 設定後端服務時，才能使用這項功能。

csm.service_name
- 服務名稱。
csm.service_namespace_name
- 服務命名空間名稱。

remote_workload 一詞是指對等互連，也就是說，對於用戶端而言，RPC 的目標伺服器 Pod 是遠端工作負載，而對於伺服器而言，啟動 RPC 的用戶端 Pod 則是遠端工作負載。

請注意，這些屬性不會顯示在 grpc.client.attempt.started 和 grpc.server.call.started 上，因為系統無法在這些指標的收集點取得所有拓撲網格資訊。

觀測功能設定操作說明

本節說明如何在服務網格設定中，為無 Proxy gRPC 啟用 Cloud Service Mesh Observability。

C++

觀測功能僅支援 Bazel 建構系統。目標 grpcpp_csm_observability 需要新增為依附元件。

必要程式碼變更

如要使用 Cloud Service Mesh 可觀測性，必須將下列程式碼新增至 gRPC 用戶端和伺服器。

#include <grpcpp/ext/csm_observability.h>

int main() {
  // …
  auto observability = grpc::CsmObservabilityBuilder()
                          .SetMeterProvider(std::move(meter_provider))
                          .BuildAndRegister();
  assert(observability.ok());
  // …
}

在執行任何 gRPC 作業 (包括建立管道、伺服器或憑證) 前，請使用 CsmObservabilityBuilder API 註冊外掛程式。下列範例說明如何使用 Prometheus 匯出工具設定 Cloud Service Mesh 可觀測性。

  opentelemetry::exporter::metrics::PrometheusExporterOptions opts;
  opts.url = "0.0.0.0:9464";
  auto prometheus_exporter =
      opentelemetry::exporter::metrics::PrometheusExporterFactory::Create(opts);
  auto meter_provider =
      std::make_shared<opentelemetry::sdk::metrics::MeterProvider>();
  meter_provider->AddMetricReader(std::move(prometheus_exporter));
  auto observability = grpc:::CsmObservabilityBuilder()
                          .SetMeterProvider(std::move(meter_provider))
                          .BuildAndRegister();

CsmObservabilityBuilder() 上的 SetMeterProvider() API 可讓使用者設定 MeterProvider 物件，並透過匯出工具進行設定。

Java

如要為 Java gRPC 應用程式啟用 Cloud Service Mesh Observability，請按照下列步驟操作：

確認專案包含 grpc-gcp-csm-observability 構件。使用 gRPC 1.65.0 以上版本。
在 main() 方法中，提供已設定的 OpenTelemetry SDK 執行個體和 MeterProvider，藉此初始化 Cloud Service Mesh Observability，以收集及匯出指標。

執行任何 gRPC 作業 (例如設定管道或伺服器) 之前，請務必使用 CsmObservability.Builder() API 註冊 OpenTelemetry SDK。

建立 CsmObservability 執行個體後，在該執行個體上叫用 registerGlobal()，即可為所有 Cloud Service Mesh 管道和伺服器啟用 Cloud Service Mesh Observability。

下列範例說明如何使用 Prometheus 匯出工具設定 Cloud Service Mesh 可觀測性。

import io.grpc.gcp.csm.observability.CsmObservability;
...

public static void main(String[] args) {
    ...

    int prometheusPort = 9464;

    SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder()
        .registerMetricReader(
            PrometheusHttpServer.builder().setPort(prometheusPort).build())
        .build();

    OpenTelemetrySdk openTelemetrySdk = OpenTelemetrySdk.builder()
        .setMeterProvider(sdkMeterProvider)
        .build();

    CsmObservability observability = new CsmObservability.Builder()
        .sdk(openTelemetrySdk)
        .build();
    observability.registerGlobal();

    // ... (continue with channel and server configuration)
}

Go

在執行任何 gRPC 作業 (包括建立 ClientConn 或伺服器，或憑證) 之前，請使用 MeterProvider 全域設定 Cloud Service Mesh Observability。下列範例說明如何設定 Cloud Service Mesh 可觀測性。設定 Cloud Service Mesh 可觀測性後，所有 Cloud Service Mesh 管道和伺服器都會採用 OpenTelemetry 統計資料外掛程式，並使用提供的選項和額外的 Cloud Service Mesh 標籤進行設定。非 Cloud Service Mesh 管道會取得 OpenTelemetry 統計資料外掛程式，但沒有 Cloud Service Mesh 標籤。

  import (
  "context"

  "google.golang.org/grpc/stats/opentelemetry"
  "google.golang.org/grpc/stats/opentelemetry/csm"

  "go.opentelemetry.io/otel/sdk/metric"
)

func main() {
  reader := metric.NewManualReader()
  provider := metric.NewMeterProvider(metric.WithReader(reader))
  opts := opentelemetry.Options{
    MetricsOptions: opentelemetry.MetricsOptions{
        MeterProvider: provider,
    },
  }
  cleanup := csm.EnableObservability(context.Background(), opts)
  defer cleanup()
  // Any created ClientConns and servers will be configured with an
  // OpenTelemetry stats plugin configured with provided options.

}

Python

Cloud Service Mesh 可觀測性需要下列 gRPC 依附元件：

grpcio>=1.65.0
grpcio-observability>=1.65.0
grpcio-csm-observability>=1.65.0

在執行任何 gRPC 作業 (包括建立管道、伺服器或憑證) 之前，請使用 CsmOpenTelemetryPlugin API 建立及註冊外掛程式：

import grpc_csm_observability

# ...
csm_plugin = grpc_csm_observability.CsmOpenTelemetryPlugin(
    meter_provider=[your_meter_provider],
)
csm_plugin.register_global()

# Create server or client

完成所有 gRPC 作業後，請使用下列程式碼取消註冊並清除資源：

csm_plugin.deregister_global()

下列範例說明如何使用 Prometheus 匯出工具設定 Cloud Service Mesh Observability：

import grpc_csm_observability
from opentelemetry.exporter.prometheus import PrometheusMetricReader
from prometheus_client import start_http_server

start_http_server(port=9464, addr="0.0.0.0")
reader = PrometheusMetricReader()
meter_provider = MeterProvider(metric_readers=[reader])
csm_plugin = CsmOpenTelemetryPlugin(
    meter_provider=meter_provider,
)
csm_plugin.register_global()

# Clean up after use

csm_plugin.deregister_global()

在先前的範例中，您可以擷取 localhost:9464/metrics，取得 Cloud Service Mesh Observability 回報的指標。

請注意，如要讓新增至 gRPC 指標的網格屬性正常運作，用戶端和伺服器二進位檔都必須設定 CsmObservability。

如果使用非 Google 基礎架構匯出及儲存指標，收集管道應在指標中加入屬性，說明應用程式執行的環境。這項資訊連同先前所述的網格屬性，可用於查看網格上執行的流量。

規格變更

Cloud Service Mesh Observability 會透過環境變數判斷網格拓撲資訊，這些環境變數必須新增至用戶端和伺服器的容器環境。透過 Cloud Service Mesh Observability，同層級可取得這項資訊，用於指標報表。

spec:
  containers:
  - image: IMAGE_NAME
    name: CONTAINER_NAME
    env:
    - name: GRPC_XDS_BOOTSTRAP
      value: "/tmp/grpc-xds/td-grpc-bootstrap.json" #created by td-grpc-bootstrap
    - name: POD_NAME
      valueFrom:
        fieldRef:
          fieldPath: metadata.name
    - name: NAMESPACE_NAME
      valueFrom:
        fieldRef:
          fieldPath: metadata.namespace
     - name: CSM_WORKLOAD_NAME
       value: CSM_WORKLOAD_NAME
     - name: CONTAINER_NAME
       value: CONTAINER_NAME
     - name: OTEL_RESOURCE_ATTRIBUTES
       value: k8s.pod.name=$(POD_NAME),k8s.namespace.name=$(NAMESPACE_NAME),k8s.container.name=CONTAINER_NAME

取代下列項目：

將 IMAGE_NAME 替換為映像檔的名稱。
將 CONTAINER_NAME 替換為容器名稱。
CSM_WORKLOAD_NAME，例如部署名稱。