Contoh kueri SQL untuk Trace

Pratinjau

Produk atau fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum di Persyaratan Khusus Layanan. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Dokumen ini berisi contoh kueri yang khusus untuk membuat kueri data trace yang disimpan di project Anda Google Cloud .

Dukungan bahasa SQL

Kueri yang digunakan di halaman Log Analytics mendukung fungsi GoogleSQL dengan beberapa pengecualian.

Perintah SQL berikut tidak didukung untuk kueri SQL yang dikeluarkan menggunakan halaman Log Analytics:

• Perintah DDL dan DML
• Fungsi yang ditentukan pengguna (UDF) Javascript
• Fungsi BigQuery ML
• Variabel SQL

Berikut hanya didukung saat Anda membuat kueri set data tertaut menggunakan halaman BigQuery Studio dan Looker Studio, atau menggunakan alat command line bq:

• Fungsi yang ditentukan pengguna (UDF) Javascript
• Fungsi BigQuery ML
• Variabel SQL

Praktik terbaik

Untuk menetapkan rentang waktu kueri, sebaiknya gunakan pemilih rentang waktu. Misalnya, untuk melihat data selama seminggu terakhir, pilih 7 hari terakhir dari pemilih rentang waktu. Anda juga dapat menggunakan pemilih rentang waktu untuk menentukan waktu mulai dan berakhir, menentukan waktu untuk dilihat, dan mengubah zona waktu.

Jika Anda menyertakan kolom start_time dalam klausa WHERE, setelan pemilih rentang waktu tidak akan digunakan. Contoh berikut memfilter data menggunakan fungsi TIMESTAMP_SUB, yang memungkinkan Anda menentukan interval lihat kembali dari waktu saat ini:

WHERE
  start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

Untuk mengetahui informasi selengkapnya tentang cara memfilter menurut waktu, lihat Fungsi waktu dan Fungsi stempel waktu.

Sebelum memulai

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.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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 Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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 Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. Untuk mendapatkan izin yang diperlukan untuk memuat halaman Log Analytics, menulis, menjalankan, dan menyimpan kueri pribadi pada data trace, 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 Analisis Observabilitas (roles/observability.analyticsUser) di project Anda. Peran ini berisi izin yang diperlukan untuk menyimpan dan menjalankan kueri pribadi, serta menjalankan kueri bersama.
   • Logs Viewer (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.

Cara menggunakan kueri di halaman ini

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

   Buka Log Analytics

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

2. Di panel Query, klik  SQL, lalu salin dan tempel kueri ke panel kueri SQL.

   Berikut menunjukkan format klausa FROM untuk membuat kueri tampilan _AllSpans:

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

   Klausa FROM berisi kolom berikut:

   • PROJECT_ID: ID project.
   • LOCATION: Lokasi bucket observabilitas.
   • _Trace adalah nama bucket observabilitas
   • Spans adalah nama set data.
   • _AllSpans adalah nama tampilan.
   Catatan: Pemisah untuk jalur adalah karakter titik, (.). Jika elemen jalur seperti the Google Cloud project berisi karakter titik, maka pastikan setiap kolom jalur diapit oleh tanda kutip terbalik tunggal, (`).

Untuk menggunakan kueri yang ditampilkan dalam dokumen ini di halaman BigQuery Studio atau menggunakan alat command line bq, lalu edit klausa FROM dan masukkan jalur ke set data tertaut. Misalnya, untuk membuat kueri tampilan _AllSpans pada set data tertaut bernama my_linked_dataset yang ada di project myproject, jalurnya adalah `myproject.my_linked_dataset._AllSpans`.

Kasus penggunaan umum

Bagian ini mencantumkan beberapa kasus penggunaan umum, yang mungkin membantu Anda membuat kueri kustom.

Menampilkan semua data trace

Untuk membuat kueri tampilan _AllSpans, jalankan kueri berikut:

-- Display all data.
SELECT *
FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
-- Limit to 10 entries.
LIMIT 10

Menampilkan informasi rentang umum

Untuk menampilkan informasi rentang umum, seperti waktu mulai dan durasi, jalankan kueri berikut:

SELECT
  start_time,
  -- Set the value of service name based on the first non-null value in the list.
  COALESCE(
    JSON_VALUE(resource.attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,
  name AS span_name,
  duration_nano,
  status.code AS status,
  trace_id,
  span_id
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
LIMIT 10

Untuk mempelajari lebih lanjut, lihat Ekspresi kondisional.

Menampilkan persentil ke-50 dan ke-99 latensi rentang

Untuk menampilkan persentil ke-50 dan ke-99 latensi untuk setiap layanan rpc, jalankan kueri berikut:

SELECT
  -- Compute 50th and 99th percentiles for each service
  STRING(attributes['rpc.service']) || '/' || STRING(attributes['rpc.method']) AS rpc_service_method,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(50)] AS duration_nano_p50,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(99)] AS duration_nano_p99
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE
  -- Matches spans whose kind field has a value of 2 (SPAN_KIND_SERVER).
  kind = 2
GROUP BY rpc_service_method

Untuk mengetahui informasi selengkapnya tentang enumerasi, lihat dokumentasi OpenTelemetry: SpanKind.

Untuk melihat hasil secara grafis, Anda dapat membuat diagram dengan dimensi yang ditetapkan ke rpc_service_method. Anda dapat menambahkan dua ukuran, satu untuk rata-rata nilai duration_nano_p50, dan yang lainnya untuk rata-rata kolom duration_nano_p99.

Memfilter entri trace

Untuk menerapkan filter ke kueri, tambahkan klausa WHERE. Sintaksis yang Anda gunakan dalam klausa ini bergantung pada jenis data kolom. Bagian ini memberikan beberapa contoh untuk berbagai jenis data.

Memfilter menurut jenis data string

Kolom name disimpan sebagai String.

• Untuk menganalisis hanya rentang yang kolom name-nya ditentukan, gunakan klausa berikut:

  -- Matches spans that have a name field.
  WHERE name IS NOT NULL
  

• Untuk menganalisis hanya rentang yang kolom name-nya memiliki nilai "POST", gunakan klausa berikut:

  -- Matches spans whose name is POST.
  WHERE STRPOS(name, "POST") > 0
  

• Untuk menganalisis hanya rentang yang kolom name-nya berisi nilai "POST", gunakan operator LIKE beserta karakter pengganti:

  -- Matches spans whose name contains POST.
  WHERE name LIKE "%POST%"
  

Memfilter menurut jenis data bilangan bulat

Kolom kind adalah bilangan bulat, yang dapat mengambil nilai antara nol dan lima:

• Untuk menganalisis hanya rentang yang kolom kind-nya ditentukan, gunakan klausa berikut:

  -- Matches spans that have field named kind.
  WHERE kind IS NOT NULL
  

• Untuk menganalisis rentang yang nilai kind-nya adalah satu atau dua, gunakan klausa berikut:

  -- Matches spans whose kind value is 1 or 2.
  WHERE kind IN (1, 2)
  

Memfilter menurut jenis data RECORD

Beberapa kolom dalam skema trace memiliki jenis data RECORD. Kolom ini dapat menyimpan satu atau beberapa struktur data, atau menyimpan entri berulang dari struktur data yang sama.

Memfilter menurut status atau kode status

Kolom status adalah contoh kolom yang jenis datanya adalah RECORD. Kolom ini menyimpan satu struktur data, dengan anggota yang diberi label code dan message.

• Untuk hanya menganalisis rentang saat kolom status.code memiliki nilai 1, tambahkan klausa berikut:

  -- Matches spans that have a status.code field that has a value of 1.
  WHERE status.code = 1
  

  Kolom status.code disimpan sebagai bilangan bulat.

• Untuk menganalisis rentang yang kolom status-nya bukan EMPTY, tambahkan klausa berikut:

  -- Matches spans that have status field. When the status field exists, it
  -- must contain a subfield named code.
  -- Don't compare status to NULL, because this field has a data type of RECORD.
  WHERE status.code IS NOT NULL
  

Memfilter menurut peristiwa atau link

Kolom events dan links disimpan dengan jenis data RECORD, tetapi kolom ini adalah kolom berulang.

• Untuk mencocokkan rentang yang memiliki setidaknya satu peristiwa, gunakan klausa berikut:

  -- Matches spans that have at least one event. Don't compare events to NULL.
  -- The events field has data type of RECORD and contains a repeated fields.
  WHERE ARRAY_LENGTH(events) > 0
  

• Untuk mencocokkan rentang yang memiliki peristiwa yang kolom name-nya memiliki nilai message, gunakan klausa berikut:

  WHERE
    -- Exists is true when any event in the array has a name field with the
    -- value of message.
    EXISTS(
      SELECT 1
      FROM UNNEST(events) AS ev
      WHERE ev.name = 'message'
    )
  

Memfilter menurut jenis data JSON

Kolom attributes berjenis JSON. Setiap atribut individual adalah pasangan nilai kunci.

• Untuk menganalisis hanya rentang yang kolom attributes-nya ditentukan, gunakan klausa berikut:

  -- Matches spans where at least one attribute is specified.
  WHERE attributes IS NOT NULL
  

• Untuk menganalisis hanya rentang yang kunci atribut bernama component memiliki nilai "proxy", gunakan klausa berikut:

  -- Matches spans that have an attribute named component with a value of proxy.
  WHERE attributes IS NOT NULL
        AND JSON_VALUE(attributes, '$.component') = 'proxy'
  

  Anda juga dapat menggunakan pernyataan LIKE beserta karakter pengganti untuk melakukan pengujian berisi:

  -- Matches spans that have an attribute named component whose value contains proxy.
  WHERE attributes IS NOT NULL
        AND JSON_VALUE(attributes, '$.component') LIKE '%proxy%'
  

Mengelompokkan dan menggabungkan data trace

Bagian ini mengilustrasikan cara mengelompokkan dan menggabungkan rentang. Jika Anda tidak menentukan pengelompokan, tetapi menentukan gabungan, satu hasil akan dicetak karena SQL memperlakukan semua entri yang memenuhi klausa WHERE sebagai satu grup.

Setiap ekspresi SELECT harus disertakan dalam kolom grup atau digabungkan.

Mengelompokkan rentang menurut waktu mulai

Untuk mengelompokkan data menurut waktu mulai, gunakan fungsi TIMESTAMP_TRUNC, yang memangkas stempel waktu ke granularitas yang ditentukan seperti HOUR:

SELECT
  -- Truncate the start time to the hour. Count the number of spans per group.
  TIMESTAMP_TRUNC(start_time, HOUR) AS hour,
  status.code AS code,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE
  -- Matches spans shows start time is within the previous 12 hours.
  start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 12 HOUR)
GROUP BY
  -- Group by hour and status code.
  hour, code
ORDER BY hour DESC

Untuk mengetahui informasi selengkapnya, lihat TIMESTAMP_TRUNC dokumentasi dan Fungsi tanggal dan waktu.

Catatan: Jika Anda menyertakan kolom start_time dalam klausa WHERE, setelan pemilih rentang waktu tidak akan digunakan.

Menghitung rentang menurut kode status

Untuk menampilkan jumlah rentang dengan kode status tertentu, jalankan kueri berikut:

SELECT
  -- Count the number of spans for each status code.
  status.code,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE status.code IS NOT NULL
GROUP BY status.code

Jika Anda mengganti status.code dengan kind, kueri sebelumnya akan melaporkan jumlah rentang untuk setiap nilai enumerasi kind. Demikian pula, jika Anda mengganti status.code dengan name, hasil kueri akan mencantumkan jumlah entri untuk setiap nama rentang.

Menghitung durasi rata-rata semua rentang

Untuk menampilkan durasi rata-rata, setelah mengelompokkan data rentang menurut nama rentang, jalankan kueri berikut:

SELECT
  -- Group by name, and then compute the average duration for each group.
  name,
  AVG(duration_nano) AS nanosecs,
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
GROUP BY name
ORDER BY nanosecs DESC

Menghitung durasi rata-rata dan persentil per nama layanan

Kueri berikut menghitung jumlah rentang dan berbagai statistik untuk setiap layanan:

SELECT
  -- Set the service name by the first non-null value.
  COALESCE(
    JSON_VALUE(resource.attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,

  -- Count the number spans for each service name. Also compute statistics.
  COUNT(*) AS span_count,
  AVG(duration_nano) AS avg_duration_nano,
  MIN(duration_nano) AS min_duration_nano,
  MAX(duration_nano) AS max_duration_nano,

  -- Calculate percentiles for duration
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(50)] AS p50_duration_nano,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(95)] AS p95_duration_nano,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(99)] AS p99_duration_nano,

  -- Count the number of unique trace IDs. Also, collect up to 5 unique
  -- span names and status codes.
  COUNT(DISTINCT trace_id) AS distinct_trace_count,
  ARRAY_AGG(DISTINCT name IGNORE NULLS LIMIT 5) AS sample_span_names,
  ARRAY_AGG(DISTINCT status.code IGNORE NULLS LIMIT 5) AS sample_status_codes
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
GROUP BY service_name
ORDER BY span_count DESC

Penelusuran lintas kolom

Bagian ini menjelaskan dua pendekatan yang dapat Anda gunakan untuk menelusuri beberapa kolom tampilan yang Anda kueri:

• Penelusuran berbasis token: Anda menentukan lokasi penelusuran, kueri penelusuran, lalu menggunakan fungsi SEARCH. Karena fungsi SEARCH memiliki aturan khusus tentang cara data ditelusuri, sebaiknya baca dokumentasi SEARCH.

• Penelusuran berbasis substring: Anda memberikan lokasi penelusuran, literal string, lalu menggunakan fungsi CONTAINS_SUBSTR. Sistem melakukan pengujian yang tidak peka huruf besar/kecil untuk menentukan apakah literal string ada dalam ekspresi. Fungsi CONTAINS_SUBSTR menampilkan TRUE jika literal string ada dan FALSE jika tidak. Nilai penelusuran harus berupa literal STRING, tetapi bukan literal NULL.

Mengkueri beberapa tampilan

Pernyataan kueri memindai satu atau beberapa tabel atau ekspresi dan menampilkan baris hasil yang dihitung. Misalnya, Anda dapat menggunakan pernyataan kueri untuk menggabungkan hasil pernyataan SELECT pada tabel atau set data yang berbeda dengan berbagai cara, lalu memilih kolom dari data gabungan.

Untuk menggabungkan tampilan, batasan berikut berlaku:

1. Lokasi tampilan memenuhi salah satu hal berikut:

   • Semua tampilan memiliki lokasi yang sama.
   • Semua tampilan berada di lokasi global atau us.

2. Saat resource penyimpanan menggunakan kunci enkripsi yang dikelola pelanggan (CMEK), salah satu hal berikut harus benar:

   • Resource penyimpanan yang menggunakan CMEK menggunakan kunci Cloud KMS yang sama.
   • Resource penyimpanan yang menggunakan CMEK memiliki ancestor umum, dan ancestor tersebut menentukan kunci Cloud KMS default Cloud KMS yang berada di lokasi yang sama dengan resource penyimpanan.

   Jika satu atau beberapa resource penyimpanan menggunakan CMEK, sistem akan mengenkripsi data sementara yang dihasilkan oleh gabungan dengan kunci Cloud KMS umum atau kunci Cloud KMS default ancestor.

Misalnya, Anda memiliki dua tampilan yang berada di lokasi yang sama. Kemudian, Anda dapat menggabungkan tampilan ini jika salah satu hal berikut berlaku:

• Resource penyimpanan tidak menggunakan CMEK.
• Satu resource penyimpanan menggunakan CMEK dan yang lainnya tidak.
• Kedua resource penyimpanan menggunakan CMEK dan keduanya menggunakan kunci Cloud KMS yang sama.

• Kedua resource penyimpanan menggunakan CMEK, tetapi menggunakan kunci yang berbeda. Namun, resource tersebut berbagi an ancestor yang menentukan kunci Cloud KMS default yang berada di lokasi yang sama dengan the resource penyimpanan.

  Misalnya, hierarki resource untuk bucket log dan bucket observabilitas mencakup organisasi yang sama. Anda dapat menggabungkan tampilan di bucket tersebut jika, untuk organisasi tersebut, Anda telah mengonfigurasi setelan resource default untuk Cloud Logging dan untuk bucket observabilitas dengan kunci Cloud KMS default yang sama untuk lokasi penyimpanan.

Menggabungkan data trace dan log menggunakan ID trace

Kueri berikut menggabungkan data log dan trace menggunakan ID rentang dan trace:

SELECT
  T.trace_id,
  T.span_id,
  T.name,
  T.start_time,
  T.duration_nano,
  L.log_name,
  L.severity,
  L.json_payload
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans` AS T
JOIN
  `PROJECT_ID.LOCATION._Default._AllLogs` AS L
ON
  -- Join log and trace data by both the span ID and trace ID.
  -- Don't join only on span ID, this field isn't globally unique.
  T.span_id = L.span_id
  -- A regular expression is required because the storage format of the trace ID
  -- differs between a log view and a trace view.
  AND T.trace_id = REGEXP_EXTRACT(L.trace, r'/([^/]+)$')
WHERE T.duration_nano > 1000000
LIMIT 10

Respons kueri mencantumkan ID trace dan rentang, yang memungkinkan Anda membuat kueri secara individual untuk mengumpulkan informasi selengkapnya. Selain itu, hasil mencantumkan tingkat keparahan entri log dan payload JSON.

Langkah berikutnya

• Menyimpan dan membagikan kueri SQL.
• Membuat diagram hasil kueri SQL.
• Mengkueri set data tertaut di BigQuery.

Untuk dokumentasi referensi SQL atau contoh lainnya, lihat dokumen berikut:

• Fungsi, operator, dan kondisional.
• Fungsi penelusuran.
• Sintaksis kueri.
• Contoh kueri SQL untuk Cloud Logging.