Membuat kueri dan menganalisis rekaman aktivitas

Observability Analytics memungkinkan Anda menjalankan kueri SQL pada data Cloud Trace untuk menemukan tren performa, menghasilkan insight gabungan, dan memvisualisasikan hasil dalam diagram dan tabel. Kueri dijalankan terhadap tampilan _AllSpans default, yang mencakup semua data trace yang disimpan oleh project Anda, dan Anda dapat menyimpan hasilnya ke dasbor kustom.

Jika Anda ingin memeriksa trace, span, atau atribut span individual, gunakan halaman Trace Explorer. Untuk mengetahui informasi selengkapnya, lihat Menemukan dan menjelajahi trace.

Tentang set data BigQuery tertaut

Anda tidak memerlukan set data BigQuery tertaut untuk mengkueri data trace, atau untuk mengkueri data trace dan log. Untuk skenario tersebut, Anda dapat menggunakan halaman Observability Analytics. Untuk mengetahui informasi tentang cara membuat kueri data log, lihat Membuat kueri dan menganalisis log dengan Observability Analytics.

Anda memerlukan set data BigQuery tertaut jika ingin melakukan salah satu hal berikut:

Dokumen ini tidak menjelaskan cara membuat set data BigQuery tertaut atau cara mengonfigurasi Observability Analytics untuk menjalankan kueri di mesin BigQuery. Untuk mengetahui informasi tentang topik ini, lihat Membuat set data BigQuery tertaut dan Menjalankan kueri trace di mesin BigQuery.

Sebelum memulai

  1. Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

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

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

    8.

  8. Untuk mendapatkan izin yang Anda perlukan untuk memuat halaman Observability Analytics, menulis, menjalankan, dan menyimpan kueri pribadi pada data trace Anda, minta administrator untuk memberi Anda peran IAM berikut:

    • Observability View Accessor (roles/observability.viewAccessor) di tampilan kemampuan observasi yang ingin Anda kueri. Peran ini mendukung kondisi IAM, yang memungkinkan Anda membatasi pemberian akses ke tampilan tertentu. Jika Anda tidak melampirkan kondisi ke pemberian peran, akun utama dapat mengakses semua tampilan kemampuan observasi.
    • Observability Analytics User (roles/observability.analyticsUser) di project Anda. Peran ini berisi izin yang diperlukan untuk menyimpan dan menjalankan kueri pribadi, serta menjalankan kueri bersama.

    Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

    Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Menampilkan skema

Skema menentukan cara data disimpan, yang mencakup kolom dan jenis datanya. Informasi ini penting bagi Anda karena skema menentukan kolom yang Anda kueri dan apakah Anda perlu mentransmisikan kolom ke jenis data yang berbeda. Misalnya, untuk menulis kueri yang menghitung latensi rata-rata permintaan HTTP, Anda perlu mengetahui cara mengakses kolom latensi dan apakah kolom tersebut disimpan sebagai bilangan bulat seperti 100 atau sebagai string seperti "100". Jika data latensi disimpan sebagai string, kueri harus mentransmisikan nilai ke nilai numerik sebelum menghitung rata-rata.

Untuk mengidentifikasi skema, lakukan hal berikut:

  1. Di konsol Google Cloud , buka halaman Observability Analytics:

    Buka Observability Analytics

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Logging.

  2. Di menu Views, buka bagian Traces, lalu pilih _Trace.Spans._AllSpans.

    Panel Schema akan diperbarui. Observability Analytics secara otomatis menyimpulkan kolom dari sebuah kolom jika jenis datanya adalah JSON. Untuk melihat seberapa sering kolom yang disimpulkan ini muncul dalam data Anda, klik Options, lalu pilih View info and description.

    Untuk mempelajari skema, lihat Skema penyimpanan untuk data trace.

    Jika Anda tidak melihat tampilan bernama _Trace.Spans._AllSpans, berarti projectGoogle Cloud Anda tidak berisi bucket kemampuan observasi bernama _Trace. Untuk mengetahui informasi tentang cara mengatasi kegagalan ini, lihat Inisialisasi penyimpanan trace gagal.

Membuat kueri data trace

Bagian ini menjelaskan pendekatan yang dapat Anda gunakan untuk mengkueri data trace:

  • Memuat kueri yang ditentukan sistem, mengedit kueri ini, lalu menjalankan kueri.
  • Masukkan dan jalankan kueri kustom. Misalnya, Anda dapat menempelkan kueri yang Anda miliki atau menulisnya. Kueri kustom dapat menyertakan gabungan, kueri bertingkat, dan pernyataan SQL kompleks lainnya. Untuk contoh, lihat Contoh kueri SQL.
  • Membuat kueri dengan membuat pilihan menu, lalu menjalankan kueri tersebut. Observability Analytics mengonversi pilihan Anda menjadi kueri SQL, yang dapat Anda lihat dan edit.

Memuat, mengedit, dan menjalankan kueri yang ditentukan sistem

  1. Di konsol Google Cloud , buka halaman Observability Analytics:

    Buka Observability Analytics

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Logging.

  2. Di menu Views, buka bagian Traces, lalu pilih _Trace.Spans._AllSpans.

    Jika Anda tidak melihat tampilan bernama _Trace.Spans._AllSpans, berarti projectGoogle Cloud Anda tidak berisi bucket kemampuan observasi bernama _Trace. Untuk mengetahui informasi tentang cara mengatasi kegagalan ini, lihat Inisialisasi penyimpanan trace gagal.

  3. Lakukan salah satu hal berikut:

    • Untuk memuat kueri yang ditentukan sistem yang mengandalkan Query Builder, yang memungkinkan Anda menentukan kueri dengan pilihan menu, pastikan panel Query menampilkan Query Builder. Jika editor SQL ditampilkan, klik  Builder.

    • Untuk memuat kueri yang ditentukan sistem yang mengekstrak nilai JSON, pastikan panel Query menampilkan editor SQL. Jika panel ini menampilkan Pembuat Kueri, klik  SQL.

  4. Di panel Schema, pilih Query, lalu klik Overwrite.

    Panel Query menampilkan kueri yang ditentukan sistem. Jika Anda memilih mode Pembuat Kueri, tetapi ingin melihat kueri SQL, klik  SQL.

  5. Opsional: Ubah kueri.

  6. Untuk menjalankan kueri, buka toolbar dan pilih Run Query.

    Observability Analytics menampilkan hasil kueri dalam tabel. Namun, Anda dapat membuat diagram, dan Anda juga dapat menyimpan tabel atau diagram ke dasbor kustom. Untuk mengetahui informasi selengkapnya, lihat Membuat diagram hasil kueri SQL.

    Jika toolbar menampilkan Run in BigQuery, Anda harus mengalihkan Observability Analytics untuk menggunakan mesin kueri default. Untuk melakukan perubahan ini, di toolbar panel Query, klik Settings, lalu pilih Analytics (default).

Memasukkan dan menjalankan kueri kustom

Untuk memasukkan kueri SQL, lakukan hal berikut:

  1. Di konsol Google Cloud , buka halaman Observability Analytics:

    Buka Observability Analytics

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Logging.

  2. Di panel Query, klik  SQL.

    • Untuk menentukan rentang waktu, sebaiknya gunakan pemilih rentang waktu. Jika Anda menambahkan klausa WHERE yang menentukan kolom timestamp, nilai tersebut akan mengganti setelan di pemilih rentang waktu dan pemilih tersebut akan dinonaktifkan.

    • Untuk contoh, lihat Contoh kueri SQL.

    • Editor SQL menampilkan nama yang sepenuhnya memenuhi syarat untuk tampilan _Trace.Spans._AllSpans, yang memiliki format berikut:

      FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`

      Kolom dalam ekspresi sebelumnya memiliki arti berikut:

      Jika panel kueri menampilkan pesan error yang merujuk ke pernyataan FROM, tampilan tidak dapat ditemukan. Untuk mengetahui informasi tentang cara mengatasi kegagalan ini, lihat Pesan error yang menyatakan bahwa tampilan tidak ada.

  3. Untuk menjalankan kueri, buka toolbar dan pilih Run Query.

    Observability Analytics menampilkan hasil kueri dalam tabel. Namun, Anda dapat membuat diagram, dan Anda juga dapat menyimpan tabel atau diagram ke dasbor kustom. Untuk mengetahui informasi selengkapnya, lihat Membuat diagram hasil kueri SQL.

    Jika toolbar menampilkan Run in BigQuery, Anda harus mengalihkan Observability Analytics untuk menggunakan mesin kueri default. Untuk melakukan perubahan ini, di toolbar panel Query, klik Settings, lalu pilih Analytics (default).

Membuat, mengedit, dan menjalankan kueri

Antarmuka Query Builder memungkinkan Anda membuat kueri dengan membuat pilihan dari menu. Observability Analytics mengonversi pilihan Anda menjadi kueri SQL, yang dapat Anda lihat dan edit. Misalnya, Anda dapat memulai dengan menggunakan antarmuka Pembuat Kueri, lalu beralih ke editor SQL untuk menyaring kueri.

Observability Analytics selalu dapat mengonversi pilihan menu Anda dari antarmuka Pembuat Kueri menjadi kueri SQL. Namun, tidak semua kueri SQL dapat direpresentasikan oleh antarmuka Query Builder. Misalnya, kueri dengan gabungan tidak dapat direpresentasikan oleh antarmuka ini.

Untuk membuat kueri, lakukan hal berikut:

  1. Di konsol Google Cloud , buka halaman Observability Analytics:

    Buka Observability Analytics

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Logging.

  2. Jika panel Kueri menampilkan editor SQL, pilih Pembuat Kueri, yang akan membuka panel Pembuat Kueri.

  3. Gunakan menu Source untuk memilih tampilan yang ingin Anda kueri. Pilihan Anda dipetakan ke klausa FROM dalam kueri SQL.

  4. Opsional: Gunakan menu berikut untuk membatasi atau memformat tabel hasil:

    • Telusuri semua kolom: Telusuri string yang cocok. Pilihan Anda dipetakan ke klausa WHERE dalam kueri SQL.

    • Kolom: Pilih kolom yang muncul di tabel hasil. Pilihan Anda dipetakan ke klausa SELECT dalam kueri SQL.

      Saat Anda memilih nama kolom di menu ini, dialog akan terbuka. Dalam dialog ini, Anda dapat melakukan hal berikut:

      • Gunakan menu untuk menggabungkan atau mengelompokkan data Anda.

        Untuk mencegah error sintaksis, agregasi dan pengelompokan apa pun yang Anda terapkan ke satu kolom akan otomatis diterapkan ke kolom lain juga. Untuk mengetahui contoh cara menggabungkan dan mengelompokkan entri, lihat Mengelompokkan dan menggabungkan data menggunakan Pembuat Kueri.

      • Mengonversi nilai dari jenis apa pun menjadi jenis data lain yang ditentukan. Untuk mengetahui informasi selengkapnya, lihat dokumentasi CAST.

      • Mengekstrak substring nilai menggunakan ekspresi reguler. Untuk mengetahui informasi selengkapnya, lihat dokumentasi REGEXP_EXTRACT.

    • Filter: Tambahkan filter jika Anda ingin membatasi kueri ke span yang berisi atribut atau ID span tertentu. Menu ini mencantumkan semua opsi filter yang tersedia. Pilihan Anda dipetakan ke klausa WHERE dalam kueri SQL.

    • Urutkan Menurut: Tetapkan kolom yang akan diurutkan, dan apakah pengurutan menaik atau menurun. Pilihan Anda dipetakan ke klausa ORDER BY dalam kueri SQL.

    • Limit: Menetapkan jumlah maksimum baris dalam tabel hasil. Pilihan Anda dipetakan ke klausa LIMIT dalam kueri SQL.

  5. Untuk menjalankan kueri, buka toolbar dan pilih Run Query.

    Observability Analytics menampilkan hasil kueri dalam tabel. Namun, Anda dapat membuat diagram, dan Anda juga dapat menyimpan tabel atau diagram ke dasbor kustom. Untuk mengetahui informasi selengkapnya, lihat Membuat diagram hasil kueri SQL.

    Jika toolbar menampilkan Run in BigQuery, Anda harus mengalihkan Observability Analytics untuk menggunakan mesin kueri default. Untuk melakukan perubahan ini, di toolbar panel Query, klik Settings, lalu pilih Analytics (default).

Contoh: Mengelompokkan dan menggabungkan data menggunakan Pembuat Kueri

Saat Anda memilih kolom di Pembuat Kueri, setiap kolom menyertakan menu tempat Anda dapat menambahkan pengelompokan dan agregasi. Pengelompokan memungkinkan Anda mengatur data ke dalam grup berdasarkan nilai satu atau beberapa kolom, dan agregasi memungkinkan Anda melakukan penghitungan pada grup ini untuk menampilkan satu nilai.

Setiap kolom yang Anda pilih di elemen Columns memiliki menu terlampir dengan opsi berikut:

  • Tidak ada: Jangan mengelompokkan atau menggabungkan menurut kolom ini.
  • Aggregate: Mengelompokkan kolom yang tercantum dalam elemen Columns, kecuali jika kolom memiliki pilihan Aggregate. Untuk kolom tersebut, hitung nilainya dengan melakukan operasi pada semua entri di setiap pengelompokan. Operasi ini mungkin untuk menghitung rata-rata kolom atau melakukan sesuatu seperti menghitung jumlah entri di setiap pengelompokan.
  • Group By: Mengelompokkan entri menurut semua kolom yang tercantum dalam elemen Columns.

Contoh ini menunjukkan cara menggunakan Pembuat Kueri untuk mengelompokkan span berdasarkan waktu mulai, nama span, dan jenis span, lalu menghitung durasi rata-rata dalam nanodetik untuk setiap grup:

  1. Di menu Columns, pilih kolom start_time, name, kind, dan duration_nano.
  2. Untuk memotong waktu mulai menjadi jam, luaskan menu di kolom start_time dan pilih Kelompokkan Menurut. Pastikan menu perincian ditetapkan ke Hour.

  3. Klik Terapkan.

    Jika Anda memilih Kelompokkan Menurut untuk kolom mana pun, sistem akan mengelompokkan entri berdasarkan semua kolom. Dalam contoh ini, entri dikelompokkan menurut nilai start_time yang dipotong, nama span, jenis span, dan nilai durasi.

    Namun, tujuan untuk contoh ini adalah mengelompokkan entri berdasarkan waktu yang dipotong, nama span, dan jenis span, lalu untuk setiap grup, menghitung durasi rata-rata. Pada langkah berikutnya, Anda akan mengubah pengelompokan dan menambahkan agregasi.

  4. Luaskan menu di kolom duration_nano, pilih Aggregate, lalu tetapkan kolom Aggregation ke Average.

    Saat Anda menjalankan kueri, setiap baris sesuai dengan grup, yang terdiri dari waktu yang dipotong, nama span, dan jenis span. Entri terakhir di setiap baris adalah durasi rata-rata untuk semua entri dalam grup tersebut.

    Hasil kueri ini mirip dengan berikut ini:

    +-----------------------------------+----------------+----------+-----------------------+
| Row | hour_timestamp              | span_name      | kind     | average_duration_nano |
|     | TIMESTAMP                   | STRING         | INTEGER  | FLOAT                 |
+-----+-----------------------------+-----------+---------------+-----------------------+
| 1   | 2025-10-09 13:00:00.000 EDT | http.receive   | 3        | 122138.22813990474
| 2   | 2025-10-09 13:00:00.000 EDT | query.request  | 1        | 6740819304.390297
| 3   | 2025-10-09 13:00:00.000 EDT | client.handler | 2        | 6739339098.409376

  5. Kueri Anda dapat menyertakan beberapa agregasi. Misalnya, untuk menambahkan kolom yang menghitung jumlah entri di setiap grup, lakukan hal berikut:

    1. Di elemen Columns, klik Add column.
    2. Pilih Semua (*).
    3. Dalam dialog, pilih Aggregate, pilih Count untuk Aggregation, lalu pilih Apply.

    Dengan perubahan ini, pengelompokan tetap sama. Entri dikelompokkan berdasarkan waktu mulai yang dipotong, nama span, dan jenis span. Namun, untuk setiap grup, kueri menghitung durasi rata-rata dan jumlah entri.

Kueri SQL yang sesuai untuk contoh sebelumnya adalah sebagai berikut:

WITH
  scope_query AS (
  SELECT
    *
  FROM
    `PROJECT_ID.us._Trace.Spans._AllSpans` )
SELECT
  -- Report the truncated start time, span name, span kind, average duration and number
  -- of entries for each group.
  TIMESTAMP_TRUNC( start_time, HOUR ) AS hour_start_time,
  name AS span_name,
  kind,
  AVG( duration_nano ) AS average_duration_nano,
  COUNT( * ) AS count_all
FROM
  scope_query
GROUP BY
  TIMESTAMP_TRUNC( start_time, HOUR ),
  name,
  kind
LIMIT
  100

Langkah berikutnya