Error Reporting용 Ruby 앱 계측

Ruby용 Error Reporting 라이브러리를 사용하면 Ruby 애플리케이션에서 Error Reporting으로 직접 오류 이벤트를 전송하여 런타임 비정상 종료를 진단하고 모니터링할 수 있습니다. 라이브러리로 애플리케이션을 계측하면 로그 버킷에서 고객 관리 암호화 키 (CMEK)를 사용하는 경우에도 맞춤 오류 이벤트를 보고하고 오류를 포착할 수 있습니다.

Cloud Run 함수, App Engine, Compute Engine, Google Kubernetes Engine을 비롯한 통합 Google Cloud 서비스에서 실행되는 애플리케이션의 경우 Error Reporting은 Ruby용 Error Reporting 라이브러리 없이도 Cloud Logging에서 오류 이벤트를 자동으로 추론할 수 있습니다. Error Reporting이 로그에서 오류 이벤트를 추론하려면 로그 항목이 오류 형식 요구사항을 따라야 하며, 시작 프로젝트 또는 로그가 라우팅된 대상 프로젝트가 소유한 CMEK가 아닌 로그 버킷에 저장되어야 합니다.

시작하기 전에

Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Error Reporting API , if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Error Reporting API , if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

1. Ruby 2.2+ 이상을 설치합니다.

클라이언트 라이브러리 설치

Ruby용 Error Reporting 라이브러리를 사용하면 거의 모든 곳에서 실행되는 Ruby 애플리케이션에서 보고된 오류 이벤트를 모니터링하고 볼 수 있습니다.

1. google-cloud-error_reporting gem을 Gemfile에 추가합니다.

   gem "google-cloud-error_reporting"

2. 번들러를 사용해 Gem을 설치합니다.

   bundle install

라이브러리 사용 설정

Ruby on Rails를 사용하고 있는 경우, 번들러가 시작되면 자동으로 라이브러리를 애플리케이션에 로드합니다.

다른 랙 기반 애플리케이션은 라이브러리가 제공하는 랙 미들웨어를 사용할 수 있습니다.

require "google/cloud/error_reporting"

use Google::Cloud::ErrorReporting::Middleware

설치에 대한 자세한 내용은 Ruby용 Error Reporting 라이브러리의 문서를 참조하세요. 또한 Issue Tracker를 통해 문제를 보고할 수도 있습니다.

클라이언트 라이브러리 구성

Ruby용 Error Reporting 라이브러리 동작을 맞춤설정할 수 있습니다. 가능한 구성 옵션 목록은 라이브러리 구성을 참조하세요.

Google Cloud에서 앱 실행

projects.events.report를 사용하여 오류 그룹을 만들려면 서비스 계정에 Error Reporting 작성자 역할(roles/errorreporting.writer)이 필요합니다.

일부 Google Cloud 서비스는 적합한 서비스 계정에 Error Reporting 작성자 역할 (roles/errorreporting.writer)을 자동으로 부여합니다. 하지만 일부 서비스의 경우에는 사용자가 적합한 서비스 계정에 이 역할을 부여해야 합니다.

Cloud Run 및 Cloud Run Functions

Cloud Run에서 사용하는 기본 서비스 계정에는 Error Reporting 작성자 역할 (roles/errorreporting.writer) 권한이 있습니다.

Ruby용 Error Reporting 라이브러리는 명시적으로 사용자 인증 정보를 제공하지 않아도 사용 가능합니다.

Cloud Run은 Error Reporting을 사용하도록 자동으로 구성됩니다. 처리되지 않은 JavaScript 예외는 Logging에 나타나고 Ruby용 Error Reporting 라이브러리를 사용하지 않아도 Error Reporting에서 처리합니다.

참고: 로그 항목에 스택 트레이스가 포함되어 있고 로그 항목의 심각도 수준이 설정되지 않았거나 최소 ERROR로 설정되어 있으면 Error Reporting에서 오류 이벤트를 자동으로 만듭니다.

Ruby on Rails 구성 인터페이스 사용

Ruby on Rails 프레임워크에서 Ruby용 Error Reporting 라이브러리를 사용하려면 Ruby on Rails 구성 인터페이스를 통해 매개변수를 제공하세요.

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Error Reporting specific parameters
  config.google_cloud.error_reporting.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.error_reporting.keyfile    = "/path/to/service-account.json"
end

또한 다음을 사용하여 모든 Stackdriver Gem에 대한 공유 구성을 설정할 수 있습니다.

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Shared parameters
  config.google_cloud.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.keyfile    = "/path/to/service-account.json"
end

Error Reporting은 Rails가 프로덕션 모드에서 실행하는 경우 기본적으로 사용 설정됩니다. 개발 모드에서 Error Reporting을 사용 설정하려면 다음을 추가하세요.

# Add this to config/environments/development.rb
Rails.application.configure do |config|
  config.google_cloud.use_error_reporting = true
end

계측 구성 인터페이스 사용

다른 랙 기반 애플리케이션에서 Ruby용 Error Reporting 라이브러리를 사용하려면 구성 인터페이스를 통해 매개변수를 제공하세요.

require "google/cloud/error_reporting"

Google::Cloud.configure do |config|
  # Stackdriver Error Reporting specific parameters
  config.error_reporting.project_id = "YOUR-PROJECT-ID"
  config.error_reporting.keyfile    = "/path/to/service-account.json"
end

또한 다음을 사용하여 모든 Google Cloud Observability gem에 공유 구성을 설정할 수 있습니다.

require "stackdriver"

Google::Cloud.configure do |config|
  # Stackdriver Shared parameters
  config.project_id = "YOUR-PROJECT-ID"
  config.keyfile    = "/path/to/service-account.json"
end

App Engine 가변형 환경

App Engine은 기본 서비스 계정에 Error Reporting 작성자 역할(roles/errorreporting.writer)을 자동으로 부여합니다.

Ruby용 Error Reporting 라이브러리는 명시적으로 사용자 인증 정보를 제공하지 않아도 사용 가능합니다.

Error Reporting은 App Engine 가변형 환경 애플리케이션에서 자동으로 사용 설정되며 추가 설정은 필요하지 않습니다.

참고: stderr에 작성된 오류 로그 항목은 Ruby용 Error Reporting 라이브러리를 직접 사용하지 않아도 Error Reporting에 의해 자동으로 처리됩니다.

Google Kubernetes Engine

Google Kubernetes Engine에 Error Reporting를 사용하려면 다음을 수행합니다.

1. 컨테이너에 사용할 서비스 계정에 Error Reporting 작성자 역할(roles/errorreporting.writer)이 부여되었는지 확인합니다.

   Compute Engine 기본 서비스 계정 또는 커스텀 서비스 계정을 사용할 수 있습니다.

   역할 부여에 대한 상세 설명은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

2. 클러스터를 만들고 클러스터에 cloud-platform 액세스 범위를 부여합니다.

   예를 들어 다음 create 명령어는 cloud-platform 액세스 범위와 서비스 계정을 지정합니다.

   gcloud container clusters create CLUSTER_NAME --service-account  SERVICE_ACCT_NAME --scopes=cloud-platform
   

참고: 클러스터를 만든 후에는 해당 서비스 계정을 변경할 수 없습니다.

Compute Engine

Compute Engine VM 인스턴스에 Error Reporting을 사용하려면 다음을 수행합니다.

1. VM 인스턴스에 사용할 서비스 계정에 Error Reporting 작성자 역할(roles/errorreporting.writer)이 부여되었는지 확인합니다.

   Compute Engine 기본 서비스 계정 또는 커스텀 서비스 계정을 사용할 수 있습니다.

   역할 부여에 대한 상세 설명은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

2. Google Cloud 콘솔에서 VM 인스턴스 페이지로 이동합니다.

   VM 인스턴스로 이동

   검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Compute Engine인 결과를 선택합니다.

3. cloud-platform 액세스 범위를 지정하려는 VM 인스턴스를 선택합니다.

4. 중지를 클릭한 후 수정을 클릭합니다.

5. ID 및 API 액세스 섹션에서 Error Reporting 작성자 역할(roles/errorreporting.writer)이 있는 서비스 계정을 선택합니다.

6. 액세스 범위 섹션에서 모든 Cloud API에 대한 전체 액세스 허용을 선택한 후 변경사항을 저장합니다.

7. 시작/재개를 클릭합니다.

예

랙 기반 프레임워크의 오류 보고

Ruby용 Error Reporting 라이브러리를 사용하면 Error Reporting을 Ruby on Rails 및 Sinatra와 같은 인기 있는 랙 기반 Ruby 웹 프레임워크에 쉽게 통합할 수 있습니다. 라이브러리를 사용 설정하면 랙 스택에서 캡처된 예외를 자동으로 보고합니다.

수동으로 오류 보고

다음 예시와 같이 report 메서드를 호출하여 오류를 수동으로 보고할 수 있습니다.

require "google/cloud/error_reporting"

begin
  raise "Something went wrong"
rescue StandardError => e
  Google::Cloud::ErrorReporting.report e
end

로컬 개발 환경에서 앱 실행

자체 워크스테이션에서 라이브러리를 실행하는 것과 같이 로컬 개발 환경에서 Ruby용 Error Reporting 라이브러리를 사용하려면 Ruby용 Error Reporting 라이브러리에 로컬 애플리케이션 기본 사용자 인증 정보를 제공해야 합니다. 자세한 내용은 Error Reporting에 인증을 참조하세요.

로컬 개발 환경에서 이 페이지의 Ruby 샘플을 사용하려면 gcloud CLI를 설치하고 초기화한 후 사용자 인증 정보로 애플리케이션 기본 사용자 인증 정보를 설정합니다.

1. Google Cloud CLI를 설치합니다.

2. 외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

3. 로컬 셸을 사용하는 경우 사용자 계정에 대한 로컬 인증 사용자 인증 정보를 만듭니다.

   gcloud auth application-default login

   Cloud Shell을 사용하는 경우 이 작업을 수행할 필요는 없습니다.

   참고: gcloud CLI가 계정에 serviceusage.services.use 권한이 없다는 경고를 출력하는 경우 일부 gcloud CLI 명령어와 클라이언트 라이브러리가 작동하지 않을 수 있습니다. 관리자에게 서비스 사용량 소비자 IAM 역할(roles/serviceusage.serviceUsageConsumer)을 부여해 달라고 요청한 후 다음 명령어를 실행하세요.

   gcloud auth application-default set-quota-project PROJECT_ID

   인증 오류가 반환되고 외부 ID 공급업체(IdP)를 사용하는 경우 제휴 ID로 gcloud CLI에 로그인했는지 확인합니다.

자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

projects.events.report 메서드는 또한 API 키를 지원합니다. 인증에 API 키를 사용하려는 경우 로컬 애플리케이션 기본 사용자 인증 정보 파일을 설정할 필요가 없습니다. 자세한 내용은 Google Cloud 인증 문서의 API 키 만들기를 참고하세요.

Ruby on Rails 구성 인터페이스 사용

Ruby on Rails 프레임워크에서 Ruby용 Error Reporting 라이브러리를 사용하려면 Ruby on Rails 구성 인터페이스를 통해 매개변수를 제공하세요.

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Error Reporting specific parameters
  config.google_cloud.error_reporting.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.error_reporting.keyfile    = "/path/to/service-account.json"
end

또한 다음을 사용하여 모든 Stackdriver Gem에 대한 공유 구성을 설정할 수 있습니다.

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Shared parameters
  config.google_cloud.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.keyfile    = "/path/to/service-account.json"
end

Error Reporting은 Rails가 프로덕션 모드에서 실행하는 경우 기본적으로 사용 설정됩니다. 개발 모드에서 Error Reporting을 사용 설정하려면 다음을 추가하세요.

# Add this to config/environments/development.rb
Rails.application.configure do |config|
  config.google_cloud.use_error_reporting = true
end

계측 구성 인터페이스 사용

다른 랙 기반 애플리케이션에서 Ruby용 Error Reporting 라이브러리를 사용하려면 구성 인터페이스를 통해 매개변수를 제공하세요.

require "google/cloud/error_reporting"

Google::Cloud.configure do |config|
  # Stackdriver Error Reporting specific parameters
  config.error_reporting.project_id = "YOUR-PROJECT-ID"
  config.error_reporting.keyfile    = "/path/to/service-account.json"
end

또한 다음을 사용하여 모든 Google Cloud Observability gem에 공유 구성을 설정할 수 있습니다.

require "stackdriver"

Google::Cloud.configure do |config|
  # Stackdriver Shared parameters
  config.project_id = "YOUR-PROJECT-ID"
  config.keyfile    = "/path/to/service-account.json"
end

오류 그룹 보기

Google Cloud 콘솔에서 Error Reporting 페이지로 이동합니다.

Error Reporting으로 이동

검색창을 사용하여 이 페이지를 찾을 수도 있습니다.

자세한 내용은 오류 그룹 보기 및 필터링을 참고하세요.