마이크로서비스 관측 가능성으로 Google Cloud에서 gRPC 애플리케이션 설정


마이크로서비스 관측 가능성 도구는 Google Cloud 및 기타 위치에 배포된 gRPC 워크로드에서 Cloud Monitoring, Cloud Logging, Cloud Trace의 원격 분석 데이터를 수집하고 나타내기 위해 애플리케이션을 계측하는 기능을 제공합니다. 마이크로서비스 관측 가능성은 마이크로서비스 API를 사용 설정하여 Monitoring, Logging, Trace에 액세스할 수 있는 권한이 부여된 모든 배포에서 작동합니다.

이 튜토리얼에서는 Compute Engine을 사용하여 Google Cloud에서 간단한 gRPC 애플리케이션을 빌드하여 마이크로서비스 관측 가능성 기능을 사용하고 마이크로서비스 관측 가능성으로 애플리케이션을 계측하고 Monitoring 및 Logging에서 실시간으로 표시되는 마이크로서비스를 보는 방법을 알아봅니다.

목표

개략적으로 다음을 수행합니다.

  • 서비스 개발자는 다음을 수행할 수 있습니다.

    • 원하는 언어(C++, Go, Java)로 gRPC 애플리케이션을 만듭니다.
    • 애플리케이션을 선택하고 마이크로서비스 관측 가능성 플러그인을 제어합니다.
    • Compute Engine VM에 애플리케이션을 배포합니다.
  • 서비스 운영자는 여러 방법으로 수집된 데이터를 소비합니다.

    • Trace에서 trace 보기
    • 마이크로서비스(gRPC) 모니터링이라는 모니터링 대시보드에서 측정항목 보기
    • 측정항목 탐색기에서 측정항목 보기
    • 로그 탐색기에서 로그 항목 검사

비용

이 문서에서는 비용이 청구될 수 있는 다음과 같은 Google Cloud 구성요소를 사용합니다.

프로젝트 사용량을 기준으로 예상 비용을 산출하려면 가격 계산기를 사용하세요. Google Cloud를 처음 사용하는 사용자는 무료 체험판을 사용할 수 있습니다.

이 문서에 설명된 태스크를 완료했으면 만든 리소스를 삭제하여 청구가 계속되는 것을 방지할 수 있습니다. 자세한 내용은 삭제를 참조하세요.

시작하기 전에

콘솔

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

  4. Enable the Compute Engine, and Microservices API APIs.

    Enable the APIs

  5. Create a service account:

    1. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
    2. Select your project.
    3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

      In the Service account description field, enter a description. For example, Service account for quickstart.

    4. Click Create and continue.
    5. Grant the following roles to the service account: Logging > Logs Viewer > Logs Writer, Monitoring > Monitoring Editor > Metrics Writer, Trace > Trace Admin > Trace Agent.

      To grant a role, find the Select a role list, then select the role.

      To grant additional roles, click Add another role and add each additional role.

    6. Click Continue.
    7. In the Service account users role field, enter the identifier for the principal that will attach the service account to other resources, such as Compute Engine instances.

      This is typically the email address for a Google Account.

    8. Click Done to finish creating the service account.

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  7. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

  8. Enable the Compute Engine, and Microservices API APIs.

    Enable the APIs

  9. Create a service account:

    1. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
    2. Select your project.
    3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

      In the Service account description field, enter a description. For example, Service account for quickstart.

    4. Click Create and continue.
    5. Grant the following roles to the service account: Logging > Logs Viewer > Logs Writer, Monitoring > Monitoring Editor > Metrics Writer, Trace > Trace Admin > Trace Agent.

      To grant a role, find the Select a role list, then select the role.

      To grant additional roles, click Add another role and add each additional role.

    6. Click Continue.
    7. In the Service account users role field, enter the identifier for the principal that will attach the service account to other resources, such as Compute Engine instances.

      This is typically the email address for a Google Account.

    8. Click Done to finish creating the service account.

  10. 마이크로서비스 관측 가능성 개요를 참조하세요.
  11. 지원되는 두 가지 환경 변수에 대해 알아보고 사용할 항목을 결정하고 환경 변수에 필요한 값을 결정합니다.

CLI

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. Install the Google Cloud CLI.
  3. To initialize the gcloud CLI, run the following command:

    gcloud init
  4. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  5. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

  6. Enable the Compute Engine, and Microservices API APIs:

    gcloud services enable compute.googleapis.com microservices.googleapis.com
  7. Set up authentication:

    1. Create the service account:

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Replace SERVICE_ACCOUNT_NAME with a name for the service account.

    2. Grant roles to the service account. Run the following command once for each of the following IAM roles: roles/logging.logWriter, roles/monitoring.metricWriter, roles/cloudtrace.agent:

      gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

      Replace the following:

      • SERVICE_ACCOUNT_NAME: the name of the service account
      • PROJECT_ID: the project ID where you created the service account
      • ROLE: the role to grant
    3. Grant the required role to the principal that will attach the service account to other resources.

      gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

      Replace the following:

      • SERVICE_ACCOUNT_NAME: the name of the service account
      • PROJECT_ID: the project ID where you created the service account
      • USER_EMAIL: the email address for a Google Account
  8. Install the Google Cloud CLI.
  9. To initialize the gcloud CLI, run the following command:

    gcloud init
  10. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  11. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

  12. Enable the Compute Engine, and Microservices API APIs:

    gcloud services enable compute.googleapis.com microservices.googleapis.com
  13. Set up authentication:

    1. Create the service account:

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Replace SERVICE_ACCOUNT_NAME with a name for the service account.

    2. Grant roles to the service account. Run the following command once for each of the following IAM roles: roles/logging.logWriter, roles/monitoring.metricWriter, roles/cloudtrace.agent:

      gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

      Replace the following:

      • SERVICE_ACCOUNT_NAME: the name of the service account
      • PROJECT_ID: the project ID where you created the service account
      • ROLE: the role to grant
    3. Grant the required role to the principal that will attach the service account to other resources.

      gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

      Replace the following:

      • SERVICE_ACCOUNT_NAME: the name of the service account
      • PROJECT_ID: the project ID where you created the service account
      • USER_EMAIL: the email address for a Google Account
  14. 마이크로서비스 관측 가능성 개요를 참조하세요.
  15. 지원되는 두 가지 환경 변수에 대해 알아보고 사용할 항목을 결정하고 환경 변수에 필요한 값을 결정합니다.

Compute Engine VM 만들기 및 연결

다음 안내에 따라 Compute Engine VM 인스턴스를 만들고 연결합니다. VM에서 애플리케이션을 배포한 후 마이크로서비스 관측 가능성으로 애플리케이션을 계측합니다.

  1. VM 인스턴스를 만듭니다.

    gcloud compute instances create grpc-observability-vm \
      --image-family=debian-11 \
      --image-project=debian-cloud \
      --service-account=SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com
    
  2. VM 인스턴스에 연결합니다.

    gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm
    

Compute Engine VM에 애플리케이션 배포

원하는 애플리케이션을 이전 단계에서 만든 Compute Engine VM에 배포한 후 이 단계를 건너뛰거나 예시를 사용하여 원하는 언어로 안내를 계속 진행할 수 있습니다.

C++

  1. VM 인스턴스에 연결한 후 다음 명령어를 실행합니다.

    sudo apt-get update -y
    sudo apt-get install -y git build-essential clang
    git clone -b v1.54.0 https://github.com/grpc/grpc.git --depth=1
    

Go

  1. Go가 설치되었는지 확인합니다.

    sudo apt-get install -y git
    sudo apt install wget
    wget https://go.dev/dl/go1.20.2.linux-amd64.tar.gz
    sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf \
    go1.20.2.linux-amd64.tar.gz
    export PATH=$PATH:/usr/local/go/bin
    
  2. gRPC-Go 예시를 클론합니다.

    git clone https://github.com/grpc/grpc-go.git
    cd grpc-go/
    git checkout -b run-observability-example
    875c97a94dca8093bf01ff2fef490fbdd576373d
    

자바

  1. VM 인스턴스에 연결한 후 Java 8 이상이 설치되었는지 확인합니다.

    sudo apt update
    sudo apt upgrade
    sudo apt install git
    sudo apt-get install -y openjdk-11-jdk-headless
    
  2. grpc-java 저장소를 클론합니다.

    export EXAMPLES_VERSION=v1.54.1
    git clone -b $EXAMPLES_VERSION --single-branch --depth=1 \
    https://github.com/grpc/grpc-java.git
    

gRPC Google Cloud Observability 구성 파일 만들기

서버 및 클라이언트 모두에 마이크로서비스 관측 가능성을 사용 설정하려면 별도의 gRPC Google Cloud Observability 구성 파일이 필요합니다. 이후 단계에서 이 파일의 위치를 GRPC_GCP_OBSERVABILITY_CONFIG_FILE로 내보냅니다. 구성 파일에서 다양한 매개변수를 설정하는 방법을 알아보려면 다음 안내를 따르세요.

예시 GRPC_GCP_OBSERVABILITY_CONFIG_FILE

{
  "project_id": "your-project-here",
  "cloud_logging": {
    "client_rpc_events": [
    {
      "methods": ["google.pubsub.v1.Subscriber/Acknowledge", "google.pubsub.v1.Publisher/CreateTopic"],
      "exclude": true,
    },
    {
      "methods": ["google.pubsub.v1.Subscriber/*", "google.pubsub.v1.Publisher/*"],
      "max_metadata_bytes": 4096,
      "max_message_bytes": 4096,
    }],
    "server_rpc_events": [{
      "methods": ["*"],
      "max_metadata_bytes": 4096,
      "max_message_bytes": 4096
    }],
  },
  "cloud_monitoring": {},
  "cloud_trace": {
    "sampling_rate": 0.5,
  }
  "labels": {
    "SOURCE_VERSION": "J2e1Cf",
    "SERVICE_NAME": "payment-service-1Cf",
    "DATA_CENTER": "us-west1-a"
  }
}

다음 섹션에는 개별 구성요소의 구성에서 데이터 수집을 사용 설정하는 방법에 대한 안내가 포함되어 있습니다. 이 튜토리얼에서 gRPC 예시를 사용한 경우 이 구성을 있는 그대로 사용하거나(your-project-here 업데이트 후) 애플리케이션의 템플릿으로 사용할 수 있습니다. 예시는 환경 변수의 구성 정보를 보여줍니다.

측정항목 사용 설정

측정항목을 사용 설정하려면 구성에 cloud_monitoring 객체를 추가하고 값을 {}로 설정합니다.

측정항목에 대한 자세한 내용은 측정항목 정의를 참조하세요.

추적 사용 설정

추적을 사용 설정하려면 다음을 수행합니다.

  1. 구성에 cloud_trace 객체를 추가합니다.
  2. cloud_trace.sampling_rate0.5로 설정하여 RPC의 50%를 무작위로 추적합니다.

서비스 간 추적을 사용 설정하려면 업스트림에서 수신된(또는 그 자체로 시작된) trace 컨텍스트를 다운스트림으로 전파하는 것이 서비스에서 지원되어야 합니다.

Tracing에 대한 자세한 내용은 Trace 정의를 참조하세요.

로깅 사용 설정

로깅을 사용 설정하려면 다음을 수행합니다.

  1. 구성에 cloud_logging 객체를 추가합니다.
  2. client_rpc_eventsserver_rpc_events 중 하나 또는 모두에 패턴을 추가하여 전송 수준 이벤트 로깅을 생성할 서비스 또는 메서드 집합과 헤더 및 메시지에 대해 로깅할 바이트 수를 지정합니다.

로깅에 대한 자세한 내용은 로그 레코드 정의를 참조하세요.

관측 가능성 플러그인에 대한 애플리케이션 계측

마이크로서비스 관측 가능성 플러그인을 사용할 수 있도록 애플리케이션을 계측하려면 원하는 언어에 대한 다음 안내를 따르세요.

C++

gRPC C++ v1.54부터 마이크로서비스 관측 가능성과 함께 C++를 사용할 수 있습니다. 저장소 예시는 GitHub에 있습니다.

  1. 관측 가능성 지원은 Bazel 빌드 시스템을 통해서만 제공됩니다. 대상 grpcpp_gcp_observability를 종속 항목으로 추가합니다.

  2. 마이크로서비스 관측 가능성을 선택하려면 추가 종속 항목이 필요하고(관측 가능성 모듈) 기존 gRPC 클라이언트, 서버 또는 둘 다에 대해 다음 코드를 변경해야 합니다.

    #include <grpcpp/ext/gcp_observability.h>
    
    int main(int argc, char** argv) {
      auto observability = grpc::GcpObservability::Init();
      assert(observability.ok());
      
      // Observability data flushed when object goes out of scope
    }
    

    채널, 서버, 사용자 인증 정보 생성을 포함하여 gRPC 작업 전에 다음을 호출합니다.

    grpc::GcpObservability::Init();
    

    그러면 저장해야 하는 absl::StatusOr<GcpObservability>가 반환됩니다. 상태에 따라 관측 가능성이 성공적으로 초기화되었는지 여부를 확인할 수 있습니다. 함께 제공되는 GcpObservability 객체는 관측 가능성의 전체 기간을 제어하고, 범위를 벗어날 때 관측 가능성 데이터를 자동으로 닫고 플러시합니다.

Go

  1. 마이크로서비스 관측 가능성 플러그인은 gRPC Go 버전 v1.54.0 이상에 대해 지원됩니다. 저장소 예시는 GitHub에 있습니다.

Go 모듈의 경우 마이크로서비스 관측 가능성을 선택하려면 관측 가능성 모듈 및 다음 코드가 필요합니다.

import "google.golang.org/grpc/gcp/observability"

func main() {
  ctx, cancel := context.WithTimeout(context.Background(), time.Second)
  defer cancel()
  if err := observability.Start(ctx); err != nil {
    log.Warning("Unable to start gRPC observability:", err)
  }
  defer observability.End()
  
}

observability.Start 호출은 환경 변수에서 구성을 파싱하고, 그에 따라 내보내기 도구를 만들고, 호출 후 생성되는 클라이언트 연결 및 서버에 대해 수집 논리를 삽입합니다. 지연된 observability.End 호출은 리소스를 삭제하고 애플리케이션이 종료되기 전 버퍼링된 데이터가 비워지도록 합니다.

애플리케이션 코드가 업데이트된 후 다음 명령어를 실행하여 go.mod 파일을 업데이트합니다.

go mod tidy

자바

Java 애플리케이션에 마이크로서비스 관측 가능성을 사용하려면 grpc-gcp-observability 아티팩트를 포함하도록 빌드를 수정합니다. gRPC 버전 1.54.1 이상을 사용합니다.

Gradle 및 Maven 빌드 도구 섹션의 빌드 스니펫에서 grpcVersion은 값 1.54.1로 설정됩니다.

저장소 예시는 GitHub에 있습니다.

  1. 마이크로서비스 관측 가능성에 대해 Java 애플리케이션을 성공적으로 계측하기 위해서는 다음 코드를 main()에 추가합니다.
...
import io.grpc.gcp.observability.GcpObservability;
...

// Main application class
...

public static void main(String[] args) {
...
  // call GcpObservability.grpcInit() to initialize & get observability
  GcpObservability observability = GcpObservability.grpcInit();

...
  // call close() on the observability instance to shutdown observability
  observability.close();
...
}

모든 gRPC 채널 또는 서비스가 생성되기 전에 GcpObservability.grpcInit()를 호출해야 합니다. GcpObservability.grpcInit() 함수는 마이크로서비스 관측 가능성 구성을 읽고 이를 사용해서 생성된 각 채널 및 서버에서 로깅, 측정항목, trace 기능에 필요한 전역 인터셉터 및 추적기를 설정합니다. GcpObservability.grpcInit()는 스레드에 안전하며 정확히 한 번 호출되어야 합니다. 나중에 close()를 호출하기 위해 저장해야 하는 GcpObservability의 인스턴스를 반환합니다.

GcpObservability.close()는 리소스를 할당 해제합니다. 이후에 생성되는 채널 또는 서버는 로깅을 수행하지 않습니다.

GcpObservabilitytry-with-resource를 다음과 같이 사용할 경우 자동으로 종료되는 java.lang.AutoCloseable을 구현합니다.

...
import io.grpc.gcp.observability.GcpObservability;
...

// Main application class
...

public static void main(String[] args) {
...
  // call GcpObservability.grpcInit() to initialize & get observability
  try (GcpObservability observability = GcpObservability.grpcInit()) {

...
  } // observability.close() called implicitly
...
}

Gradle 빌드 도구 사용

Gradle 빌드 도구를 사용하는 경우 다음을 포함합니다.

def grpcVersion = '1.54.1'

...

dependencies {
...
implementation "io.grpc:grpc-gcp-observability:${grpcVersion}"
...
}

Maven 빌드 도구 사용(pom.xml)

Maven 빌드 도구를 사용하는 경우 다음을 포함합니다.

<properties>
...
<grpc.version>1.54.1</grpc.version>
...
</properties>

...

<dependencies>
...
<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-gcp-observability</artifactId>
<version>${grpc.version}</version>
</dependency>
...
</dependencies>

애플리케이션 실행

튜토리얼에 gRPC 예시를 사용한 경우에만 이 섹션의 안내를 따르세요. 애플리케이션 바이너리를 타겟팅하도록 run 명령어를 수정할 수 있습니다.

서버 실행

C++

  1. VM에 SSH를 통해 연결되는 세션을 만듭니다.
  2. 환경 변수를 내보냅니다. 에 정의된 단계를 사용하여 server_config.json을 만듭니다.

      export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
      export GRPC_GCP_OBSERVABILITY_CONFIG_FILE="$(pwd)/examples/cpp/gcp_observability/helloworld/server_config.json"
    
  3. 서버 애플리케이션 shell cd grpc tools/bazel run examples/cpp/gcp_observability/helloworld:greeter_server를 실행합니다.

Go

  1. VM에 SSH를 통해 연결되는 세션을 만듭니다.
  2. 환경 변수를 내보냅니다. 에 정의된 단계를 사용하여 server_config.json을 만듭니다.

    export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./server/serverConfig.json
    
  3. 서버 애플리케이션 shell go run ./server/main.go를 실행합니다.

자바

  1. 예시 디렉터리에서 리드미 파일을 열고 파일 안내를 따릅니다.
  2. 다른 터미널 창을 열라는 안내가 있으면 다음 명령어를 실행합니다. shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

클라이언트 실행

C++

  1. VM에 SSH를 통해 연결되는 다른 세션을 만듭니다.
  2. 환경 변수를 내보냅니다. 에 정의된 단계를 사용하여 client_config.json 파일을 만듭니다.

      export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
      export GRPC_GCP_OBSERVABILITY_CONFIG_FILE="$(pwd)/examples/cpp/gcp_observability/helloworld/client_config.json"
    
  3. 클라이언트 애플리케이션을 실행합니다.

    cd grpc
    tools/bazel run examples/cpp/gcp_observability/helloworld:greeter_client
    

Go

  1. VM에 SSH를 통해 연결되는 다른 세션을 만듭니다.
  2. 환경 변수를 내보냅니다. 에 정의된 단계를 사용하여 client_config.json 파일을 만듭니다. shell export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./client/clientConfig.json
  3. 클라이언트 애플리케이션을 실행합니다.

    cd grpc-go/examples/features/observability
    go run ./client/main.go
    

자바

  1. 예시 디렉터리에서 리드미 파일을 열고 파일 안내를 따릅니다.
  2. 다른 터미널 창을 열라는 안내가 있으면 다음 명령어를 실행합니다. shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

삭제

이 튜토리얼에서 사용된 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 리소스가 포함된 프로젝트를 삭제하거나 프로젝트를 유지하고 개별 리소스를 삭제하세요.

프로젝트 삭제

    Delete a Google Cloud project:

    gcloud projects delete PROJECT_ID

개별 리소스 삭제

  1. 인스턴스를 삭제합니다.
    gcloud compute instances delete INSTANCE_NAME

다음 단계