프록시리스 gRPC의 관측 가능성

미리보기

이 제품 또는 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 제품 및 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

프록시리스 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
    • '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
    • 원격 워크로드의 이름입니다. 포드 정의가 포함된 객체의 이름이어야 합니다(예: 배포, ReplicaSet 또는 빈 포드의 포드 이름).

서비스 라벨: RPC가 라우팅되는 백엔드 서비스(xDS 클러스터)에 대한 정보입니다. 이는 백엔드 서비스가 Gateway API를 통해 구성된 경우에만 사용할 수 있습니다.

• csm.service_name
  • 서비스 이름
• csm.service_namespace_name
  • 서비스 네임스페이스 이름

remote_workload라는 용어는 피어를 나타냅니다. 즉, 클라이언트의 경우 RPC의 대상인 서버 포드가 원격 워크로드이고 서버의 경우 RPC를 시작한 클라이언트 포드가 원격 워크로드입니다.

이러한 측정항목의 수집 지점에서는 모든 토폴로지 메시 정보를 사용할 수 없으므로 grpc.client.attempt.started 및 grpc.server.call.started에서는 이러한 속성을 사용할 수 없습니다.

참고: grpc.client.call.duration은 측정항목으로 사용할 수 없습니다. grpc.client.attempt.duration 및 grpc.server.call.duration 측정항목을 사용할 수 있습니다.

관측 가능성 설정 안내

이 섹션에서는 서비스 메시 설정에서 프록시리스 gRPC에 Cloud Service Mesh 관측 가능성을 사용 설정하는 방법을 설명합니다.

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 관측 가능성을 사용 설정하려면 다음 단계를 수행합니다.

1. 프로젝트에 grpc-gcp-csm-observability 아티팩트가 포함되어 있는지 확인합니다. gRPC 버전 1.65.0 이상을 사용합니다.

2. main() 메서드 내에서 구성된 OpenTelemetry SDK 인스턴스에 측정항목을 수집하고 내보낼 MeterProvider를 제공하여 Cloud Service Mesh 관측 가능성을 초기화합니다.

   채널 또는 서버 설정과 같은 gRPC 작업을 수행하기 전에 CsmObservability.Builder() API를 사용하여 OpenTelemetry SDK를 등록해야 합니다.

   CsmObservability 인스턴스가 생성되면 인스턴스에서 registerGlobal()을 호출하면 모든 Cloud Service Mesh 채널과 서버에 Cloud Service Mesh 관측 가능성을 사용 설정할 수 있습니다.

   다음 예시에서는 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

ClientConn 또는 서버 또는 사용자 인증 정보 생성을 포함하여 gRPC 작업 전에 MeterProvider를 사용하여 Cloud Service Mesh 관측 가능성을 전역으로 구성합니다. 다음 샘플은 Cloud Service Mesh 관측 가능성을 설정하는 방법을 보여줍니다. Cloud Service Mesh 관측 가능성을 설정하면 모든 Cloud Service Mesh 채널과 모든 서버에서 제공된 옵션과 추가 Cloud Service Mesh 라벨로 구성된 OpenTelemetry 통계 플러그인을 선택합니다. Cloud Service Mesh 채널이 아닌 채널에는 Cloud Service Mesh 라벨이 없는 OpenTelemetry 통계 플러그인이 제공됩니다.

  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 관측 가능성을 설정하는 방법을 보여줍니다.

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 관측 가능성에서 보고된 측정항목을 가져올 수 있습니다.

gRPC 측정항목에 추가된 메시 속성이 작동하려면 클라이언트 바이너리와 서버 바이너리 모두 CsmObservability로 설정해야 합니다.

Google 이외의 인프라를 사용하여 측정항목을 내보내고 저장하는 경우 수집 파이프라인은 애플리케이션이 실행되는 환경을 설명하는 측정항목에 속성을 추가해야 합니다. 이 속성과 앞에서 설명한 메시 속성을 함께 사용하여 메시에서 실행되는 트래픽을 확인할 수 있습니다.

사양 변경사항

Cloud Service Mesh 관측 가능성은 클라이언트 및 서버 모두에 컨테이너 환경에 추가해야 하는 환경 변수를 통해 메시 토폴로지 정보를 결정합니다. 이 정보는 Cloud Service Mesh 관측 가능성을 통해 측정항목 보고를 위한 피어에 제공됩니다.

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을 워크로드 이름(예: 배포 이름)으로 바꿉니다.