Membuat kueri dan menganalisis rekaman aktivitas

Dokumen ini menjelaskan cara membuat kueri dan menganalisis data pelacakan menggunakan Observability Analytics, yang menyediakan antarmuka kueri berbasis SQL. SQL memungkinkan Anda melakukan analisis gabungan, yang dapat membantu Anda menghasilkan insight dan mengidentifikasi tren. Untuk melihat hasil kueri, gunakan tabel atau diagram. Anda juga dapat menyimpan tabel dan diagram ini ke dasbor kustom.

Jika ingin melihat atau menjelajahi pelacakan atau rentang individual, atau melihat atribut yang dilampirkan ke rentang, gunakan halaman Trace Explorer. Untuk mengetahui informasi tentang halaman tersebut, lihat Menemukan dan menjelajahi pelacakan.

Untuk pelacakan, Anda dapat membuat kueri bucket observabilitas bernama _Trace. Satu tampilan, _AllSpans, tersedia untuk kueri. Untuk mempelajari lebih lanjut cara data pelacakan disimpan, lihat Ringkasan penyimpanan.

Tentang set data BigQuery tertaut

Anda tidak memerlukan set data BigQuery tertaut untuk membuat kueri data pelacakan, atau untuk membuat kueri data pelacakan 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 tertaut atau cara mengonfigurasi Observability Analytics untuk menjalankan kueri di slot yang dicadangkan. Untuk mengetahui informasi tentang topik ini, lihat Membuat kueri set data BigQuery tertaut.

Sebelum memulai

  1. Login keakun Anda. Google Cloud 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.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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 Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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 pelacakan, minta administrator untuk memberi Anda peran IAM berikut:

    • Pengakses Lihat Observabilitas (roles/observability.viewAccessor) pada tampilan observabilitas yang ingin Anda kueri. Peran ini mendukung kondisi IAM, yang memungkinkan Anda membatasi pemberian ke tampilan tertentu. Jika Anda tidak melampirkan kondisi ke pemberian peran, akun utama dapat mengakses semua tampilan observabilitas.
    • Pengguna Observability Analytics (roles/observability.analyticsUser) di project Anda. Peran ini berisi izin yang diperlukan untuk menyimpan dan menjalankan kueri pribadi, serta menjalankan kueri bersama.
    • Pengakses Lihat Log (roles/logging.viewer) di project Anda.

    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 mengonversi kolom ke jenis data yang berbeda. Misalnya, untuk menulis kueri yang menghitung latensi rata-rata permintaan HTTP, Anda harus 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 mengonversi nilai ke nilai numerik sebelum menghitung rata-rata.

Untuk mengidentifikasi skema, lakukan hal berikut:

  1. Di Google Cloud konsol, 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 saat jenis datanya adalah JSON. Untuk melihat frekuensi kolom yang disimpulkan ini muncul dalam data Anda, klik Options , lalu pilih View info and description.

    Untuk mempelajari skema, lihat Skema penyimpanan untuk data pelacakan.

    Jika Anda tidak melihat tampilan bernama _Trace.Spans._AllSpans,Google Cloud project Anda tidak berisi bucket observabilitas bernama _Trace. Untuk mengetahui informasi tentang cara mengatasi kegagalan ini, lihat Inisialisasi penyimpanan pelacakan gagal.

Membuat kueri data pelacakan

Bagian ini menjelaskan pendekatan yang dapat Anda gunakan untuk membuat kueri data pelacakan:

  • Memuat kueri yang ditetapkan sistem, mengedit kueri ini, lalu menjalankan kueri.
  • Memasukkan dan menjalankan kueri kustom. Misalnya, Anda dapat menempelkan kueri yang Anda miliki atau menulis kueri. Kueri kustom dapat mencakup gabungan, kueri bertingkat, dan pernyataan SQL kompleks lainnya. Untuk contohnya, 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 ditetapkan sistem

  1. Di Google Cloud konsol, 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,Google Cloud project Anda tidak berisi bucket observabilitas bernama _Trace. Untuk mengetahui informasi tentang cara mengatasi kegagalan ini, lihat Inisialisasi penyimpanan pelacakan gagal.

  3. Lakukan salah satu hal berikut:

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

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

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

    Panel Query menampilkan kueri yang ditetapkan sistem. Jika Anda memilih mode Query Builder, 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 Google Cloud konsol, 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 contohnya, lihat Contoh kueri SQL.

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

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

      Kolom dalam ekspresi sebelumnya memiliki arti berikut:

      Jika panel kueri menampilkan pesan error yang mereferensikan pernyataan FROM, tampilan tidak dapat ditemukan. Untuk mengetahui informasi tentang cara mengatasi kegagalan ini, lihat Pesan error yang menyatakan 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 mulai menggunakan antarmuka Query Builder , lalu beralih ke editor SQL untuk menyempurnakan kueri.

Observability Analytics selalu dapat mengonversi pilihan menu Anda dari antarmuka Query Builder 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 Google Cloud konsol, 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 Query menampilkan editor SQL, pilih Builder, yang akan membuka panel Query Builder.

  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:

    • Search all fields: 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.

        Untuk mencegah error sintaksis, setiap penggabungan dan pengelompokan yang Anda terapkan ke satu kolom akan otomatis diterapkan ke kolom lain juga. Untuk contoh cara menggabungkan dan mengelompokkan entri, lihat Mengelompokkan dan menggabungkan data menggunakan Query Builder.

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

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

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

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

    • Limit: Tetapkan 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 Query Builder

Saat Anda memilih kolom di Query Builder, setiap kolom akan menyertakan menu tempat Anda dapat menambahkan pengelompokan dan penggabungan. Pengelompokan memungkinkan Anda mengatur data ke dalam grup berdasarkan nilai satu atau beberapa kolom, dan penggabungan 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:

  • None: Jangan kelompokkan atau gabungkan menurut kolom ini.
  • Aggregate: Kelompokkan kolom yang tercantum di elemen Columns, kecuali jika kolom memiliki pilihan Aggregate. Untuk kolom tersebut, hitung nilai 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: Kelompokkan entri menurut semua kolom yang tercantum di elemen Columns.

Contoh ini menunjukkan cara menggunakan Query Builder untuk mengelompokkan rentang menurut waktu mulai, nama rentang, dan jenis rentang, 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 memangkas waktu mulai ke jam, luaskan menu di kolom start_time, lalu pilih Group By. Pastikan menu granularity ditetapkan ke Hour.

  3. Klik Apply.

    Saat Anda memilih Group By untuk kolom mana pun, sistem akan mengelompokkan entri menurut semua kolom. Dalam contoh ini, entri dikelompokkan menurut nilai start_time yang dipangkas, nama rentang, jenis rentang, dan nilai durasi.

    Namun, tujuan contoh ini adalah mengelompokkan entri menurut waktu yang dipangkas, nama rentang, dan jenis rentang, lalu untuk setiap grup, menghitung durasi rata-rata. Pada langkah berikutnya, Anda akan mengubah pengelompokan dan menambahkan penggabungan.

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

    Saat Anda menjalankan kueri, setiap baris sesuai dengan grup, yang terdiri dari waktu yang dipangkas, nama rentang, dan jenis rentang. 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_duation_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 penggabungan. Misalnya, untuk menambahkan kolom yang menghitung jumlah entri di setiap grup, lakukan hal berikut:

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

    Dengan perubahan ini, pengelompokan tetap sama. Entri dikelompokkan menurut waktu mulai yang dipangkas, nama rentang, dan jenis rentang. 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.global._Trace._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