Format JSON permintaan pembuatan konfigurasi metrik

Panduan ini menjelaskan format permintaan JSON untuk endpoint /api/v1/generate_metrics_config alat Pembuat Konfigurasi Metrik (MCG). Format ini memungkinkan Anda menentukan kampanye telemetri—dengan 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 melingkar, atau referensi yang tidak ditentukan, lalu mengompilasinya menjadi pesan buffer 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 mendesain kampanye pengumpulan metrik, ikuti alur logis berikut:

1. Tentukan sumber data: Tentukan asal data Anda.
2. Tentukan logika dan pemrosesan: Siapkan aturan untuk waktu pengumpulan data dan cara memprosesnya.
3. Buat output: Mengemas data yang diproses ke dalam pesan akhir.
4. Kolom tingkat teratas: Tambahkan kolom tingkat teratas seperti UUID, definisi sinyal, dan kontrol siklus proses.

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 channel pub/sub yang ditentukan dalam VSIDL.

• Layanan SDV (berbasis RPC): Data tersedia jika layanan mengekspos RPC CreateSubscription atau GetLatestMessage.

• Penayang berbasis Publisher Registry yang Dapat Dikonfigurasi: Data tersedia jika aplikasi mendaftarkan dirinya menggunakan IConfigurablePublisherRegistry antarmuka Binder Android atau library Publisher Registry yang Dapat Dikonfigurasi dari Telemetry SDK.

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

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

Format source_identifier

Layanan Telemetri menerima beberapa format ID sumber. Lihat Definisi sumber data dalam konfigurasi metrik untuk mengetahui 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 jenis tidak ada dalam katalog Anda, Anda juga harus memberikan definisinya di descriptor_protos.

{
  "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. Pengagregasi (konsep) menentukan cara data diproses berdasarkan pemicu tersebut. Karena ekspresi (konsep) adalah kunci untuk memicu kondisi dan logika agregasi, bagian ini pertama-tama menjelaskan cara menulisnya.

Ekspresi

Ekspresi memungkinkan Anda menentukan perhitungan dan kondisi menggunakan sintaksis yang mudah dibaca. 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 yang terakhir diterima yang di-cache oleh layanan Telemetri. (Catatan: Jika sub_sampling_interval_ms disetel, ini mungkin berbeda dengan pesan terbaru yang dipublikasikan.)
• 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).

Pemicu: Menentukan kapan tindakan terjadi

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

Pemicu data

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

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

Pemicu berkala

Diaktifkan pada interval reguler (concept).

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

Pemicu bersyarat

Dipicu berdasarkan evaluasi ekspresi (konsep). Pemicu ini memerlukan satu atau beberapa pemicu induk untuk memulai evaluasinya. Pemicu ini sering kali berupa pemicu data untuk sumber data atau pengagregasi dalam ekspresi, atau pemicu berkala untuk melakukan polling data.

Jenis kondisi

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

Opsi tepi

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.

{
  "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
        }
      }
    }
  }
}

Penggabung: Menentukan cara data diproses

Gunakan penggabung untuk pemrosesan data sementara yang memiliki status (konsep). Tentukan penggabung dan tambahkan ke array aggregators.

Agregator mengubah data dan menyediakannya untuk agregator dan laporan lainnya.

Pembuat pesan

Objek message_builder menentukan struktur pesan output dan logika agregasi yang digunakan untuk menghitung kolomnya. Sumber data ini digunakan dalam Agregator dan Konfigurasi Laporan.

{
  "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
        }
      }
    ]
  }
}

Buat 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 langsung 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 Agregator. Karena laporan biasanya merupakan snapshot tanpa status, hal ini menjaga logika kompleks dengan status dalam agregator dan mencadangkan laporan untuk pemformatan.

{
  "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 tingkat teratas

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

Setel 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 bergaris 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 (dikemas 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. Saat 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 data terjadi. Misalnya, untuk mengumpulkan data hanya saat kendaraan sedang dikemudikan, 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 dilanjutkan hanya saat pemicu mulai diaktifkan lagi.

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

• Deteksi Sekali (Selesai): Gunakan deactivate_trigger_name jika konfigurasi hanya boleh dijalankan satu kali (misalnya, untuk mendeteksi kemunculan pertama kode kesalahan tertentu), lalu dinonaktifkan 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 secara terus-menerus hingga kampanye berakhir.

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 dalam vs_version. Hal ini terjadi saat menyetel 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 semua jenis pesan 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
]

{
  "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 tingkat teratas

{
  "existing_uuid": "00000000-0000-0000-0000-000000000000", // 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 penggabung

{
  "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