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:
- Menentukan sumber data: Tentukan dari mana data Anda berasal.
- Menentukan logika dan pemrosesan: Siapkan aturan untuk menentukan kapan harus mengumpulkan data dan cara memprosesnya.
- Membuat output: Mengemas data yang diproses menjadi pesan akhir.
- 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.
Layanan SDV (berbasis pub/sub): Data tersedia dari saluran pub/sub yang ditentukan di VSIDL.
Layanan SDV (berbasis RPC): Data tersedia jika layanan mengekspos RPC
CreateSubscriptionatauGetLatestMessage.Penayang berbasis Configurable Publisher Registry: Data tersedia jika aplikasi mendaftarkan dirinya menggunakan antarmuka Android Binder
IConfigurablePublisherRegistryatau library Configurable Publisher Registry dari Telemetry SDK.
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). |
||||
opsionalconfiguration |
Hanya RPC dan Configurable Publisher Registry. Objek untuk mengonfigurasi sumber data dengan kolom berikut:
|
||||
Kolom untuk jenis koneksi SUBSCRIPTION |
|||||
opsionalsub_sampling_interval_ms |
Pub/sub saja. Bilangan bulat non-negatif (milidetik) untuk membatasi frekuensi pesan dengan menentukan interval minimum antarpesan. | ||||
opsionalfetch_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: Jikasub_sampling_interval_msditetapkan, 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 kolomspeeddari sumber dataSpeedSource.SpeedSource.speed > 27.7: Dievaluasi menjaditruejika 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. |
periodicdataconditional |
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_trueis_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 Dapat berisi objek |
falling_edge |
Jika numerik, diaktifkan saat nilainya menurun. Jika ekspresi berupa boolean, akan diaktifkan saat berubah dari Dapat berisi objek |
all_changes |
Diaktifkan saat hasil ekspresi berbeda dari nilai sebelumnya. Jika opsi edge ditetapkan, opsi ini hanya mendukung nilai numerik dan boolean. Dapat berisi |
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. |
opsionalrequire_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. |
opsionalreset_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:
|
||||||
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. |
opsionalreport_incomplete(default: `false`) |
Boolean. Jika `true`, sistem akan membuat laporan akhir saat penonaktifan atau saat pengumpulan data berakhir, meskipun data tidak ada. |
opsionalreport_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_namedanstop_trigger_nameuntuk mengontrol kapan pengumpulan terjadi. Misalnya, untuk mengumpulkan data hanya saat kendaraan sedang berjalan, gunakanIgnitionOnsebagai pemicu mulai danIgnitionOffsebagai 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_namejika 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) | |
|---|---|
opsionalstart_trigger_name |
Nama pemicu yang memulai sesi pengumpulan. Dapat ditetapkan tanpa stop_trigger_name. |
opsionalstop_trigger_name |
Nama pemicu yang menjeda sesi pengumpulan (misalnya, saat kendaraan tidak bergerak). Jika ditetapkan,
start_trigger_name juga harus ditetapkan. |
opsionaldeactivate_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:
- Kegagalan inferensi jenis: Seperti yang dijelaskan dalam format
source_identifier, MCG tidak dapat menyimpulkan jenis saatsource_identifiermenggunakan FQIN atau nama kustom. - Pesan kustom: Deskripsi konfigurasi metrik menggunakan pesan protobuf yang tidak ditemukan dalam katalog VSIDL yang ditentukan di
vs_version. Hal ini terjadi saat menetapkanmessage_typedimessage_builderuntuk 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 saatSpeedSourcemengirim data. - Pemicu berkala (
EveryMinute) yang diaktifkan setiap 60 detik. - Agregator (
SpeedAggregator) yang menggunakanOnNewSpeeduntuk menghitung kecepatan rata-rata, menghitung pembacaan, dan menyimpan nilai terbaru, yang direset saat dibaca. - Konfigurasi laporan (
MinuteReport) yang menggunakanEveryMinuteuntuk memicu laporan yang berisi kecepatan rata-rata dan jumlah dariSpeedAggregator. - 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_namesource_name.fieldsource_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 atauMONOTONIC_TIME_SINCE_BOOT_OR_RESUME |
abs(n) |
Nilai absolut | |
floor(n), round(n), ceil(n) |
Fungsi pembulatan | |
| Urutan operasi | () |
Pengelompokan standar untuk prioritas |