Format JSON permintaan pembuatan konfigurasi metrik

Panduan ini menjelaskan format permintaan JSON untuk endpoint /api/v2/generate_metrics_config alat Metrics Configuration Generator (MCG). Format ini memungkinkan Anda menentukan kampanye telemetri—menentukan pengumpulan data, pemrosesan di perangkat, dan pembuatan laporan—dalam struktur yang dapat dibaca manusia.

Alat MCG memvalidasi objek JSON ini, memeriksa masalah seperti ketidakcocokan jenis, dependensi sirkular, atau referensi yang tidak ditentukan, lalu mengompilasinya menjadi pesan buffering protokol (protobuf) MetricsConfig. Pesan MetricsConfig ini adalah format biner yang dijalankan oleh layanan Telemetri di perangkat untuk menjalankan kampanye.

Prasyarat: Anda harus memahami skema JSON, protobuf, dan struktur data dasar. Untuk ringkasan konseptual, lihat Konsep konfigurasi metrik.

Cara menulis deskripsi konfigurasi

Untuk merancang kampanye pengumpulan metrik, ikuti alur logis berikut:

  1. Menentukan sumber data: Tentukan dari mana data Anda berasal.
  2. Menentukan logika dan pemrosesan: Siapkan aturan untuk menentukan kapan harus mengumpulkan data dan cara memprosesnya.
  3. Membuat output: Mengemas data yang diproses menjadi pesan akhir.
  4. Kolom level teratas: Tambahkan kolom level teratas seperti UUID, definisi sinyal, dan kontrol siklus proses.

Contoh: Laporan kecepatan rata-rata

Panduan ini menggunakan contoh untuk menunjukkan cara semua komponen saling melengkapi. Pipeline ini membuat laporan yang menghitung kecepatan kendaraan rata-rata setiap menit. Class ini menentukan Sumber Data (SpeedSource) untuk mengumpulkan data kecepatan, Pemicu (OnNewSpeed, EveryMinute) untuk mengontrol alur eksekusi, Agregator (SpeedAggregator) untuk menghitung rata-rata, dan Konfigurasi Laporan Metrik (MinuteReport) untuk mengemas hasilnya. Contoh di bagian yang dapat diperluas dibuat berdasarkan skenario ini.

Menentukan sumber data

Telemetri mendukung pengumpulan data dari Layanan SDV (melalui Middleware SDV) dan penayang berbasis Configurable Publisher Registry.

Untuk menggunakan data di SDV, tentukan sumber data (konsep) dan tambahkan ke array data_sources.

Kolom objek sumber data (item dalam daftar data_sources)
name String yang ditentukan pengguna yang mengidentifikasi sumber data ini dalam konfigurasi metrik.
source_identifier ID yang digunakan untuk menemukan layanan. Untuk mengetahui detailnya, lihat format source_identifier.
connection_type SUBSCRIPTION untuk aliran data berkelanjutan (diperlukan untuk pemicu data), atau ON_DEMAND untuk pengambilan on demand (untuk mengetahui detailnya, lihat konfigurasi sumber data).
opsional
configuration

Hanya RPC dan Configurable Publisher Registry. Objek untuk mengonfigurasi sumber data dengan kolom berikut:

type_url FQN pesan protobuf konfigurasi.
value_json,
value_textproto,
atau value
Payload dalam format JSON, textproto, atau base64.
Kolom untuk jenis koneksi SUBSCRIPTION
opsional
sub_sampling_interval_ms
Pub/sub saja. Bilangan bulat non-negatif (milidetik) untuk membatasi frekuensi pesan dengan menentukan interval minimum antarpesan.
opsional
fetch_last_message
(default: false)
Pub/sub saja. Boolean. Jika true, mengambil pesan terbaru setelah koneksi.

Tidak semua opsi tersedia untuk semua jenis sumber data. Lihat panduan integrasi sumber data untuk mengetahui informasi selengkapnya.

Format source_identifier

Layanan Telemetri menerima beberapa format ID sumber. Lihat Definisi sumber data dalam konfigurasi metrik untuk ringkasannya.

MCG menyimpulkan jenis pesan protobuf dari source_identifier hanya jika menggunakan format Nama Jenis Unit. Jika Anda menggunakan FQIN atau nama kustom (dari Configurable Publisher Registry), MCG tidak dapat menyimpulkan jenisnya. Dalam kasus ini, Anda harus memberikan data_source_message_types. Jika jenisnya tidak ada dalam katalog, Anda juga harus memberikan definisinya di descriptor_protos.

Contoh: Menentukan sumber data

Contoh ini melaporkan kecepatan kendaraan. Pertama, lihat katalog VSIDL untuk mengidentifikasi layanan yang memublikasikan data ini.

Dengan menggunakan katalog contoh di codebase SDV, identifikasi layanan yang relevan. Sesuai dengan Format source_identifier, tentukan jenis pesan protobuf mcg.test.subpkg.speed_msg. Karena kecepatan biasanya sering dipublikasikan, gunakan sub_sampling_interval_ms untuk membatasi pembaruan menjadi satu pesan per detik:

{
  "name": "SpeedSource",
  "source_identifier": "mcg.test.subpkg.speed_msg",
  "connection_type": "SUBSCRIPTION",
  "sub_sampling_interval_ms": 1000 // Limit updates to 1 per second
}

Menentukan logika dan pemrosesan

Logika ditangani oleh dua komponen yang bekerja sama: Pemicu (konsep) menentukan kapan sesuatu terjadi. Agregator (konsep) menentukan cara data diproses berdasarkan pemicu tersebut. Karena ekspresi (konsep) adalah kunci untuk kondisi pemicu dan logika agregasi, bagian ini akan menjelaskan cara menulisnya terlebih dahulu.

Ekspresi

Ekspresi memungkinkan Anda menentukan penghitungan dan kondisi menggunakan sintaksis yang dapat dibaca manusia. MCG mengompilasi string ini ke dalam format yang dapat dieksekusi dan dioptimalkan untuk evaluasi di perangkat.

Ekspresi dapat menyatakan penghitungan aritmetika, kondisi logis, dan perbandingan data. Untuk mengetahui sintaksis lengkap, termasuk operator dan fungsi, lihat Sintaksis ekspresi.

Keaktualan data: Saat ekspresi mengakses sumber data, perilaku pengambilan bergantung pada jenis koneksi:

  • SUBSCRIPTION: Menggunakan pesan terakhir diterima yang di-cache oleh layanan Telemetri. (Catatan: Jika sub_sampling_interval_ms ditetapkan, ini mungkin berbeda dari pesan terbaru yang dipublikasikan secara absolut.)
  • ON_DEMAND: Memicu panggilan langsung untuk mengambil pesan baru dari layanan.

Batasan jenis

  • Array: Akses indeks array langsung (misalnya, my_data_source.my_array[0]) tidak didukung.
  • Keamanan jenis: Pastikan Anda membandingkan jenis yang kompatibel (misalnya, jangan membandingkan kolom string dengan daftar bilangan bulat).

Contoh: Ekspresi

Contoh ini perlu mengekstrak nilai kecepatan untuk menghitung rata-ratanya. Sistem juga perlu menentukan apakah kendaraan melaju kencang (lebih dari 100 km/jam) untuk pemicu bersyarat. Anda dapat menemukan nama kolom (dalam hal ini speed) dalam definisi pesan protobuf yang digunakan oleh sumber data. Ekspresi berikut dapat melakukannya:

  • SpeedSource.speed: Mengambil nilai kolom speed dari sumber data SpeedSource.
  • SpeedSource.speed > 27.7: Dievaluasi menjadi true jika kecepatan lebih besar dari 27,7 m/dtk (sekitar 100 km/jam).

Pemicu: Menentukan kapan tindakan terjadi

Pemicu menentukan kapan tindakan dijalankan: mengevaluasi agregator, membuat laporan, atau mengontrol siklus proses pengumpulan. Tambahkan semua pemicu yang ditentukan ke array triggers tingkat teratas.

Kolom objek pemicu (item dalam daftar triggers)
name ID unik untuk pemicu ini dalam konfigurasi metrik.
periodic
data
conditional
Anda harus memberikan salah satu kolom ini untuk menentukan perilaku.

Pemicu data

Diaktifkan saat sumber data SUBSCRIPTION memberikan pesan baru (konsep).

Kolom objek data (dalam pemicu)
source_name name dari data_source yang diproses oleh pemicu ini.

Contoh: Pemicu data

Dalam contoh ini, perbarui penghitungan kecepatan rata-rata setiap kali SpeedSource memublikasikan pesan baru. Pemicu data ini diaktifkan setiap kali hal itu terjadi:

{
  "name": "OnNewSpeed",
  "data": {
    "source_name": "SpeedSource" // Reference to the defined data source
  }
}

Pemicu berkala

Diaktifkan pada interval reguler (konsep).

Kolom objek periodic (dalam pemicu)
period_ms Angka non-negatif yang menentukan interval dalam milidetik.

Contoh: Pemicu berkala

Contoh ini memerlukan laporan setiap menit. Pemicu berkala ini diaktifkan setiap 60.000 md untuk membuat laporan tersebut:

{
  "name": "EveryMinute",
  "periodic": {
    "period_ms": 60000 // 60,000 ms = 60 seconds
  }
}

Pemicu bersyarat

Diaktifkan berdasarkan evaluasi ekspresi (konsep). Pemicu ini memerlukan satu atau beberapa pemicu induk untuk memulai evaluasinya. Hal ini sering kali merupakan pemicu data untuk sumber data atau agregator dalam ekspresi, atau pemicu berkala untuk melakukan polling data.

Kolom objek conditional (dalam pemicu)
triggers Array dengan setidaknya satu nama pemicu induk. Saat pemicu induk diaktifkan, pemicu bersyarat akan mengevaluasi ekspresi.
expression Ekspresi yang akan dievaluasi. Lihat Ekspresi.
condition_type Menentukan kapan pemicu harus diaktifkan, berdasarkan evaluasi ekspresi.
Jenis kondisi

Kamus condition_type harus berisi tepat satu jenis kondisi yang tersedia sebagai kunci. Untuk mengetahui informasi selengkapnya, lihat Pemicu bersyarat.

Kolom objek condition_type (saling eksklusif)
is_true

is_false
Diaktifkan saat ekspresi boolean bernilai true atau false.
rising_edge

Jika numerik, diaktifkan saat nilainya meningkat. Jika ekspresi berupa boolean, akan diaktifkan saat berubah dari false menjadi true.

Dapat berisi objek rising_options (lihat Opsi tepi).

falling_edge

Jika numerik, diaktifkan saat nilainya menurun. Jika ekspresi berupa boolean, akan diaktifkan saat berubah dari true menjadi false.

Dapat berisi objek falling_options (lihat Opsi tepi).

all_changes

Diaktifkan saat hasil ekspresi berbeda dari nilai sebelumnya. Jika opsi edge ditetapkan, opsi ini hanya mendukung nilai numerik dan boolean.

Dapat berisi rising_options, falling_options, atau keduanya (lihat Opsi edge).

Opsi edge

Objek rising_options dan falling_options memiliki kolom berikut. Jika disediakan, transisi yang sesuai harus memenuhi persyaratan durasi. Transisi tanpa opsi yang ditentukan akan langsung diaktifkan.

Kolom untuk objek opsi edge
min_duration_ms Angka non-negatif (dalam milidetik) yang menentukan durasi kondisi harus dipertahankan dalam status baru sebelum pemicu diaktifkan.
opsional
require_exact
Boolean. Jika benar, semua nilai yang dipublikasikan selama durasi harus sama agar pemicu diaktifkan.

Contoh: Contoh: Pemicu bersyarat

Pemicu berikut menggunakan opsi edge. Pemberitahuan ini akan diaktifkan jika kecepatan melebihi 27,7 m/dtk dan tetap tinggi selama setidaknya 5 detik:

{
  "name": "SpeedingFor5Seconds",
  "conditional": {
    "triggers": ["OnNewSpeed"],
    "expression": "SpeedSource.speed > 27.7",
    "condition_type": {
      "rising_edge": {
        "rising_options": {
          "min_duration_ms": 5000 // Condition must hold for 5s in new state
        }
      }
    }
  }
}

Agregator: Menentukan cara data diproses

Menggunakan agregator untuk pemrosesan data stateful dan perantara (konsep). Tentukan agregator dan tambahkan ke array aggregators.

Agregator mengubah data dan menyediakannya untuk agregator dan laporan lain.

Kolom agregator (item dalam daftar aggregators)
name String yang ditentukan pengguna yang mengidentifikasi agregator ini. Ekspresi dapat mereferensikan agregator ini berdasarkan nama untuk mengakses hasilnya.
trigger_names Array yang berisi satu atau beberapa nama pemicu yang menyebabkan agregasi ini dievaluasi.
opsional
reset_on_get
Boolean, default: `false`. Jika `true`, sistem akan mereset status agregasi setelah nilainya diakses oleh agregator, laporan metrik, atau pemicu bersyarat lain.
message_builder Menentukan data yang akan dibaca, diproses, dan digabungkan. Kolom pesan output kemudian menjadi sumber data untuk agregator dan laporan lainnya. Fungsi ini menggunakan field_assignments, dengan setiap penetapan menentukan kolom dalam pesan output.

Pembuat pesan

Objek message_builder menentukan struktur pesan output dan logika agregasi yang digunakan untuk menghitung kolomnya. ID ini digunakan di Agregator dan Konfigurasi Laporan.

Kolom objek message_builder (di agregator atau laporan)
message_type Nama yang sepenuhnya memenuhi syarat dari jenis pesan protobuf untuk output. Jika dihilangkan, MCG akan membuat jenis pesan kustom berdasarkan jenis output yang disimpulkan field_assignments'. Hanya gunakan ini jika builder pesan adalah bagian dari laporan metrik dan laporan Anda harus cocok dengan definisi pesan protobuf tertentu yang telah ditentukan sebelumnya.
field_assignments Array objek definisi kolom. Setiap objek menentukan kolom dalam pesan output dan logika untuk menghitung nilainya.
Kolom objek penetapan kolom (item dalam daftar field_assignments)
field_name Nama yang ditentukan pengguna untuk kolom. Properti ini mengidentifikasi nilai tertentu dalam objek saat menggunakan notasi titik dalam ekspresi (aggregator_name.field_name).
aggregation

Objek yang menentukan cara sistem menghitung nilai kolom dengan kolom berikut:

@type Fungsi agregasi.

  • avg, min, max, sum, stddev: Statistik matematika standar.
  • count: Menghitung berapa kali agregator ini telah dipicu.
  • delta: Perbedaan antara nilai saat ini dan sebelumnya.
  • vector: Membuat daftar nilai (ring buffer).
  • none: Meneruskan nilai mentah.
expression Ekspresi input untuk agregasi. Wajib untuk semua jenis agregasi, kecuali count.
max_length Hanya untuk @type: "vector". Bilangan bulat opsional yang membatasi ukuran vektor, sehingga membuat buffering ring.

Contoh: Contoh: Agregator

Misalnya, hitung statistik antara laporan menit. Agregator ini dipicu oleh OnNewSpeed untuk menghitung kecepatan rata-rata (avg), menghitung pembacaan (count), dan menyimpan 5 nilai kecepatan terakhir (vector). Tetapkan reset_on_get ke true. Tindakan ini akan mereset statistik setiap kali MinuteReport membacanya, sehingga memulai periode pengumpulan baru untuk agregator pada menit berikutnya:

{
  "name": "SpeedAggregator",
  "trigger_names": ["OnNewSpeed"], // Update aggregation on new speed data
  "reset_on_get": true, // Reset stats after they are read by the report configuration
  "message_builder": {
    "field_assignments": [
      {
        "field_name": "average_speed",
        "aggregation": {
          "@type": "avg",
          "expression": "SpeedSource.speed"
        }
      },
      {
        "field_name": "speed_reading_count",
        "aggregation": {
          "@type": "count" // Counts triggers (that is, processed speed readings) since last reset
        }
      },
      {
        "field_name": "speed_history_last5",
        "aggregation": {
          "@type": "vector",
          "expression": "SpeedSource.speed",
          "max_length": 5 // Keep last 5 readings
        }
      }
    ]
  }
}

Membuat output

Untuk menentukan output akhir kampanye telemetri, tambahkan objek ke array report_configs (konsep). Konfigurasi ini menentukan cara data yang diproses dikemas dan kapan data tersebut dibuat. Anda dapat menentukan beberapa konfigurasi laporan dalam satu konfigurasi metrik untuk menggunakan kembali komponen.

Anda mengontrol pembuatan laporan menggunakan kolom trigger_names. Selain itu, Anda dapat menggunakan report_initial untuk segera membuat laporan saat konfigurasi diaktifkan, dan report_incomplete untuk membuat laporan akhir saat pengumpulan data terganggu.

Catatan: Untuk menghubungkan pemrosesan ke output, gunakan jenis agregasi none (@type: "none") untuk membaca nilai yang telah dihitung sebelumnya dari Aggregator. Karena laporan biasanya merupakan snapshot stateless, hal ini akan mempertahankan logika stateful yang kompleks dalam agregator dan mencadangkan laporan untuk pemformatan.

Kolom objek konfigurasi laporan (item dalam daftar report_configs)
name Nama unik untuk laporan. Nama ini akan muncul dalam metadata laporan yang dibuat.
trigger_names Array nama pemicu yang menyebabkan laporan dibuat dan dipublikasikan.
message_builder Lihat Pembuat pesan untuk mengetahui detailnya. Ini menentukan konten laporan. Agregasi hanya dievaluasi saat laporan dipicu. Misalnya, agregasi vektor menambahkan satu nilai per laporan, dan agregasi jumlah mencerminkan nomor laporan.
opsional
report_incomplete
(default: `false`)
Boolean. Jika `true`, sistem akan membuat laporan akhir saat penonaktifan atau saat pengumpulan data berakhir, meskipun data tidak ada.
opsional
report_initial
(default: `false`)
Boolean. Jika `true`, sistem akan langsung membuat laporan saat konfigurasi metrik diaktifkan.

Contoh: Konfigurasi laporan

Terakhir, tentukan konfigurasi laporan untuk contoh ini. Peristiwa ini dipicu oleh EveryMinute. Fungsi ini membaca kecepatan rata-rata yang dihitung dan jumlah pembacaan dari SpeedAggregator menggunakan agregasi none, yang meneruskan nilai yang telah diagregasi ke laporan:

{
  "name": "MinuteReport",
  "trigger_names": ["EveryMinute"], // Generate report every minute
  "message_builder": {
    "field_assignments": [
      {
        "field_name": "average_speed",
        "aggregation": {
          "@type": "none", // Read the value directly from the aggregator
          "expression": "SpeedAggregator.average_speed"
        }
      },
      {
        "field_name": "reading_count",
        "aggregation": {
          "@type": "none",
          "expression": "SpeedAggregator.speed_reading_count"
        }
      }
    ]
  }
}

Kolom level teratas

Selain array data_sources, aggregators, triggers, dan report_configs, deskripsi konfigurasi metrik memerlukan referensi ke katalog sinyal. Anda juga dapat menyertakan bidang opsional untuk menetapkan UUID tertentu dan mengelola siklus proses koleksi.

Menetapkan UUID

Setiap MetricsConfig memerlukan ID Unik Universal (UUID). Jika Anda memberikan existing_uuid, MCG akan menggunakannya. Jika tidak, ID acak akan dibuat. Untuk konsistensi di seluruh deployment dan alat, tentukan existing_uuid.

String harus berupa UUID bertanda hubung yang valid dan hanya berisi huruf kecil.

"existing_uuid": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",

Definisi sinyal

Untuk memvalidasi nama dan jenis sinyal, MCG memerlukan akses ke Katalog Sinyal Kendaraan. Ini adalah protobuf FileDescriptorSet yang berisi definisi VSIDL .proto Anda (dipaketkan dan diupload ke MCG). Untuk mengetahui detail tentang cara membuat dan mengupload katalog, lihat Katalog Sinyal Kendaraan.

Tentukan versi katalog di kolom vs_version objek JSON:

"vs_version": "v1.0",

Menentukan pemicu siklus proses

Dalam konteks kampanye telemetri, siklus proses MetricsConfig menentukan kapan data benar-benar direkam. Meskipun sistem pengelolaan kampanye men-deploy dan mengaktifkan konfigurasi di perangkat, Anda dapat menggunakan pemicu siklus proses untuk mengontrol secara tepat kapan data dikumpulkan dalam deployment tersebut.

Hal ini memungkinkan Anda menyelaraskan pengumpulan data dengan pola penggunaan kendaraan, seperti "Perjalanan" (IgnitionOn hingga IgnitionOff) atau "Sesi Pengisian Daya", tanpa perlu menonaktifkan konfigurasi.

  • Kontrol Sesi (Mulai/Jeda): Gunakan start_trigger_name dan stop_trigger_name untuk mengontrol kapan pengumpulan terjadi. Misalnya, untuk mengumpulkan data hanya saat kendaraan sedang berjalan, gunakan IgnitionOn sebagai pemicu mulai dan IgnitionOff sebagai pemicu berhenti. Konfigurasi tetap aktif di perangkat, tetapi secara efektif "dijeda" (berhenti mengumpulkan dan memproses) saat pemicu berhenti diaktifkan, dan hanya dilanjutkan saat pemicu mulai diaktifkan lagi.

    Penting: Tindakan ini hanya menjeda pengumpulan. Fungsi ini tidak menentukan jendela logis, set data terpisah, atau memiliki efek samping lainnya. Nilai agregator tidak direset saat pengumpulan dijeda atau dilanjutkan.

  • Deteksi Sekali Saja (Selesai): Gunakan deactivate_trigger_name jika konfigurasi hanya boleh berjalan sekali (misalnya, untuk mendeteksi kemunculan pertama kode error tertentu) dan kemudian menonaktifkan dirinya sendiri secara permanen di perangkat tersebut, meskipun kampanye secara teknis masih aktif.

Jika Anda tidak menentukan pemicu siklus proses, pengumpulan data akan segera dimulai saat konfigurasi diaktifkan oleh kampanye dan berlanjut terus-menerus hingga kampanye berakhir.

Kolom siklus proses level teratas (objek root)
opsional
start_trigger_name
Nama pemicu yang memulai sesi pengumpulan. Dapat ditetapkan tanpa stop_trigger_name.
opsional
stop_trigger_name
Nama pemicu yang menjeda sesi pengumpulan (misalnya, saat kendaraan tidak bergerak). Jika ditetapkan, start_trigger_name juga harus ditetapkan.
opsional
deactivate_trigger_name
Nama pemicu yang menyelesaikan dan menonaktifkan `MetricsConfig` sepenuhnya.

Lanjutan: Definisi proto kustom

Dalam dua kasus utama, vs_version saja tidak cukup bagi MCG untuk memahami semua jenis pesan dalam deskripsi konfigurasi metrik:

  1. Kegagalan inferensi jenis: Seperti yang dijelaskan dalam format source_identifier, MCG tidak dapat menyimpulkan jenis saat source_identifier menggunakan FQIN atau nama kustom.
  2. Pesan kustom: Deskripsi konfigurasi metrik menggunakan pesan protobuf yang tidak ditemukan dalam katalog VSIDL yang ditentukan di vs_version. Hal ini terjadi saat menetapkan message_type di message_builder untuk format laporan kustom.

Dalam kasus ini, gunakan data_source_message_types untuk membantu MCG menyimpulkan jenis dan descriptor_protos untuk memberikan definisi pesan.

data_source_message_types

Petakan string source_identifier ke jenis pesan protobuf yang sepenuhnya memenuhi syarat. Kunci di data_source_message_types harus cocok dengan nilai source_identifier dari entri data_sources:

"data_source_message_types": {
  "MyCustomSpeedService": "com.sdv.example.SampleMessage"
}

descriptor_protos

Berikan definisi untuk jenis pesan apa pun yang digunakan dalam data_source_message_types atau message_builder yang tidak ada dalam vs_version yang dikonfigurasi.

Teruskan descriptorpb.FileDescriptorSet berenkode base64 dalam array descriptor_protos. Buat ini dari file .proto menggunakan compiler Protobuf protoc.

"descriptor_protos": [
  "Cu8BCiZtY2cvdGVzdGRhdGEvbWF4YXZnY3..." // Base64 string
]

Contoh: Deskripsi konfigurasi lengkap

Bagian sebelumnya menentukan semua komponen untuk contoh: membuat laporan setiap menit dengan kecepatan kendaraan rata-rata yang diamati selama menit tersebut.

Komponennya adalah:

  • Sumber data (SpeedSource) untuk mendapatkan data kecepatan hingga sekali per detik.
  • Pemicu data (OnNewSpeed) yang diaktifkan saat SpeedSource mengirim data.
  • Pemicu berkala (EveryMinute) yang diaktifkan setiap 60 detik.
  • Agregator (SpeedAggregator) yang menggunakan OnNewSpeed untuk menghitung kecepatan rata-rata, menghitung pembacaan, dan menyimpan nilai terbaru, yang direset saat dibaca.
  • Konfigurasi laporan (MinuteReport) yang menggunakan EveryMinute untuk memicu laporan yang berisi kecepatan rata-rata dan jumlah dari SpeedAggregator.
  • Kolom tingkat teratas (existing_uuid, vs_version) untuk mengidentifikasi konfigurasi metrik dan menentukan katalog VSIDL yang akan digunakan untuk definisi sinyal.

Jika digabungkan, bagian-bagian ini akan membentuk deskripsi lengkap konfigurasi metrik:

{
  "existing_uuid": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", // Unique identifier for the configuration
  "vs_version": "example_version", // Version of the VSIDL catalog to use
  "data_sources": [
    {
      "name": "SpeedSource",
      "source_identifier": "mcg.test.subpkg.speed_msg",
      "connection_type": "SUBSCRIPTION",
      "sub_sampling_interval_ms": 1000
    }
  ],
  "aggregators": [
    {
      "name": "SpeedAggregator",
      "trigger_names": ["OnNewSpeed"],
      "reset_on_get": true,
      "message_builder": {
        "field_assignments": [
          {
            "field_name": "average_speed",
            "aggregation": {
              "@type": "avg",
              "expression": "SpeedSource.speed"
            }
          },
          {
            "field_name": "speed_reading_count",
            "aggregation": { "@type": "count" }
          },
          {
            "field_name": "speed_history_last5",
            "aggregation": {
              "@type": "vector",
              "expression": "SpeedSource.speed",
              "max_length": 5
            }
          }
        ]
      }
    }
  ],
  "triggers": [
    {
      "name": "OnNewSpeed",
      "data": { "source_name": "SpeedSource" }
    },
    {
      "name": "EveryMinute",
      "periodic": { "period_ms": 60000 }
    }
  ],
  "report_configs": [
    {
      "name": "MinuteReport",
      "trigger_names": ["EveryMinute"],
      "message_builder": {
        "field_assignments": [
          {
            "field_name": "average_speed",
            "aggregation": {
              "@type": "none",
              "expression": "SpeedAggregator.average_speed"
            }
          },
          {
            "field_name": "reading_count",
            "aggregation": {
              "@type": "none",
              "expression": "SpeedAggregator.speed_reading_count"
            }
          }
        ]
      }
    }
  ]
}

Template referensi

Untuk definisi API, lihat referensi API MCG.

Bagian berikut memberikan referensi lengkap deskripsi konfigurasi metrik. Gunakan sebagai panduan untuk membuat deskripsi konfigurasi metrik Anda sendiri.

Kolom level teratas

{
  "existing_uuid": "1cbec8e6-46f5-4649-9fa2-09f81bc93f8b", // Optional
  "vs_version": "example_version", // Optional
  "descriptor_protos": ["..."], // Optional. Base64 encoded FileDescriptorSet
  "data_source_message_types": {
    "ExampleServiceName": "com.example.ProtoMessage"
  }, // Optional
  "start_trigger_name": "DataTriggerExample", // Optional
  "stop_trigger_name": "ConditionalTriggerExample", // Optional
  "deactivate_trigger_name": "PeriodicTriggerExample" // Optional
}

Input: sumber data dan agregator

{
  "data_sources": [
    {
      "name": "SubscriptionExample",
      "source_identifier": "com.example.sdv.ExampleMessage|example-unit",
      "connection_type": "SUBSCRIPTION", // Options: SUBSCRIPTION (default), ON_DEMAND
      "sub_sampling_interval_ms": 100, // Optional
      "fetch_last_message": false // Optional. Default: false
    },
    {
      "name": "RegistryExample",
      // Configurable Publisher Registry-based publisher (matches data_source_message_types)
      "source_identifier": "ExampleServiceName",
      "connection_type": "SUBSCRIPTION"
    },
    {
      "name": "GetterExample",
      "source_identifier": "com.example.sdv.ExampleConfig|example-unit",
      "connection_type": "ON_DEMAND",
      "configuration": {
        "type_url": "type.googleapis.com/example.Config",
        "value_json": {} // Or value_textproto, value (base64)
      }
    }
  ],
  "aggregators": [
    {
      "name": "AggregatorExample",
      "trigger_names": ["DataTriggerExample"],
      "reset_on_get": false, // Optional. Default: false. If true, resets state after it's read
      "message_builder": {
        "message_type": ".com.example.AggregatedMessage", // Optional
        "field_assignments": [
          {
            "field_name": "avg_example",
            "aggregation": {
              // Options: avg, count, min, max, sum, stddev, delta, vector, none
              "@type": "avg",
              "expression": "SubscriptionExample.value"
            }
          },
          {
            "field_name": "count_example",
            "aggregation": {
              "@type": "count" // Counts number of evaluations. No expression needed
            }
          },
          {
            "field_name": "vector_example",
            "aggregation": {
              "@type": "vector",
              "expression": "SubscriptionExample.value",
              "max_length": 10 // Optional. If set, creates a ring buffer
            }
          }
        ]
      }
    }
  ]
}

Logika dan pemrosesan: pemicu

{
  "triggers": [
    {
      "name": "PeriodicTriggerExample",
      "periodic": { "period_ms": 1000 }
    },
    {
      "name": "DataTriggerExample",
      "data": { "source_name": "SubscriptionExample" }
    },
    {
      "name": "ConditionalTriggerExample",
      "conditional": {
        "triggers": ["PeriodicTriggerExample"],
        "expression": "SubscriptionExample.value > 0",
        "condition_type": {
          // Options: is_true, is_false, rising_edge, falling_edge, all_changes
          "rising_edge": {
            "rising_options": { "min_duration_ms": 0, "require_exact": false }
          }
        }
      }
    }
  ]
}

Output: konfigurasi laporan

{
  "report_configs": [
    {
      "name": "ReportExample",
      "trigger_names": ["PeriodicTriggerExample"],
      "report_incomplete": false, // Optional. Default: false
      "report_initial": false, // Optional. Default: false
      "message_builder": {
        "message_type": ".com.example.ReportMessage", // Optional. Must be defined in VSIDL catalog or descriptor_protos. Message type will be inferred if not provided
        "field_assignments": [
          {
            "field_name": "avg_example",
            "aggregation": {
              "@type": "none", // Passthrough since aggregation is done in AggregatorExample
              "expression": "AggregatorExample.avg_example"
            }
          }
        ]
      }
    }
  ]
}

Sintaksis ekspresi

Kategori Sintaksis Deskripsi
Akses data source_name
source_name.field
source_name.field.subfield
Mengakses pesan lengkap dari sumber data atau agregator
Mengakses kolom tertentu dalam pesan (termasuk kolom bertingkat)
Aritmetika +, -, *, /, %, ** Matematika standar. ** adalah eksponensial.
Logika &&, ||, !, ^ AND, OR, NOT, XOR.
Relasional ==, !=, <, <=, >, >= == dan != berfungsi pada semua jenis. Lainnya memerlukan angka.
Daftar contains(list, item)
doesnotcontain(list, item)
alleq(list, value)
Beroperasi pada vektor (array). alleq(list, value) menampilkan true jika semua item dalam list sama dengan value.
Fungsi timestamp(clock_type) Waktu saat ini dalam mikrodetik.
clock_type: REALTIME_CLOCK atau
MONOTONIC_TIME_SINCE_BOOT_OR_RESUME
abs(n) Nilai absolut
floor(n), round(n), ceil(n) Fungsi pembulatan
Urutan operasi () Pengelompokan standar untuk prioritas