관측 가능성 버킷 관리

이 문서에서는 관측 가능성 API를 사용하여 관측 가능성 버킷에 관한 정보를 가져오는 방법을 설명합니다. 데이터 세트, 링크, 뷰를 나열하는 방법에 관한 정보도 포함되어 있습니다. Google Cloud Observability에서 데이터를 저장하는 방법에 대해 자세히 알아보려면 스토리지 개요를 참고하세요.

추적 데이터는 관측 가능성 버킷에 저장됩니다. 이 문서에서는 트레이스 데이터의 스토리지를 관리하는 방법을 설명하지만 저장된 데이터의 형식은 설명하지 않습니다. 해당 주제에 대한 자세한 내용은 추적 스키마를 참고하세요.

이 문서는 로그 또는 측정항목 데이터의 스토리지에는 적용되지 않습니다. 로그 및 측정항목 데이터는 모니터링 가능성 버킷에 저장되지 않습니다.

시작하기 전에

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

Google Cloud CLI를 설치합니다.

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

gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.

gcloud init

Google Cloud 프로젝트를 만들거나 선택합니다.

프로젝트를 선택하거나 만드는 데 필요한 역할

프로젝트 선택: 프로젝트를 선택하는 데는 특정 IAM 역할이 필요하지 않습니다. 역할이 부여된 프로젝트를 선택하면 됩니다.
프로젝트 만들기: 프로젝트를 만들려면 resourcemanager.projects.create 권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기

Google Cloud 프로젝트를 만듭니다.
```
gcloud projects create PROJECT_ID
```
PROJECT_ID를 만들려는 Google Cloud 프로젝트의 이름으로 바꿉니다.
생성한 Google Cloud 프로젝트를 선택합니다.
```
gcloud config set project PROJECT_ID
```
PROJECT_ID을 Google Cloud 프로젝트 이름으로 바꿉니다.

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

관측 가능성 API를 사용 설정합니다.

API 사용 설정에 필요한 역할

API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할 (roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기

gcloud services enable observability.googleapis.com

사용자 계정에 역할을 부여합니다. 다음 IAM 역할마다 다음 명령어를 1회 실행합니다. roles/observability.viewer

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID입니다.
USER_IDENTIFIER: 사용자 계정의 식별자입니다. 예를 들면 myemail@example.com입니다.
ROLE: 사용자 계정에 부여하는 IAM 역할입니다.

Google Cloud CLI를 설치합니다.

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

gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.

gcloud init

Google Cloud 프로젝트를 만들거나 선택합니다.

프로젝트를 선택하거나 만드는 데 필요한 역할

프로젝트 선택: 프로젝트를 선택하는 데는 특정 IAM 역할이 필요하지 않습니다. 역할이 부여된 프로젝트를 선택하면 됩니다.
프로젝트 만들기: 프로젝트를 만들려면 resourcemanager.projects.create 권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기

Google Cloud 프로젝트를 만듭니다.
```
gcloud projects create PROJECT_ID
```
PROJECT_ID를 만들려는 Google Cloud 프로젝트의 이름으로 바꿉니다.
생성한 Google Cloud 프로젝트를 선택합니다.
```
gcloud config set project PROJECT_ID
```
PROJECT_ID을 Google Cloud 프로젝트 이름으로 바꿉니다.

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

관측 가능성 API를 사용 설정합니다.

API 사용 설정에 필요한 역할

gcloud services enable observability.googleapis.com

사용자 계정에 역할을 부여합니다. 다음 IAM 역할마다 다음 명령어를 1회 실행합니다. roles/observability.viewer

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID입니다.
USER_IDENTIFIER: 사용자 계정의 식별자입니다. 예를 들면 myemail@example.com입니다.
ROLE: 사용자 계정에 부여하는 IAM 역할입니다.

관측 가능성 버킷 나열

REST

프로젝트 및 특정 위치에 있는 모니터링 가능성 버킷을 나열하려면 projects.locations.buckets.list 엔드포인트로 요청을 보냅니다.

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

projects/PROJECT_ID/locations/LOCATION

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

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

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

예를 들어 상위 매개변수가 projects/my-project/locations/us로 설정된 buckets.list 엔드포인트에 명령어가 실행된 경우 응답은 다음과 같습니다.

{
  "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
    }
  ]
}

ID가 BUCKET_ID인 버킷에 대한 자세한 정보를 얻기 위해 다른 Observability API 엔드포인트에 명령어를 실행할 수 있습니다. 예를 들어 해당 버킷의 데이터 세트와 각 데이터 세트의 뷰 및 링크를 나열할 수 있습니다. 관측 가능성 API 엔드포인트의 전체 목록은 관측 가능성 API 참조 문서를 참고하세요.

관측 가능성 버킷의 데이터 세트 나열

REST

모니터링 가능성 버킷의 데이터 세트를 나열하려면 projects.locations.buckets.datasets.list 엔드포인트에 요청을 보냅니다.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

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

PROJECT_ID: 프로젝트 식별자
LOCATION: 관측 가능성 버킷의 위치입니다.
BUCKET_ID: 관측 가능성 버킷의 ID입니다. 예를 들어 이 ID는 _Trace일 수 있습니다.

응답은 Dataset 객체의 배열입니다. 각 객체의 name 필드 값은 다음 형식을 갖습니다.

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/dataset/DATASET_ID

예를 들어 projects/my-project/locations/us/buckets/_Trace로 설정된 상위 매개변수와 함께 buckets.datasets.list 엔드포인트에 명령어가 실행된 경우 응답은 다음과 같습니다.

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

다른 Observability API 엔드포인트에 명령어를 실행하여 ID가 DATASET_ID인 데이터 세트에 관한 정보를 가져올 수 있습니다. 예를 들어 각 데이터 세트의 뷰와 링크를 나열할 수 있습니다. 관측 가능성 API 엔드포인트의 전체 목록은 관측 가능성 API 참조 문서를 참고하세요.

데이터 세트의 뷰 나열

REST

데이터 세트의 뷰를 나열하려면 projects.locations.buckets.datasets.views.list 엔드포인트에 요청을 보냅니다.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/views

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

PROJECT_ID: 프로젝트 식별자
LOCATION: 관측 가능성 버킷의 위치입니다.
BUCKET_ID: 관측 가능성 버킷의 ID입니다. 예를 들어 이 ID는 _Trace일 수 있습니다.
DATASET_ID: 쿼리할 데이터 세트의 ID입니다. 예를 들어 이 ID는 Spans일 수 있습니다.

응답은 View 객체의 배열입니다. 각 객체의 name 필드 값은 다음 형식을 갖습니다.

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/views/OBS_VIEW_ID

앞의 표현식에서 뷰의 ID는 OBS_VIEW_ID로 표시됩니다. 예를 들어 이 필드의 값은 _AllSpans일 수 있습니다.

예를 들어 projects/my-project/locations/us/buckets/_Trace/datasets/Spans/views로 설정된 상위 매개변수와 함께 buckets.datasets.views.list 엔드포인트에 명령어가 실행된 경우 응답은 다음과 같습니다.

{
  "views": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans/views/_AllSpans",
      "filter": "",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
    }
  ]
}

관측 가능성 API 엔드포인트의 전체 목록은 관측 가능성 API 참조 문서를 참고하세요.

데이터 세트의 링크 나열

REST

데이터 세트의 링크를 나열하려면 projects.locations.buckets.datasets.links.list 엔드포인트로 요청을 보냅니다.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID

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

PROJECT_ID: 프로젝트 식별자
LOCATION: 관측 가능성 버킷의 위치입니다.
BUCKET_ID: 관측 가능성 버킷의 ID입니다. 예를 들어 이 ID는 _Trace일 수 있습니다.
DATASET_ID: 쿼리할 데이터 세트의 ID입니다. 예를 들어 이 ID는 Spans일 수 있습니다.

응답은 Link 객체의 배열입니다. 각 객체의 name 필드 값은 다음 형식을 갖습니다.

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/links/LINK_ID

LINK_ID은 BigQuery 데이터 세트의 이름입니다. 이 필드는 Google Cloud 프로젝트에 대해 전역적으로 고유합니다.

예를 들어 projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links로 설정된 상위 매개변수와 함께 buckets.datasets.links.list 엔드포인트에 명령어가 실행된 경우 응답은 다음과 같습니다.

{
  "links": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links/my_link",
      "description": "My link for traces to BigQuery",
      "createTime": "2025-01-12T15:42:30.988919645Z"
    }
  ]
}

관측 가능성 API 엔드포인트의 전체 목록은 관측 가능성 API 참조 문서를 참고하세요.

데이터 세트에 링크 만들기

데이터 세트에 링크를 만들어 BigQuery에서 추적 데이터를 쿼리할 수 있습니다. 데이터 세트에 연결된 Link 객체를 삭제할 수도 있습니다.

시작하기 전에

데이터 세트에 링크를 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

모니터링 가능성 편집자(roles/observability.editor)
BigQuery 사용자(roles/bigquery.user)

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

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

연결된 BigQuery 데이터 세트 만들기

REST

BigQuery 데이터 세트에 대한 링크를 만들려면 projects.locations.buckets.datasets.links.create 엔드포인트에 요청을 전송합니다.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID

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

PROJECT_ID: 프로젝트 식별자
LOCATION: 관측 가능성 버킷의 위치입니다.
BUCKET_ID: 관측 가능성 버킷의 ID입니다. 예를 들어 이 ID는 _Trace일 수 있습니다.
DATASET_ID: 쿼리할 데이터 세트의 ID입니다. 예를 들어 이 ID는 Spans일 수 있습니다.

이 명령어에는 쿼리 매개변수와 요청 본문이 필요합니다.

쿼리 매개변수 linkId를 지정하고 BigQuery 데이터 세트의 이름으로 설정해야 합니다. 예를 들면 linkId="my_link"입니다. BigQuery 데이터 세트 이름은 Google Cloud 프로젝트에서 고유해야 하며, 100자로 제한되고 문자, 숫자, 밑줄만 포함할 수 있습니다.
요청 본문은 Link 객체입니다. name 필드의 값은 다음 형식을 갖습니다.
```
projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/dataset/DATASET_ID/links/LINK_ID
```
name 필드에 제공하는 값은 쿼리 매개변수에서 참조하는 연결된 BigQuery 데이터 세트와 일치해야 합니다.

LINK_ID 필드는 BigQuery 데이터 세트의 이름입니다.

응답은 Operation 객체입니다. 이 객체에는 메서드의 진행률에 대한 정보가 포함됩니다. 메서드가 완료되면 Operation 객체에 상태 데이터가 포함됩니다.

관측 가능성 API 엔드포인트의 전체 목록은 관측 가능성 API 참조 문서를 참고하세요.

다음 단계

원격 분석 쿼리에 대해 알아보려면 원격 분석 보기 및 분석을 참고하세요.

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

시작하기 전에

관측 가능성 버킷 나열

REST

관측 가능성 버킷의 데이터 세트 나열

REST

데이터 세트의 뷰 나열

REST

데이터 세트의 링크 나열

REST

데이터 세트에 링크 만들기

시작하기 전에

연결된 BigQuery 데이터 세트 만들기

REST

다음 단계

관측 가능성 버킷 관리