Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

관측 가능성 버킷 만들기

프로젝트에서 추적 데이터를 수신하기 전에 _Trace 관측 가능성 버킷을 수동으로 만들어 스토리지 위치와 고객 관리 암호화 키 (CMEK) 설정을 맞춤설정할 수 있습니다. 이 버킷이 존재하기 전에 Google Cloud 프로젝트에서 추적 데이터를 수집하면 Google Cloud Observability에서 프로젝트의 관측 가능성 버킷 기본 설정을 사용하여 버킷을 자동으로 프로비저닝합니다.

Google Cloud Observability에서 데이터를 저장하는 방법에 대한 자세한 내용은 스토리지 개요를 참고하세요.

조직 정책과의 상호작용

관측 가능성 버킷을 생성하라는 요청은 명령 매개변수가 조직 정책을 준수하는지 확인합니다. 예를 들어 조직 정책에서 리소스 위치를 제한하는 경우 제한된 위치를 지정하면 버킷 생성이 실패합니다.

관측 가능성 버킷의 기본 설정과의 상호작용

Google Cloud Observability가 데이터 수집으로 인해 관측 가능성 버킷을 자동으로 만드는 경우 버킷의 상위 리소스에 적용되는 관측 가능성 버킷의 기본 설정을 사용합니다. 이러한 기본 설정은 상위 요소나 상위 요소의 계층적 상위 요소에 정의되어 있을 수 있으며 다음을 지정합니다.

스토리지 위치입니다.
저장된 데이터에 사용할 Cloud KMS 키입니다.

관측 가능성 버킷을 만들 때는 위치를 지정해야 합니다. 만들기 요청에서 다른 키를 명시적으로 지정하지 않는 한 Google Cloud Observability는 기본 설정에 정의된 Cloud KMS 키를 적용합니다.

해당 기본 설정에서 Cloud KMS 키를 지정하는 경우 Google 기본 암호화로 버킷을 만들 수 없습니다. Google 기본 암호화를 사용하려면 기본 설정에 Cloud KMS 키가 구성되어 있지 않은지 확인하세요.

관측 가능성 버킷의 기본 설정에 대한 자세한 내용은 관측 가능성 버킷의 기본값 설정을 참고하세요.

제한사항

다음 제한사항이 적용됩니다.

지원되는 위치를 지정해야 합니다.
BUCKET_ID는 _Trace이어야 합니다.
표시 이름은 인코딩된 바이트 100개를 초과할 수 없습니다.
설명은 인코딩된 바이트 1,000개를 초과할 수 없습니다.
데이터는 30일 동안 저장됩니다. 보관 기간을 생략하거나 30로 설정해야 합니다.
Cloud KMS 키를 제공하는 경우 키의 위치가 모니터링 가능성 버킷의 상위 위치와 정확히 일치해야 합니다.
관측 가능성 버킷은 Google Cloud 프로젝트에서만 만들 수 있습니다.
Google Cloud 프로젝트에는 _Trace라는 모니터링 가능성 버킷이 최대 하나 있을 수 있습니다.

시작하기 전에

프로젝트와 IAM 역할을 구성하고 사용할 인터페이스를 선택합니다.

프로젝트 및 역할 구성

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Roles required to enable APIs

Enable the API

관측 가능성 버킷을 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 관측 가능성 편집자 (roles/observability.editor) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

인터페이스 구성

gcloud

Google Cloud 콘솔에서 Cloud Shell을 활성화합니다.

Cloud Shell 활성화

Google Cloud 콘솔 하단에 Cloud Shell 세션이 시작되고 명령줄 프롬프트가 표시됩니다. Cloud Shell은 Google Cloud CLI가 사전 설치된 셸 환경으로, 현재 프로젝트의 값이 이미 설정되어 있습니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.

Terraform

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

Google Cloud CLI를 설치합니다.
외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.
로컬 셸을 사용하는 경우 사용자 계정에 대한 로컬 인증 사용자 인증 정보를 만듭니다.
```
gcloud auth application-default login
```
Cloud Shell을 사용하는 경우 이 작업을 수행할 필요는 없습니다.

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

자세한 내용은 Google Cloud 인증 문서의 로컬 개발 환경의 ADC 설정을 참고하세요.

REST

로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공한 사용자 인증 정보를 사용합니다.

Google Cloud CLI를 설치합니다.

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

자세한 내용은 Google Cloud 인증 문서의 REST 사용을 위한 인증을 참조하세요.

Cloud KMS 키 구성

(선택사항) 관측 가능성 버킷을 만들고 Cloud KMS 키를 지정하려면 다음을 실행하세요.

Cloud Key Management Service API를 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할을 부여하는 방법 알아보기
API 사용 설정하기
키링 및 키를 만듭니다.

관측 가능성 버킷의 위치는 키의 위치와 일치해야 합니다.
PROJECT_ID를 프로젝트 ID로 바꾸고 다음 명령어를 실행합니다.
```
gcloud beta observability settings describe \
--location=global --project=PROJECT_ID
```
위 명령어는 기본 저장소 위치를 구성했는지 확인합니다. 또한 이 계정이 없는 경우 Google Cloud Observability 서비스 계정을 만듭니다. 명령어의 응답에는 서비스 계정의 ID가 나열됩니다.
Google Cloud Observability 서비스 계정에 Cloud KMS CryptoKey 암호화/복호화 역할을 부여합니다.
```
gcloud kms keys add-iam-policy-binding \
--project=KMS_PROJECT_ID \
--member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-observability.iam.gserviceaccount.com \
--role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=KMS_KEY_LOCATION \
--keyring=KMS_KEY_RING \
KMS_KEY_NAME
```
이전 명령어를 실행하기 전에 다음을 바꿉니다.
- KMS_PROJECT_ID: 고유한 영숫자 식별자. Google Cloud 프로젝트 이름과 Cloud KMS가 실행되는 Google Cloud 프로젝트의 임의로 할당된 번호로 구성됩니다. 이 식별자를 가져오는 방법에 대한 자세한 내용은 프로젝트 식별을 참조하세요.
- service-PROJECT_NUMBER: 이전 단계의 응답에 나열된 관측 가능성 서비스 계정의 이름입니다.
- KMS_KEY_LOCATION: Cloud KMS 키 리전
- KMS_KEY_RING: Cloud KMS 키링의 이름
- KMS_KEY_NAME: Cloud KMS 키 이름. projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY 형식으로 지정됩니다.

관측 가능성 버킷 만들기

gcloud

지원되지 않음.

Terraform

관측 가능성 버킷을 만들려면 Terraform 리소스 google_observability_bucket를 사용하고 다음 필드를 설정합니다.

project: 프로젝트의 ID입니다.
location: 모니터링 가능성 버킷의 위치입니다. 자세한 내용은 위치를 참고하세요.
bucket_id: 관측 가능성 버킷의 ID입니다. 이 필드는 _Trace로 설정해야 합니다.

설명과 표시 이름을 설정하고 CMEK를 제공할 수도 있습니다. 자세한 내용은 리소스 문서를 참고하세요.

REST

모니터링 가능성 버킷을 만들려면 projects.locations.buckets.create에 요청을 보냅니다.

다음 형식을 갖는 상위 매개변수를 지정해야 합니다.

projects/PROJECT_ID/locations/LOCATION

이전 표현식의 필드는 다음과 같은 의미를 갖습니다.

PROJECT_ID: 프로젝트 식별자
LOCATION: 관측 가능성 버킷의 위치입니다.

요청 본문은 Bucket 객체입니다. 다음 입력란을 작성하세요.

name: 이 필드를 다음으로 설정합니다.

projects/PROJECT_ID/locations/LOCATION/buckets/_Trace

선택사항: displayName 및 description 필드에 값을 제공합니다.
선택사항: CMEK를 제공합니다. 지정된 경우 이 키는 저장된 데이터를 암호화합니다.

CMEK를 제공하지 않으면 버킷의 상위 리소스에 적용되는 기본 설정에 따라 암호화 키가 결정됩니다. 기본 설정에서 Cloud KMS 키를 지정하면 해당 키가 저장된 데이터를 암호화합니다. 그렇지 않으면 Google 기본 암호화가 사용됩니다.

응답은 Operation 객체입니다. Operation.done 필드가 true로 설정될 때까지 projects.locations.operations.get 메서드를 폴링합니다. Operation 구조의 다른 필드는 요청의 성공 또는 실패에 관한 정보를 제공합니다.

관측 가능성 버킷 나열

모니터링 가능성 버킷을 나열하여 생성 요청이 성공적으로 완료되었는지 확인할 수 있습니다.

이 섹션에서는 관측 가능성 버킷을 나열하는 방법을 설명합니다. 관측 가능성 버킷은 데이터를 저장하는 데이터 세트의 관리 엔티티입니다.

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

LOCATION: 모니터링 가능성 버킷의 위치입니다. 위치와 관계없이 모든 관측 가능성 버킷을 나열하려면 위치를 하이픈 (-)으로 설정합니다.
PROJECT_ID: 프로젝트의 식별자입니다.

gcloud beta observability buckets list 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud beta observability buckets list \
 --location=LOCATION --project=PROJECT_ID

Windows(PowerShell)

gcloud beta observability buckets list `
 --location=LOCATION --project=PROJECT_ID

Windows(cmd.exe)

gcloud beta observability buckets list ^
 --location=LOCATION --project=PROJECT_ID

응답에는 각 관측 가능성 버킷의 이름, 설명, 생성 시간이 나열됩니다. 다음은 명령어가 성공한 경우의 응답 예시입니다.

---
createTime: '2026-01-21T21:39:22.381083860Z'
description: Bucket for storing spans from Cloud Trace.
name: projects/my-project/locations/us/buckets/_Trace

Terraform

Terraform을 사용하여 관측 가능성 버킷을 나열할 수 없습니다.

REST

프로젝트 및 특정 위치에 있는 관측 가능성 버킷을 나열하려면 projects.locations.buckets.list 메서드를 사용하세요.

다음 형식을 갖는 상위 매개변수를 지정해야 합니다.

projects/PROJECT_ID/locations/LOCATION

이전 표현식의 필드는 다음과 같은 의미를 갖습니다.

PROJECT_ID: 프로젝트 식별자
LOCATION: 관측 가능성 버킷의 위치입니다. LOCATION을 하이픈 (-)으로 설정하면 프로젝트의 모든 관측 가능성 버킷이 나열됩니다.

응답은 Bucket 객체의 배열입니다. 각 객체의 경우 name 필드 값의 형식은 다음과 같습니다.

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

다음은 샘플 응답을 보여줍니다.

{
  "buckets": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace",
      "description": "Trace Bucket",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
      "retentionDays": 30
    }
  ]
}

Observability API를 사용하여 ID가 BUCKET_ID인 버킷에 관한 자세한 정보를 확인할 수 있습니다. 예를 들어 해당 버킷의 데이터 세트와 각 데이터 세트의 뷰 및 링크를 나열할 수 있습니다. 자세한 내용은 관측 가능성 API 참조 문서를 참고하세요.

다음 단계

원격 분석 보기 및 분석
관측 가능성 버킷의 기본값 설정: 관측 가능성 버킷의 기본 스토리지 위치와 기본 고객 관리 암호화 키 (CMEK)를 구성합니다.

관측 가능성 버킷 만들기 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

조직 정책과의 상호작용

관측 가능성 버킷의 기본 설정과의 상호작용

제한사항

시작하기 전에

프로젝트 및 역할 구성

인터페이스 구성

gcloud

Terraform

REST

Cloud KMS 키 구성

관측 가능성 버킷 만들기

gcloud

Terraform

REST

관측 가능성 버킷 나열

gcloud

Linux, macOS 또는 Cloud Shell

Windows(PowerShell)

Windows(cmd.exe)

Terraform

REST

다음 단계

관측 가능성 버킷 만들기