Melacak pesan perangkat-ke-cloud Azure IoT dengan menggunakan pelacakan terdistribusi (pratinjau)

  • Artikel

Gunakan pelacakan terdistribusi (pratinjau) di IoT Hub untuk memantau pesan IoT saat melewati layanan Azure. IoT Hub adalah salah satu layanan Azure pertama yang mendukung pelacakan terdistribusi. Karena lebih banyak layanan Azure mendukung pelacakan terdistribusi, Anda dapat melacak pesan Internet of Things (IoT) di seluruh layanan Azure yang terlibat dalam solusi Anda. Untuk informasi selengkapnya tentang fitur ini, lihat Apa itu pelacakan terdistribusi?.

Saat mengaktifkan pelacakan terdistribusi untuk IoT Hub, Anda dapat:

  • Pantau alur setiap pesan melalui IoT Hub dengan menggunakan konteks pelacakan. Konteks pelacakan mencakup ID korelasi yang memungkinkan Anda menghubungkan peristiwa dari satu komponen dengan peristiwa dari komponen lain. Anda dapat menerapkannya untuk subset atau semua pesan perangkat IoT dengan menggunakan perangkat kembar.
  • Catat konteks pelacakan ke Log Azure Monitor.
  • Mengukur dan memahami alur pesan dan latensi dari perangkat ke IoT Hub dan perutean titik akhir.

Penting

Pelacakan terdistribusi Azure IoT Hub saat ini dalam PRATINJAU. Lihat Ketentuan Penggunaan Tambahan untuk Pratinjau Microsoft Azure untuk persyaratan hukum yang berlaku pada fitur Azure dalam versi beta, pratinjau, atau belum dirilis secara umum.

Prasyarat

  • Hub Azure IoT dibuat di salah satu wilayah berikut.

    • Eropa Utara
    • Asia Tenggara
    • US Barat 2

  • Perangkat yang terdaftar ke hub IoT Anda. Jika Anda tidak memilikinya, ikuti langkah-langkah dalam Mendaftarkan perangkat baru di hub IoT dan simpan perangkat string koneksi untuk digunakan dalam artikel ini.

  • Artikel ini mengasumsikan bahwa Anda mengetahui cara mengirim pesan telemetri ke hub IoT Anda.

  • Versi terbaru Git.

Batas dan pertimbangan pratinjau publik

Pertimbangkan batasan berikut untuk menentukan apakah fitur pratinjau ini tepat untuk skenario Anda:

  • Proposal untuk standar Konteks Jejak W3C saat ini adalah draf yang berfungsi.

  • Satu-satunya bahasa pengembangan yang saat ini didukung SDK klien adalah C, di cabang pratinjau publik SDK perangkat Azure IoT untuk C

  • Kemampuan kembar cloud-ke-perangkat tidak tersedia untuk tingkat dasar IoT Hub. Namun, IoT Hub masih mencatat ke Azure Monitor jika melihat header konteks pelacakan yang dibuat dengan benar.

  • Untuk memastikan operasi yang efisien, IoT Hub memberlakukan pembatasan pada tingkat pengelogan yang dapat terjadi sebagai bagian dari pelacakan terdistribusi.

  • Fitur pelacakan terdistribusi hanya didukung untuk hub IoT yang dibuat di wilayah berikut:

    • Eropa Utara
    • Asia Tenggara
    • US Barat 2

Memahami pelacakan terdistribusi Azure IoT

Banyak solusi IoT, termasuk arsitektur referensi Azure IoT, umumnya mengikuti varian arsitektur layanan mikro. Seiring solusi IoT semakin bertumbuh lebih kompleks, Anda akhirnya menggunakan puluhan layanan mikro atau lebih. Layanan mikro ini mungkin berasal dari Azure atau tidak.

Menentukan di mana pesan IoT menurun atau melambat bisa menjadi tantangan. Misalnya, bayangkan Anda memiliki solusi IoT yang menggunakan lima layanan Azure yang berbeda dan 1.500 perangkat aktif. Setiap perangkat mengirim 10 pesan perangkat ke cloud per detik, dengan total 15.000 pesan per detik. Tetapi Anda melihat bahwa aplikasi web Anda hanya melihat 10.000 pesan per detik. Bagaimana Anda menemukan pelakunya?

Agar Anda dapat membangun kembali alur pesan IoT di seluruh layanan, setiap layanan harus menyebarluaskan ID korelasi yang mengidentifikasi pesan secara unik. Setelah Azure Monitor mengumpulkan ID korelasi dalam sistem terpusat, Anda dapat menggunakan ID tersebut untuk melihat alur pesan. Metode ini disebut pola pelacakan terdistribusi.

Guna mendukung adopsi yang lebih luas untuk pelacakan terdistribusi, Microsoft berkontribusi pada proposal standar W3C untuk pelacakan terdistribusi. Saat dukungan pelacakan terdistribusi untuk IoT Hub diaktifkan, ia mengikuti alur ini untuk setiap pesan yang dihasilkan:

  1. Pesan dihasilkan pada perangkat IoT.
  2. Perangkat IoT memutuskan (dengan bantuan dari cloud) bahwa pesan ini harus ditetapkan dengan konteks pelacakan.
  3. SDK menambahkan tracestate nilai ke properti pesan, yang berisi stempel waktu untuk pembuatan pesan.
  4. Perangkat IoT mengirim pesan ke IoT Hub.
  5. Pesan tiba di gateway IoT Hub.
  6. IoT Hub mencari tracestate nilai dalam properti pesan dan memeriksa apakah nilai tersebut dalam format yang benar. Jika demikian, IoT Hub menghasilkan nilai unik trace-id global untuk pesan dan span-id nilai untuk "hop." IoT Hub mencatat nilai-nilai ini di log pelacakan terdistribusi IoT Hub di DiagnosticIoTHubD2C bawah operasi.
  7. Ketika pemrosesan pesan selesai, IoT Hub menghasilkan nilai lain span-id dan mencatatnya, bersama dengan nilai yang ada trace-id , di DiagnosticIoTHubIngress bawah operasi.
  8. Jika perutean diaktifkan untuk pesan, IoT Hub menulisnya ke titik akhir kustom. IoT Hub mencatat nilai lain span-id dengan nilai yang sama trace-id di DiagnosticIoTHubEgress bawah kategori .

Mengonfigurasi pelacakan terdistribusi di hub IoT

Di bagian ini, Anda mengonfigurasi hub IoT untuk mencatat atribut pelacakan terdistribusi (ID korelasi dan stempel waktu).

  1. Buka hub IoT Anda di portal Azure.

  2. Di panel kiri untuk hub IoT Anda, gulir ke bawah ke bagian Pemantauan dan pilih Pengaturan diagnostik.

  3. Pilih Menambahkan pengaturan diagnostik.

  4. Dalam kotak Nama pengaturan diagnostik, masukkan nama untuk pengaturan diagnostik baru. Misalnya, masukkan DistributedTracing Pengaturan.

    Cuplikan layar yang memperlihatkan tempat menambahkan nama untuk pengaturan diagnostik Anda.

  5. Pilih satu atau beberapa opsi berikut ini di bawah Detail tujuan untuk menentukan tempat mengirim informasi pengelogan:

    • Mengarsipkan ke akun penyimpanan: Mengonfigurasi akun penyimpanan untuk memuat informasi pengelogan.
    • Melakukan streaming ke hub peristiwa: Mengonfigurasi hub peristiwa agar berisi informasi pengelogan.
    • Kirim ke Analitik Log: Konfigurasikan ruang kerja Analitik Log untuk berisi informasi pengelogan.

  6. Di bagian Log , pilih operasi yang ingin Anda catat.

    Sertakan Pelacakan Terdistribusi dan konfigurasikan periode Retensi selama berapa hari Anda ingin pengelogan dipertahankan. Retensi log memengaruhi biaya penyimpanan.

    Cuplikan layar yang menunjukkan di mana operasi Pelacakan Terdistribusi adalah untuk pengaturan diagnostik IoT Hub.

  7. Pilih Simpan.

  8. (Opsional) Untuk melihat alur pesan ke tempat yang berbeda, siapkan aturan perutean ke setidaknya dua titik akhir yang berbeda.

Setelah pengelogan diaktifkan, IoT Hub merekam log saat pesan yang berisi properti pelacakan yang valid ditemui dalam salah satu situasi berikut:

  • Pesan tiba di gateway hub IoT.
  • Hub IoT memproses pesan.
  • Pesan dirutekan ke titik akhir kustom. Perutean harus diaktifkan.

Untuk mempelajari lebih lanjut tentang log ini dan skemanya, lihat Monitor IoT Hub dan Pelacakan terdistribusi di log sumber daya IoT Hub.

Memperbarui opsi pengambilan sampel

Untuk mengubah persentase pesan yang akan dilacak dari cloud, Anda harus memperbarui perangkat kembar. Anda dapat membuat pembaruan dengan menggunakan editor JSON di portal Azure atau SDK layanan IoT Hub. Subbagian berikut ini memberikan contoh.

Memperbarui satu perangkat

Anda dapat menggunakan ekstensi portal Azure atau Azure IoT Hub untuk Visual Studio Code (VS Code) untuk memperbarui laju pengambilan sampel satu perangkat.

  1. Buka hub IoT Anda di portal Azure, lalu pilih Perangkat dari bagian Manajemen perangkat di menu.

  2. Pilih perangkat Anda.

  3. Pilih ikon gerigi di bawah Pelacakan Terdistribusi (pratinjau). Di panel yang terbuka:

    1. Pilih opsi Aktifkan.
    2. Untuk Laju pengambilan sampel, pilih persentase antara 0 dan 100.
    3. Pilih Simpan.

    Cuplikan layar yang memperlihatkan cara mengaktifkan pelacakan terdistribusi di portal Azure.

  4. Tunggu beberapa detik, lalu pilih Refresh. Jika perangkat berhasil mengakui perubahan Anda, ikon sinkronisasi dengan tanda centang akan muncul.

Memperbarui beberapa perangkat secara massal

Untuk memperbarui konfigurasi pengambilan sampel pelacakan terdistribusi untuk beberapa perangkat, gunakan konfigurasi perangkat otomatis. Ikuti skema kembar ini:

{
    "properties": {
        "desired": {
            "azureiot*com^dtracing^1": {
                "sampling_mode": 1,
                "sampling_rate": 100
            }
        }
    }
}
Nama elemen Wajib Tipe Deskripsi
sampling_mode Ya Bilangan bulat Dua nilai mode saat ini didukung untuk mengaktifkan dan menonaktifkan pengambilan sampel. 1 sedang aktif, dan 2 tidak aktif.
sampling_rate Ya Bilangan bulat Nilai ini berupa persentase. Hanya nilai dari 0 ke 100 (inklusif) yang diizinkan.

Mengkueri dan memvisualisasikan jejak

Untuk melihat semua jejak yang dicatat oleh hub IoT, kueri penyimpanan log yang Anda pilih di pengaturan diagnostik. Bagian ini memperlihatkan cara mengkueri dengan menggunakan Analitik Log.

Jika Anda menyiapkan Analitik Log dengan log sumber daya, kueri dengan mencari log dalam DistributedTracing kategori. Misalnya, kueri ini memperlihatkan semua jejak yang dicatat:

// All distributed traces 
AzureDiagnostics 
| where Category == "DistributedTracing" 
| project TimeGenerated, Category, OperationName, Level, CorrelationId, DurationMs, properties_s 
| order by TimeGenerated asc

Berikut adalah beberapa contoh log di Analitik Log:

Waktu yang dihasilkan Nama operasi Kategori Tingkat ID Korelasi Durasi dalam milidetik Properti
2018-02-22T03:28:28.633Z DiagnosticIoTHubD2C DistributedTracing Informasi 00-8cd869a412459a25f5b4f31311223344-0144d2590aacd909-01 {"deviceId":"AZ3166","messageSize":"96","callerLocalTimeUtc":"2018-02-22T03:27:28.633Z","calleeLocalTimeUtc":"2018-02-22T03:27:28.687Z"}
2018-02-22T03:28:38.633Z DiagnosticIoTHubIngress DistributedTracing Informasi 00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01 20 {"isRoutingEnabled":"false","parentSpanId":"0144d2590aacd909"}
2018-02-22T03:28:48.633Z DiagnosticIoTHubEgress DistributedTracing Informasi 00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01 23 {"endpointType":"EventHub","endpointName":"myEventHub", "parentSpanId":"0144d2590aacd909"}

Untuk memahami jenis log, lihat Log pelacakan terdistribusi Azure IoT Hub.

Jalankan aplikasi contoh

Di bagian ini, Anda akan menyiapkan lingkungan pengembangan yang digunakan untuk membuat SDK C Azure IoT. Kemudian, Anda memodifikasi salah satu sampel untuk mengaktifkan pelacakan terdistribusi pada pesan telemetri perangkat Anda.

Instruksi ini adalah untuk membangun sampel pada Windows. Untuk lingkungan lainnya, lihat Mengompilasi SDK C atau SDK C yang dikemas sebelumnya untuk Pengembangan Khusus Platform.

Mengkloning kode sumber dan menginisialisasi

  1. Instal pengembangan Desktop dengan beban kerja C++ untuk Visual Studio 2022. Visual Studio 2019 juga didukung.

  2. Pasang CMake. Pastikan bahwa itu ada di Anda PATH dengan memasukkan cmake -version dari prompt perintah.

  3. Buka perintah atau shell Git Bash. Jalankan perintah berikut untuk mengkloning rilis terbaru cabang pratinjau publik repositori GitHub Azure IoT C SDK :

    git clone -b public-preview https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init

    Harapkan operasi ini memakan waktu beberapa menit untuk diselesaikan.

  4. Jalankan perintah berikut dari azure-iot-sdk-c direktori untuk membuat cmake subdirektori dan masuk ke cmake folder:

    mkdir cmake
cd cmake
cmake ..

    Jika CMake tidak dapat menemukan pengkompilasi C++, Anda mungkin mengalami kesalahan build saat menjalankan perintah sebelumnya. Jika hal ini terjadi, coba jalankan perintah ini di perintah Visual Studio.

    Setelah build berhasil, beberapa baris output terakhir akan terlihat mirip dengan output berikut:

    $ cmake ..
-- Building for: Visual Studio 15 2017
-- Selecting Windows SDK version 10.0.16299.0 to target Windows 10.0.17134.
-- The C compiler identification is MSVC 19.12.25835.0
-- The CXX compiler identification is MSVC 19.12.25835.0

...

-- Configuring done
-- Generating done
-- Build files have been written to: E:/IoT Testing/azure-iot-sdk-c/cmake

Mengedit sampel telemetri untuk mengaktifkan pelacakan terdistribusi

Di bagian ini, Anda mengedit sampel iothub_ll_telemetry_sample.c di repositori SDK untuk mengaktifkan pelacakan terdistribusi. Atau, Anda dapat menyalin versi sampel yang sudah diedit dari repositori azure-iot-distributed-tracing-sample .

  1. Gunakan editor untuk membuka file sumber azure-iot-sdk-c/iothub_client/samples/iothub_ll_telemetry_sample/iothub_ll_telemetry_sample.c.

  2. Temukan deklarasi konstanta connectionString:

    /* Paste in the your iothub connection string  */
static const char* connectionString = "[device connection string]";
#define MESSAGE_COUNT        5000
static bool g_continueRunning = true;
static size_t g_message_count_send_confirmations = 0;

    Ganti nilai connectionString konstanta dengan perangkat string koneksi yang Anda simpan di bagian Daftarkan perangkat dari mulai cepat untuk mengirim telemetri.

  3. Temukan baris kode yang memanggil IoTHubDeviceClient_LL_SetConnectionStatusCallback untuk mendaftarkan fungsi panggilan balik status koneksi sebelum perulangan kirim pesan. Tambahkan kode di bawah baris tersebut untuk memanggil IoTHubDeviceClient_LL_EnablePolicyConfiguration dan mengaktifkan pelacakan terdistribusi untuk perangkat:

    // Setting connection status callback to get indication of connection to iothub
(void)IoTHubDeviceClient_LL_SetConnectionStatusCallback(device_ll_handle, connection_status_callback, NULL);

// Enabled the distrubted tracing policy for the device
(void)IoTHubDeviceClient_LL_EnablePolicyConfiguration(device_ll_handle, POLICY_CONFIGURATION_DISTRIBUTED_TRACING, true);

do
{
    if (messages_sent < MESSAGE_COUNT)

    Fungsi ini IoTHubDeviceClient_LL_EnablePolicyConfiguration memungkinkan kebijakan untuk fitur IoT Hub tertentu yang dikonfigurasi melalui kembar perangkat. Setelah Anda mengaktifkan POLICY_CONFIGURATION_DISTRIBUTED_TRACING dengan menggunakan baris kode tambahan, perilaku pelacakan perangkat akan mencerminkan perubahan pelacakan terdistribusi yang dibuat pada perangkat kembar.

  4. Agar aplikasi sampel tetap berjalan tanpa menggunakan semua kuota, tambahkan penundaan satu detik di akhir perulangan kirim pesan:

        else if (g_message_count_send_confirmations >= MESSAGE_COUNT)
    {
        // After all messages are all received stop running
        g_continueRunning = false;
    }

    IoTHubDeviceClient_LL_DoWork(device_ll_handle);
    ThreadAPI_Sleep(1000);

} while (g_continueRunning);

Mengompilasi dan menjalankan

  1. iothub_ll_telemetry_sample Buka direktori proyek dari direktori CMake (azure-iot-sdk-c/cmake) yang Anda buat sebelumnya, dan kompilasi sampel:

    cd iothub_client/samples/iothub_ll_telemetry_sample
cmake --build . --target iothub_ll_telemetry_sample --config Debug

  2. Jalankan aplikasi lagi. Perangkat mengirim telemetri yang mendukung pelacakan terdistribusi.

    Debug/iothub_ll_telemetry_sample.exe

  3. Jaga agar aplikasi tetap berjalan. Anda dapat mengamati pesan yang dikirim ke IoT Hub di jendela konsol.

Untuk aplikasi klien yang dapat menerima keputusan pengambilan sampel dari cloud, coba sampel iothub_devicetwin_sample.c dalam repositori sampel pelacakan terdistribusi.

Solusi untuk klien non-Microsoft

Menerapkan fitur pelacakan terdistribusi tanpa menggunakan C SDK lebih kompleks. Kami tidak merekomendasikannya.

Pertama, Anda harus menerapkan semua primitif protokol IoT Hub dalam pesan Anda dengan mengikuti panduan pengembang Membuat dan membaca pesan IoT Hub. Kemudian, edit properti protokol dalam pesan MQTT dan AMQP untuk ditambahkan tracestate sebagai properti sistem.

Khususnya:

  • Untuk MQTT, tambahkan %24.tracestate=timestamp%3d1539243209 ke topik pesan. Ganti 1539243209 dengan waktu pembuatan pesan dalam format stempel waktu Unix. Sebagai contoh, lihat implementasi di C SDK.
  • Untuk AMQP, tambahkan key("tracestate") dan value("timestamp=1539243209") sebagai anotasi pesan. Untuk implementasi referensi, lihat file uamqp_messaging.c .

Untuk mengontrol persentase pesan yang berisi properti ini, terapkan logika untuk mendengarkan peristiwa yang dimulai cloud seperti pembaruan kembar.

Langkah berikutnya