Tentang laporan

Untuk mengambil data biaya dan penggunaan dengan App Optimize API, Anda harus membuat laporan terlebih dahulu. Resource ini berfungsi sebagai definisi persisten untuk data yang ingin Anda analisis, dengan menentukan parameter seperti cakupan, dimensi, rentang waktu, dan filter.

Setelah Anda membuat laporan, API akan menghasilkan data yang diminta secara asinkron. Kemudian, Anda menggunakan nama resource laporan untuk mengambil set data yang dihasilkan.

Oleh karena itu, alur kerjanya adalah:

  1. Anda membuat laporan yang menentukan kriteria Anda.
  2. Sistem memproses permintaan ini secara asinkron.
  3. Setelah operasi selesai, Anda membaca data yang dihasilkan.

Dokumen ini menjelaskan struktur dan parameter yang dapat dikonfigurasi dari laporan App Optimize API, termasuk dimensi, metrik, dan opsi pemfilteran yang tersedia, serta menjelaskan format data yang ditampilkan.

Untuk mengetahui informasi tentang batasan biaya dan pemanfaatan, lihat Memahami data.

Menentukan laporan

Untuk membuat laporan, Anda menentukan resource Report dengan parameter konfigurasi berikut, yang dijelaskan di subbagian berikutnya:

Parameter Jenis Deskripsi
scopes Array Project atau aplikasi App Hub yang akan dianalisis. Anda harus memberikan tepat satu elemen cakupan.
dimensions Array Atribut untuk mengambil dan mengelompokkan data, termasuk pengelompokan berbasis waktu.
metrics Array Pengukuran spesifik yang akan ditampilkan.
filter String Ekspresi Common Expression Language (CEL) untuk mempersempit data, termasuk rentang waktu.

Cakupan

Kolom scopes menentukan kumpulan resource yang akan dianalisis oleh App Optimize API. Meskipun kolom ini adalah array, Anda harus menentukan tepat satu elemen, yang dapat berupa project atau aplikasi App Hub:

  • project: string yang merepresentasikan Google Cloud project. Formatnya harus seperti:

    projects/PROJECT_ID

    Ganti PROJECT_ID dengan ID project Google Cloud Anda. Misalnya, projects/my-project-1.

  • application: string yang merepresentasikan nama resource lengkap aplikasi App Hub. Formatnya harus:

    projects/PROJECT_ID/locations/LOCATION/applications/APPLICATION_ID

    Ganti kode berikut:

    • PROJECT_ID: ID project host App Hub.
    • LOCATION: region aplikasi App Hub, seperti us-central1.
    • APPLICATION_ID: ID aplikasi App Hub.

    Misalnya, projects/my-host-proj/locations/us-central1/applications/my-app.

Berikut adalah contoh array scopes dalam JSON untuk permintaan pembuatan laporan, yang menampilkan satu elemen cakupan:

  • Mencakup berdasarkan project:

    "scopes": [
  {
    "project": "projects/my-project-1"
  }
]

  • Mencakup menurut aplikasi:

    "scopes": [
  {
    "application": "projects/my-host-proj/locations/us-central1/applications/my-app"
  }
]

Dimensi

Dimensi menentukan data yang ditampilkan dan cara pengelompokan data. Misalnya, jika Anda memilih project dan product_display_name, output akan berisi satu baris untuk setiap kombinasi unik dari nilai project dan nama produk yang ditemukan dalam data.

Berikut adalah tabel dimensi yang didukung:

Dimensi Jenis Deskripsi Nilai contoh
project STRING Google Cloud Project ID. projects/my-project
application STRING Aplikasi App Hub. projects/my-project/locations/us-central1/applications/my-app
service_or_workload STRING Layanan atau beban kerja App Hub. projects/my-project/locations/us-central1/applications/my-app/services/my-service
resource STRING Nama lengkap resource. //compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/vm-1
resource_type STRING Jenis resource API. compute.googleapis.com/Instance
location STRING Region Google Cloud atau multi-region. us-east1
sku STRING ID SKU penagihan. 4496-8C0D-228F
product_display_name STRING Nama Google Cloud produk. Compute Engine
month STRING Tahun dan bulan. 2024-01
day STRING Tahun, bulan, dan hari. 2024-01-10
hour STRING Tahun, bulan, hari, dan jam. 2024-01-10T00

Dimensi location merepresentasikan Google Cloud region atau multi-region yang menjadi tujuan biaya dan penggunaan. Cara lokasi ini dilaporkan bergantung pada setelan lokasi resource dalam cakupan laporan:

  • Untuk resource yang di-deploy di zona tertentu, seperti us-central1-a, biaya dan penggunaan digabungkan dan diatribusikan ke region induk. Dalam contoh ini, dimensi location akan menampilkan us-central1.
  • Untuk resource yang di-deploy di region, seperti us-central1, dimensi location mencerminkan region tertentu tersebut.
  • Untuk resource yang di-deploy atau dikonfigurasi untuk multi-region, seperti us, dimensi location mencerminkan multi-region tersebut.

Dimensi waktu

Untuk menggabungkan hasil menurut waktu, sertakan setidaknya satu dimensi waktu, seperti month, day, atau hour, dalam daftar dimensions. Perhatikan bahwa:

  • Semua dimensi waktu menggunakan Waktu Pasifik dan memperhitungkan Waktu Musim Panas (DST).
  • Format mengikuti ISO 8601.
  • Jika rentang waktu dalam filter tidak sepenuhnya sesuai dengan perincian dimensi waktu yang dipilih, rentang akan diperluas untuk mencakup periode penuh. Misalnya, memfilter sebagian hari dengan dimension: ["month"] akan menyertakan data untuk seluruh bulan.

Metrik

Metrik adalah nilai kuantitatif yang ingin Anda ukur untuk setiap grup yang ditentukan oleh dimensi Anda. Metrik yang didukung adalah:

Metrik Jenis Deskripsi
cost RECORD Biaya moneter dalam mata uang yang diminta.
cpu_mean_utilization FLOAT64 Penggunaan CPU rata-rata (0,0 hingga 1,0).
cpu_p95_utilization FLOAT64 Penggunaan CPU persentil ke-95 (0,0 hingga 1,0).
cpu_usage_core_seconds INT64 Total pekerjaan CPU yang dilakukan.
cpu_allocation_core_seconds INT64 Total kapasitas CPU yang disediakan.
memory_mean_utilization FLOAT64 Penggunaan memori rata-rata (0,0 hingga 1,0).
memory_p95_utilization FLOAT64 Penggunaan memori persentil ke-95 (0,0 hingga 1,0).
memory_usage_byte_seconds INT64 Total memori yang digunakan dari waktu ke waktu.
memory_allocation_byte_seconds INT64 Total memori yang disediakan dari waktu ke waktu.

Kombinasi yang valid

Tidak semua dimensi dapat digabungkan dengan setiap metrik di App Optimize API. Tabel berikut menunjukkan contoh set dimensi yang valid dan metrik yang dapat Anda gunakan dengannya. API akan menampilkan error jika kombinasi yang tidak valid diminta; lihat error tersebut untuk mengetahui kombinasi yang valid.

Dimensi Mendukung metrik cost Mendukung metrik cpu_mean_utilization
application, product_display_name
application
location, product_display_name, project, resource, resource_type, sku
location, product_display_name, project, resource, resource_type
location, product_display_name, project, service_or_workload
location, product_display_name, project, sku
product_display_name, project
product_display_name, resource_type
product_display_name, resource
product_display_name
project

Filter

Gunakan kolom filter untuk mempersempit data menggunakan string CEL. Anda dapat membuat ekspresi filter menggunakan kolom apa pun yang tercantum dalam tabel Dimensi.

Pemfilteran harus sesuai dengan batasan berikut:

  • Semua predikat kolom string harus menggunakan kecocokan string persis. Misalnya, location == 'us-east1'.
  • Beberapa predikat yang merujuk ke kolom string yang sama harus digabungkan menggunakan operator OR logis, ||. Contoh, location == 'us-east1' || location == 'us-west1'.
  • Semua predikat lainnya harus digabungkan menggunakan operator logis AND, &&.
  • Predikat pada dimensi waktu, seperti day, yang menentukan waktu mulai harus menggunakan perbandingan lebih besar dari atau sama dengan, >=.
  • Predikat pada dimensi waktu yang menentukan waktu berakhir harus menggunakan perbandingan kurang dari, <.

Rentang waktu

Jika filter tidak menyertakan dimensi waktu (month, day, hour), laporan secara default akan menampilkan rentang tujuh hari yang berakhir pada tengah malam Waktu Pasifik sebelumnya, dengan mempertimbangkan DST. Rentang tanggal maksimum adalah 90 hari sebelum tanggal saat ini, dan waktu mulai harus berada dalam jangka waktu 90 hari.

Misalnya, jika Waktu Pasifik saat ini adalah 2026-01-05T12:00:00, rentang defaultnya adalah 2025-12-29T00:00:00 hingga 2026-01-05T00:00:00 Waktu Pasifik. Waktu mulai paling awal untuk rentang waktu adalah 2025-10-07T00:00:00.

Metrik Cloud Run hanya tersedia selama enam minggu sebelum tanggal saat ini.

Contoh filter

Berikut beberapa contoh cara menyusun string filter CEL:

  • Untuk memfilter data laporan menurut jenis resource tertentu, gunakan operator == pada dimensi resource_type:

    resource_type == 'compute.googleapis.com/Instance'

  • Untuk menyertakan hanya data dari satu lokasi, filter pada dimensi location 

    location == 'us-east1'

  • Untuk menyertakan data dari daftar lokasi tertentu, gunakan operator || untuk menggabungkan kondisi pada dimensi location:

    location == 'us-east1' || location == 'us-west1'

  • Untuk mendapatkan data dalam rentang waktu tertentu menggunakan perincian per jam, Anda dapat memfilter dimensi hour. Contoh ini mencakup data dari awal 2024-01-01 hingga, tetapi tidak termasuk, 2024-02-01:

    hour >= timestamp('2024-01-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')

  • Untuk memfilter hari penuh, gunakan dimensi day. Perhatikan bahwa batas hari ditafsirkan dalam Waktu Pasifik, jadi menentukan offset adalah praktik terbaik. Contoh ini mencakup semua data untuk 15-03-2024 dan 16-03-2024:

    day >= timestamp('2024-03-15T00:00:00-07:00') && day < timestamp('2024-03-17T00:00:00-07:00')

  • Demikian pula, Anda dapat memfilter menurut bulan kalender menggunakan dimensi month, dengan tetap memperhatikan Waktu Pasifik untuk batas yang tepat. Contoh ini mencakup semua data untuk Oktober dan November 2025:

    month >= timestamp('2025-10-01T00:00:00-07:00') && month < timestamp('2025-12-01T00:00:00-08:00')

  • Untuk mendapatkan data dari 72 jam terakhir, gunakan fungsi now() dan duration() pada dimensi hour:

    hour >= now() - duration('72h')

  • Untuk mendapatkan data dari tujuh hari terakhir, Anda dapat menggunakan duration() dengan dimensi hour:

    hour >= now() - duration('168h')

  • Memfilter untuk bulan kalender tertentu, seperti bulan sebelumnya, memerlukan penghitungan stempel waktu awal dan akhir dalam kode aplikasi Anda. Kemudian, masukkan stempel waktu yang dihitung tersebut ke dalam ekspresi CEL. Secara konseptual, tampilannya mungkin seperti ini, memfilter dimensi day:

    day >= timestamp('START_OF_LAST_MONTH') && day < timestamp('START_OF_THIS_MONTH')

    Ganti kode berikut:

    • START_OF_LAST_MONTH: string stempel waktu ISO 8601 yang merepresentasikan awal bulan sebelumnya di zona waktu Pasifik, seperti 2025-12-01T00:00:00-08:00.
    • START_OF_THIS_MONTH: string stempel waktu ISO 8601 yang merepresentasikan awal bulan saat ini di zona waktu Pasifik, seperti 2026-01-01T00:00:00-08:00.

    Anda perlu menghitung string stempel waktu yang tepat ini dalam kode aplikasi, dengan mempertimbangkan tanggal saat ini, zona waktu (Waktu Pasifik), dan transisi Waktu Musim Panas.

  • Anda dapat menggabungkan filter string dan waktu menggunakan operator &&. Contoh ini memfilter dua lokasi dalam periode dua bulan tertentu:

    (location == 'us-east1' || location == 'us-west1') && hour >= timestamp('2023-12-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')

  • Berikut contoh yang lebih kompleks yang menggabungkan resource_type, project, dan rentang waktu berbasis day:

    resource_type == 'compute.googleapis.com/Instance' && project == 'projects/my-project' && day >= timestamp('2025-01-01T00:00:00-08:00') && day < timestamp('2025-02-01T00:00:00-08:00')

Struktur data laporan

Jika Anda berhasil membaca laporan, layanan akan menampilkan data sebagai columns dan rows.

Kolom

Array columns menjelaskan skema data, dalam urutan setiap kolom muncul di rows. Setiap objek dalam array columns memiliki name, type, dan terkadang columns bertingkat jika jenisnya adalah RECORD.

  • Dimensi yang Anda minta muncul sebagai kolom dengan jenis STRING.
  • Metrik yang Anda minta muncul sebagai kolom dengan jenis seperti INT64, FLOAT64, atau RECORD untuk jenis kompleks seperti cost.

Misalnya, dengan REST API, jika Anda meminta dimensions: ["application", "product_display_name"] dan metrics: ["cost", "cpu_mean_utilization"], maka App Optimize API sebagai respons akan menghasilkan array columns seperti ini:

"columns": [
  {
    "name": "application",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "product_display_name",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "cost",
    "type": "RECORD",
    "mode": "NULLABLE",
    "columns": [
      {
        "name": "currency_code",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "units",
        "type": "INT64",
        "mode": "NULLABLE"
      },
      {
        "name": "nanos",
        "type": "INT64",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "cpu_mean_utilization",
    "type": "FLOAT64",
    "mode": "NULLABLE"
  }
]

Baris

Kolom rows berisi data aktual. Setiap baris adalah array nilai yang mewakili satu catatan. Urutan nilai dalam setiap array dalam berkorespondensi langsung dengan urutan kolom yang ditentukan dalam array columns.

Melanjutkan contoh saat application, product_display_name, cost, dan cpu_mean_utilization diminta dari REST API, satu baris dalam array rows yang dihasilkan mungkin terlihat seperti ini:

"rows": [
  [
    "//apphub.googleapis.com/projects/my-proj/locations/us-central1/applications/my-app",
    "Compute Engine",
    {
      "currency_code": "USD",
      "units": "12",
      "nanos": 750000000
    },
    0.65
  ],
  [
    "//apphub.googleapis.com/projects/my-proj/locations/us-east1/applications/another-app",
    "Cloud Storage",
    {
      "currency_code": "USD",
      "units": "5",
      "nanos": 200000000
    },
    0.15
  ]
]

Tabel berikut memvisualisasikan cara nilai dalam array baris tunggal dipetakan ke skema yang ditentukan dalam array columns, menggunakan indeks nilai dalam array baris:

Indeks dalam baris Kolom terkait Jenis Nilai contoh
0 application STRING "//apphub.googleapis.com/.../applications/my-app"
1 product_display_name STRING "Cloud Storage"
2 cost RECORD { "currency_code": "USD", "units": "10", ... }
3 cpu_mean_utilization FLOAT64 0.65

Setiap elemen dalam daftar rows adalah array yang urutan nilainya cocok dengan urutan definisi kolom dalam array columns. Dengan demikian, nilai pada indeks n dalam array baris tertentu sesuai dengan kolom yang ditentukan pada indeks n dalam array columns.

Menafsirkan metrik biaya

Jika laporan menyertakan metrik cost, nilai akan ditampilkan sebagai RECORD yang berisi kolom berikut, berdasarkan jenis google.type.Money standar:

Kolom Jenis Deskripsi
currency_code STRING Kode mata uang ISO 4217 tiga huruf, seperti "USD".
units INT64 Seluruh unit jumlahnya.
nanos INT64 Unit nano (10-9) dari jumlah. Harus antara -999.999.999 dan +999.999.999 inklusif.

Untuk mendapatkan nilai uang penuh, Anda menggabungkan kolom units dan nanos. Kolom nanos mewakili bagian pecahan dari nilai mata uang. Contoh:

  • Jika currency_code adalah "USD", units adalah 106, dan nanos adalah 321590000: Nilainya adalah 106 + (321.590.000 / 1.000.000.000) = 106,32159 USD.

  • Jika currency_code adalah "EUR", units adalah 5, dan nanos adalah 750000000: Nilainya adalah 5 + (750.000.000 / 1.000.000.000) = 5,75 EUR.

Biasanya, Anda akan menggunakan library pemformatan mata uang standar untuk menampilkan nilai ini dalam format yang mudah digunakan, termasuk simbol mata uang yang sesuai.

Untuk mengetahui informasi selengkapnya tentang data yang ditampilkan oleh API dan untuk memahami batasannya, lihat Memahami data.

Masa berlaku laporan

Setiap laporan akan otomatis dihapus dari layanan App Optimize API 24 jam setelah laporan dibuat. Setelah waktu ini, laporan dan datanya tidak dapat diambil melalui API. Untuk memeriksa waktu habis masa berlaku terjadwal laporan, dapatkan metadata-nya dan lihat kolom expireTime.

Langkah berikutnya