Referensi API library klien telemetri Rust

Halaman ini menjelaskan jenis, metode, dan penanganan error di library libsdv_telemetry_rust_wrapper.

Antarmuka TelemetryServiceHolder

Antarmuka utama untuk klien adalah struktur TelemetryServiceHolder. Antarmuka ini menyediakan serangkaian lengkap metode untuk mengelola koneksi layanan, konfigurasi metrik, dan laporan data.

Pengelolaan siklus proses layanan

Metode ini membuat dan menghentikan koneksi dengan layanan Telemetri yang mendasarinya.

get

pub fn get() -> TelemetryResult<TelemetryServiceHolder>

Metode statis yang mengambil handle yang aman untuk thread ke layanan Telemetry. Ini adalah panggilan pemblokiran yang menunggu hingga layanan binder telemetri siap. Layanan Telemetry hanya mendukung satu instance TelemetryServiceHolder. Memanggil metode ini lebih dari sekali akan menyebabkan perilaku yang tidak terdefinisi atau tidak terduga.

TelemetryServiceHolder mengimplementasikan trait Send dan Sync, yang berarti dapat dibagikan dengan aman di seluruh thread, misalnya, dengan membungkusnya dalam instance Arc. Sebagian besar metode TelemetryServiceHolder bersifat async dan dapat digunakan secara bersamaan.

init

pub async fn init(
    &self,
    misc_status_callback: impl Fn(TelemetryServiceStatus) + Send + Sync + 'static,
    report_ready_callback: impl Fn(ReportInfo) + Send + Sync + 'static,
) -> TelemetryResult<()>

Menginisialisasi layanan dengan mendaftarkan callback asinkron. Panggil metode ini sekali setelah mendapatkan TelemetryServiceHolder dan sebelum interaksi lainnya.

selesai

pub fn finish(&self) -> TelemetryResult<()>

Menutup koneksi layanan dengan benar, menghapus pemroses yang terdaftar, dan membersihkan resource terkait. Panggil metode ini sekali saat aplikasi dihentikan.

Pengelolaan konfigurasi metrik

Metode asinkron ini mengelola definisi dan status konfigurasi pengumpulan data.

Layanan Telemetri mempertahankan konfigurasi dalam dua status:

• Tidak aktif: Konfigurasi divalidasi dan disimpan di disk, tetapi tidak digunakan untuk pengumpulan data.
• Aktif: Konfigurasi mengumpulkan data, dan komponennya (pemicu, penayang, misalnya) aktif.

Untuk memastikan konfigurasi tetap ada saat layanan dimulai ulang dan perangkat di-reboot, layanan menyimpannya di disk perangkat. Layanan menyimpan semua konfigurasi dalam dua direktori berbasis status, memvalidasi dan, jika perlu, mengaktifkannya saat booting.

add_metrics_config

pub async fn add_metrics_config(&self, serialized_config: &[u8]) -> TelemetryResult<String>

Menambahkan konfigurasi metrik baru ke layanan. Konfigurasi harus diberikan sebagai array byte yang diserialisasi. Konfigurasi yang ditambahkan tidak aktif secara default.

activate_metrics_config

pub async fn activate_metrics_config(&self, config_uuid: &str) -> TelemetryResult<String>

Mengaktifkan konfigurasi metrik yang sebelumnya ditambahkan (atau dinonaktifkan), memulai pengumpulan dan pelaporan datanya.

deactivate_metrics_config

pub async fn deactivate_metrics_config(&self, config_uuid: &str) -> TelemetryResult<String>

Menghentikan pengumpulan dan pelaporan data untuk konfigurasi metrik yang aktif. Konfigurasi tetap ada di layanan dan dapat diaktifkan kembali nanti.

remove_metrics_config

pub async fn remove_metrics_config(&self, config_uuid: &str) -> TelemetryResult<String>

Menghapus konfigurasi metrik secara permanen. Jika konfigurasi aktif, layanan akan menonaktifkannya terlebih dahulu.

remove_all_metrics_configs

pub async fn remove_all_metrics_configs(&self) -> TelemetryResult<String>

Menghapus semua konfigurasi metrik yang ada, menonaktifkan konfigurasi yang aktif.

get_active_metrics_config_uuids

pub async fn get_active_metrics_config_uuids(&self) -> TelemetryResult<Vec<String>>

Mengirimkan kueri ke layanan untuk mendapatkan daftar UUID semua konfigurasi dalam status aktif.

get_inactive_metrics_config_uuids

pub async fn get_inactive_metrics_config_uuids(&self) -> TelemetryResult<Vec<String>>

Mengirim kueri ke layanan untuk mendapatkan daftar UUID semua konfigurasi dalam status tidak aktif.

Penanganan dan pengambilan laporan metrik

Dengan metode ini, Anda dapat membuat kueri untuk laporan yang tersedia dan mengambil data laporan yang dikumpulkan.

get_metrics_report

pub async fn get_metrics_report(&self, report_uuid: &str) -> TelemetryResult<MetricsReport>

Mengambil data laporan metrik lengkap untuk UUID laporan tertentu. Anda dapat memperoleh UUID laporan dari notifikasi menggunakan report_ready_callback atau dengan memanggil get_ready_reports_info.

get_ready_reports_info

pub async fn get_ready_reports_info(&self) -> TelemetryResult<Vec<ReportInfo>>

Mengirimkan kueri ke layanan Telemetri untuk mendapatkan daftar semua laporan yang telah selesai dan siap diambil. Hal ini berguna untuk memeriksa status laporan jika notifikasi panggilan balik terlewat (misalnya, jika report_ready_callback didaftarkan terlambat).

Jenis inti, callback, dan penanganan error

libsdv_telemetry_rust_wrapper menggunakan serangkaian jenis kustom untuk berinteraksi dengan layanan Telemetri, mengelola callback asinkron, dan menangani error layanan.

Jenis respons dan error API

Jenis ini ditampilkan langsung oleh metode library untuk menunjukkan keberhasilan atau kegagalan langsung dari operasi yang diminta.

TelemetryResult

Sebagian besar metode menampilkan TelemetryResult<T>, yang merupakan alias untuk jenis Result standar, yang dikhususkan untuk error tingkat layanan:

pub type TelemetryResult<T> = Result<T, TelemetryError>;

TelemetryError

Struktur TelemetryError merangkum semua kegagalan dan memberikan informasi error spesifik per layanan yang mendetail:

TelemetryServiceStatusCodes

Enumerasi numerik yang merepresentasikan hasil panggilan API dan status layanan internal. Kode ini digunakan di TelemetryError dan TelemetryServiceStatus. Contoh:

Jenis callback asinkron

Pemroses yang terdaftar (misc_status_callback dan report_ready_callback) meneruskan jenis ini ke klien untuk memberikan update pada proses latar belakang.

TelemetryServiceStatus

Struktur TelemetryServiceStatus berfungsi sebagai argumen untuk penutupan misc_status_callback dari init, yang didaftarkan selama inisialisasi layanan. Struktur ini memberikan update asinkron tentang kesehatan dan masalah runtime layanan, misalnya, terputusnya koneksi dari sumber data.

StatusDetails

Enum ini membungkus konteks error tertentu. Jika details ada di TelemetryServiceStatus, itu adalah salah satu varian berikut:

Setiap varian enum berisi kolom tambahan yang memberikan lebih banyak konteks.

ReportInfo

Struktur ReportInfo berfungsi sebagai argumen untuk penutupan report_ready_callback init, yang didaftarkan selama inisialisasi layanan. Struktur ini berisi ID yang menjelaskan laporan metrik:

Kolom report_uuid adalah satu-satunya yang diperlukan untuk pengambilan laporan metrik lebih lanjut (lihat get_metrics_report), sementara config_uuid hanya berfungsi sebagai informasi tambahan tentang sumbernya.