트레이스 버킷 나열 및 데이터 세트 관리

Observability API 또는 Google Cloud CLI를 사용하여 관측 가능성 버킷을 확인하고, 데이터 세트와 뷰를 검사하고, SQL로 저장된 trace 데이터를 분석할 링크를 만들 수 있습니다.

개념적 배경 및 스토리지 세부정보는 trace 스토리지 개요 및 trace 스키마를 참고하세요.

시작하기 전에

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

프로젝트 및 역할 구성

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

  2. 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

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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

  5. 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

  6. Verify that billing is enabled for your Google Cloud project.

  7. 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

    8.

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

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

사용할 인터페이스를 선택합니다.

gcloud

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

Cloud Shell 활성화

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

REST

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

    Google Cloud CLI를 설치합니다.

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

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

관측 가능성 버킷 나열

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

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

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 참조 문서를 참고하세요.

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

이 섹션에서는 모니터링 가능성 버킷에서 모니터링 가능성 데이터 세트를 나열하는 방법을 설명합니다. 관측 가능성 버킷은 데이터를 저장하는 데이터 세트의 관리 컨테이너입니다. Google Cloud Observability에서 버킷을 만들면 데이터 세트가 자동으로 생성됩니다.

gcloud

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

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

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

Linux, macOS 또는 Cloud Shell

gcloud beta observability buckets datasets list \
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows(PowerShell)

gcloud beta observability buckets datasets list `
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows(cmd.exe)

gcloud beta observability buckets datasets list ^
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

응답에는 각 데이터 세트의 이름, 설명, 생성 시간이 나열됩니다. 다음은 명령어가 성공한 경우의 응답 예시입니다. 

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

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/datasets/DATASET_ID

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

{
  "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 참조 문서를 참고하세요.

데이터 세트의 뷰 나열

이 섹션에서는 관측 가능성 보기를 나열하는 방법을 설명합니다. 각 관측 가능성 데이터 세트는 하나 이상의 뷰를 호스팅합니다. 뷰는 데이터 세트의 항목 하위 집합에 대한 읽기 액세스 권한을 제공합니다. Google Cloud Observability는 데이터 세트를 만들 때 뷰를 만듭니다. 이 뷰에는 데이터 세트의 모든 데이터가 포함됩니다.

gcloud

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

  • DATASET_ID: 데이터 세트 ID입니다. 트레이스 데이터는 Spans라는 데이터 세트에 저장됩니다.
  • BUCKET_ID: 관측 가능성 버킷의 ID입니다. 예를 들어 이 ID는 _Trace일 수 있습니다.
  • LOCATION: 모니터링 가능성 버킷의 위치입니다.
  • PROJECT_ID: 프로젝트의 식별자입니다.

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

Linux, macOS 또는 Cloud Shell

gcloud beta observability buckets datasets views list \
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID \
 --bucket=BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows(PowerShell)

gcloud beta observability buckets datasets views list `
 --dataset=projects/