مشاركة عبر

تتبع رسائل Azure IoT من جهاز إلى سحابة باستخدام التتبع الموزع (معاينة)

  • مقالة

استخدم التتبع الموزع (معاينة) في IoT Hub لمراقبة رسائل IoT أثناء مرورها عبر خدمات Azure. IoT Hub هي واحدة من أولى خدمات Azure لدعم التتبع المركز. نظرا لأن المزيد من خدمات Azure تدعم التتبع الموزع، يمكنك تتبع رسائل إنترنت الأشياء (IoT) عبر خدمات Azure المتضمنة في الحل الخاص بك. لمزيد من المعلومات حول الميزة، راجع ما هو التتبع الموزع؟.

عند تمكين التتبع الموزع ل IoT Hub، يمكنك:

  • مراقبة تدفق كل رسالة من خلال IoT Hub باستخدام سياق التتبع. يتضمن سياق التتبع معرفات الارتباط التي تسمح لك بربط الأحداث من مكون واحد بأحداث من مكون آخر. يمكنك تطبيقه على مجموعة فرعية أو جميع رسائل جهاز IoT باستخدام جهاز مزدوج.
  • تسجيل سياق التتبع إلى سجلات Azure Monitor.
  • قم بقياس وفهم تدفق الرسائل ووقت الاستجابة من الأجهزة إلى IoT Hub ونقاط نهاية التوجيه.

هام

التتبع الموزع ل Azure IoT Hub قيد المعاينة حاليا. للحصول على الشروط القانونية التي تنطبق على ميزات Azure الموجودة في الإصدار التجريبي، أو المعاينة، أو التي لم يتم إصدارها بعد في التوفر العام، راجع شروط الاستخدام التكميلية لمعاينات Microsoft Azure.

المتطلبات الأساسية

  • تم إنشاء مركز Azure IoT في إحدى المناطق التالية.

    • أوروبا الشمالية
    • جنوب شرق آسيا
    • West US 2

  • جهاز مسجل في مركز IoT الخاص بك. إذا لم يكن لديك جهاز في مركز IoT، فاتبع الخطوات الواردة في تسجيل جهاز واحفظ الجهاز سلسلة الاتصال لاستخدامه في هذه المقالة.

  • تفترض هذه المقالة أنك على دراية بإرسال رسائل التتبع عن بعد إلى IoT Hub الخاص بك.

  • أحدث إصدار من Git.

حدود الإصدار الأولي العام والاعتبارات

ضع في اعتبارك القيود التالية لتحديد ما إذا كانت ميزة المعاينة هذه مناسبة للسيناريوهات الخاصة بك:

  • اقتراح معيار سياق تتبع W3C هو حاليا مسودة عمل.

  • لغة التطوير الوحيدة التي يدعمها العميل SDK حاليا هي C، في فرع المعاينة العامة من SDK لجهاز Azure IoT ل C

  • لا تتوفر إمكانية التوأم من سحابة إلى جهاز للطبقة الأساسية ل IoT Hub. ومع ذلك، لا يزال IoT Hub يسجل إلى Azure Monitor إذا كان يرى عنوان سياق تتبع مكون بشكل صحيح.

  • لضمان التشغيل الفعال، يفرض IoT Hub تقييدا على معدل التسجيل الذي يمكن أن يحدث كجزء من التتبع الموزع.

  • يتم دعم ميزة التتبع الموزعة فقط لمراكز IoT التي تم إنشاؤها في المناطق التالية:

    • أوروبا الشمالية
    • جنوب شرق آسيا
    • West US 2

فهم التتبع الموزع لـ Azure IoT

تتبع العديد من حلول IoT، بما في ذلك البنية المرجعية ل Azure IoT، بشكل عام متغيرا من بنية الخدمات المصغرة. نظراً لأن حل IoT يصبح أكثر تعقيداً، ينتهي بك الأمر باستخدام عشرات الخدمات الصغيرة أو أكثر. قد تكون هذه الخدمات المصغرة أو لا تكون من Azure.

قد يكون تحديد مكان انخفاض رسائل IoT أو إبطاءها أمرا صعبا. على سبيل المثال، تخيل أن لديك حل IoT يستخدم خمس خدمات Azure مختلفة و1500 جهاز نشط. يرسل كل جهاز 10 رسائل من جهاز إلى سحابة في الثانية، لإجمالي 15000 رسالة في الثانية. ولكنك تلاحظ أن تطبيق الويب الخاص بك لا يرى سوى 10000 رسالة في الثانية. كيف تجد الجاني؟

لكي تقوم بإعادة إنشاء تدفق رسالة IoT عبر الخدمات، يجب أن تنشر كل خدمة معرف ارتباط يحدد الرسالة بشكل فريد. بعد أن يجمع Azure Monitor معرفات الارتباط في نظام مركزي، يمكنك استخدام هذه المعرفات لمشاهدة تدفق الرسائل. تسمى هذه الطريقة نمط التتبع الموزع.

لدعم التبني الأوسع للتتبع الموزع، تساهم Microsoft في اقتراح W3C القياسي للتتبع الموزع. عند تمكين دعم التتبع الموزع ل IoT Hub، فإنه يتبع هذا التدفق لكل رسالة تم إنشاؤها:

  1. يتم إنشاء رسالة على جهاز IoT.
  2. يقرر جهاز IoT (بمساعدة من السحابة) أنه يجب تعيين هذه الرسالة بسياق تتبع.
  3. تضيف tracestate SDK قيمة إلى خاصية الرسالة، والتي تحتوي على الطابع الزمني لإنشاء الرسالة.
  4. يرسل جهاز إنترنت الأشياء الرسالة إلى IoT Hub.
  5. تصل الرسالة إلى بوابة IoT Hub.
  6. يبحث IoT Hub عن tracestate القيمة في خصائص الرسالة ويتحقق ما إذا كانت بالتنسيق الصحيح. إذا كان الأمر كذلك، فإن IoT Hub ينشئ قيمة فريدة trace-id عالميا للرسالة وقيمة span-id ل "hop". يسجل IoT Hub هذه القيم في سجلات التتبع الموزعة ل IoT Hub ضمن DiagnosticIoTHubD2C العملية.
  7. عند الانتهاء من معالجة الرسائل، ينشئ IoT Hub قيمة أخرى span-id ويسجلها، جنبا إلى جنب مع القيمة الموجودة trace-id ، ضمن DiagnosticIoTHubIngress العملية.
  8. إذا تم تمكين التوجيه للرسالة، فسيكتبها IoT Hub إلى نقطة النهاية المخصصة. يسجل IoT Hub قيمة أخرى span-id بنفس trace-id القيمة ضمن DiagnosticIoTHubEgress الفئة.

تكوين التتبع الموزع في مركز IoT

في هذا القسم، يمكنك تكوين مركز IoT لتسجيل سمات التتبع الموزعة (معرفات الارتباط والطوابع الزمنية).

  1. انتقل إلى مركز IoT في مدخل Microsoft Azure.

  2. في الجزء الأيمن لمركز IoT، مرر لأسفل إلى قسم Monitoring وحدد Diagnostics settings.

  3. حدد Add diagnostic setting.

  4. في مربع اسم إعداد التشخيص، أدخل اسما لإعداد تشخيص جديد. على سبيل المثال، أدخل DistributedTracingSettings.

    لقطة شاشة توضح مكان إضافة اسم لإعدادات التشخيص.

  5. اختر خيارا واحدا أو أكثر من الخيارات التالية ضمن تفاصيل الوجهة لتحديد مكان إرسال معلومات التسجيل:

    • أرشفة في حساب تخزين: تكوين حساب تخزين ليحتوي على معلومات التسجيل.
    • البث إلى مركز الأحداث: تكوين مركز الأحداث بحيث يحتوي على معلومات التسجيل.
    • إرسال إلى Log Analytics: تكوين مساحة عمل Log Analytics لاحتواء معلومات التسجيل.

  6. في قسم Logs ، حدد العمليات التي تريد تسجيلها.

    قم بتضمين التتبع الموزع وتكوين فترة استبقاء بعدد الأيام التي تريد الاحتفاظ بها في التسجيل. يؤثر استبقاء السجل على تكاليف التخزين.

    لقطة شاشة توضح مكان عملية التتبع الموزع لإعدادات تشخيص IoT Hub.

  7. حدد حفظ.

  8. (اختياري) لمشاهدة تدفق الرسائل إلى أماكن مختلفة، قم بإعداد قاعدة التحويل إلى نقطتي نهاية مختلفتين على الأقل.

بعد تشغيل التسجيل، يسجل IoT Hub سجلا عند مواجهة رسالة تحتوي على خصائص تتبع صالحة في أي من الحالات التالية:

  • تصل الرسالة إلى بوابة مركز IoT.
  • يعالج مركز IoT الرسالة.
  • يتم توجيه الرسالة إلى نقاط النهاية المخصصة. يجب تمكين التوجيه.

لمعرفة المزيد بشأن هذه السجلات ومخططاتها، راجع Monitor IoT Hub والتتبع المركز في سجلات موارد IoT Hub.

تحديث خيارات أخذ العينات

لتغيير النسبة المئوية للرسائل التي سيتم تتبعها من السحابة، يجب عليك تحديث الجهاز المزدوج. يمكنك إجراء التحديثات باستخدام محرر JSON في مدخل Microsoft Azure أو SDK لخدمة IoT Hub. تقدم الأقسام الفرعية التالية أمثلة.

تحديث جهاز واحد

يمكنك استخدام مدخل Microsoft Azure أو ملحق Azure IoT Hub ل Visual Studio Code (VS Code) لتحديث معدل أخذ العينات لجهاز واحد.

  1. انتقل إلى مركز IoT في مدخل Microsoft Azure، ثم حدد الأجهزة من قسم إدارة الأجهزة من القائمة.

  2. اختر جهازك.

  3. حدد أيقونة الترس ضمن التتبع الموزع (معاينة). في اللوحة التي تفتح:

    1. حدد الخيار تمكين.
    2. بالنسبة إلى معدل أخذ العينات، اختر نسبة مئوية بين 0 و100.
    3. حدد حفظ.

    لقطة شاشة توضح كيفية تمكين التتبع الموزع في مدخل Microsoft Azure.

  4. انتظر بضع ثوان، ثم حدد تحديث. إذا أقر الجهاز بنجاح بالتغييرات التي أجريتها، فستظهر أيقونة مزامنة مع علامة اختيار.

تحديث مجمع لأجهزة متعددة

لتحديث تكوين أخذ عينات التتبع الموزع لأجهزة متعددة، استخدم التكوين التلقائي للجهاز. اتبع هذا المخطط المزدوج:

{
    "properties": {
        "desired": {
            "azureiot*com^dtracing^1": {
                "sampling_mode": 1,
                "sampling_rate": 100
            }
        }
    }
}
اسم العنصر المطلوب نوع ‏‏الوصف
sampling_mode ‏‏نعم‬ رقم صحيح يتم دعم اثنين من قيم الوضع حالياً لتشغيل أخذ العينات وإيقاف تشغيله. 1 قيد التشغيل، و 2 متوقف عن التشغيل.
sampling_rate ‏‏نعم‬ رقم صحيح هذه القيمة هي نسبة مئوية. يُسمح فقط بالقيم من 0 إلى 100 (شاملة).

الاستعلام عن التتبعات وتصورها

لمشاهدة جميع التتبعات التي تم تسجيلها بواسطة مركز IoT، استعلم عن مخزن السجل الذي حددته في إعدادات التشخيص. يوضح هذا القسم كيفية الاستعلام باستخدام Log Analytics.

إذا قمت بإعداد Log Analytics مع سجلات الموارد، استعلم عن طريق البحث عن سجلات في DistributedTracing الفئة. على سبيل المثال، يعرض هذا الاستعلام جميع التتبعات المسجلة:

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

فيما يلي بعض الأمثلة على السجلات في Log Analytics:

الوقت الذي تم إنشاؤه اسم العملية الفئة المستوى معرف الارتباط المدة بالمللي ثانية خصائص
2018-02-22T03:28:28.633Z DiagnosticIoTHubD2C تتبع الموزعة (معاينة) معلوماتي 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 تتبع الموزعة (معاينة) معلوماتي 00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01 20 {"isRoutingEnabled":"false","parentSpanId":"0144d2590aacd909"}
2018-02-22T03:28:48.633Z DiagnosticIoTHubEgress تتبع الموزعة (معاينة) معلوماتي 00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01 23 {"endpointType":"EventHub","endpointName":"myEventHub", "parentSpanId":"0144d2590aacd909"}

لفهم أنواع السجلات، راجع سجلات التتبع الموزعة ل Azure IoT Hub.

تشغيل نموذج التطبيق

في هذا القسم، تقوم بإعداد بيئة تطوير لاستخدامها مع Azure IoT C SDK. بعد ذلك، يمكنك تعديل إحدى العينات لتمكين التتبع الموزع على رسائل بيانات تتبع الاستخدام الخاصة بجهازك.

هذه الإرشادات مخصصة لبناء العينة على Windows. بالنسبة إلى البيئات الأخرى، راجع تجميع C SDK أو حزم C SDK للتطوير الخاص بالنظام الأساسي.

نسخ التعليمة البرمجية المصدري وتهيئة

  1. تثبيت تطوير سطح المكتب مع حمل عمل C++‎ ل Visual Studio 2022. يتم دعم Visual Studio 2019 أيضا.

  2. قم بتثبيت CMake. تأكد من أنه في الخاص بك PATH عن طريق إدخال cmake -version من موجه الأوامر.

  3. افتح موجه الأوامر أو Git Bash shell. قم بتشغيل الأوامر التالية لاستنساخ أحدث إصدار من فرع المعاينة العامة لمستودع Azure IoT C SDK GitHub:

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

    توقع أن تستغرق هذه العملية عدة دقائق حتى تنتهي.

  4. قم بتشغيل الأوامر التالية من azure-iot-sdk-c الدليل لإنشاء cmake دليل فرعي والانتقال إلى cmake المجلد:

    mkdir cmake
cd cmake
cmake ..

    إذا تعذر على CMake العثور على المحول البرمجي C++، فقد تواجه أخطاء في الإنشاء أثناء تشغيل الأمر السابق. إذا حدث ذلك، فحاول تشغيل الأمر في موجه الأوامر Visual Studio.

    بعد نجاح البنية، ستبدو أسطر الإخراج القليلة الأخيرة مشابهة للإخراج التالي:

    $ 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

تحرير نموذج بيانات تتبع الاستخدام لتمكين التتبع الموزع

في هذا القسم، يمكنك تحرير نموذج iothub_ll_telemetry_sample.c في مستودع SDK لتمكين التتبع الموزع. أو يمكنك نسخ إصدار تم تحريره بالفعل من النموذج من مستودع azure-iot-distributed-tracing-sample .

  1. استخدم محرراً لفتح ملف المصدر azure-iot-sdk-c/iothub_client/samples/iothub_ll_telemetry_sample/iothub_ll_telemetry_sample.c.

  2. ابحث عن إعلان الثابت 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;

    استبدل قيمة connectionString الثابت بالجهاز سلسلة الاتصال الذي قمت بحفظه في قسم تسجيل جهاز في التشغيل السريع لإرسال بيانات تتبع الاستخدام.

  3. ابحث عن سطر التعليمة البرمجية الذي يستدعي IoTHubDeviceClient_LL_SetConnectionStatusCallback لتسجيل وظيفة رد اتصال حالة الاتصال قبل حلقة إرسال الرسالة. أضف تعليمة برمجية ضمن هذا السطر لاستدعاء IoTHubDeviceClient_LL_EnablePolicyConfiguration وتمكين التتبع الموزع للجهاز:

    // 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)

    تمكن الدالة IoTHubDeviceClient_LL_EnablePolicyConfiguration النهج لميزات IoT Hub المحددة التي تم تكوينها عبر توائم الجهاز. بعد التمكين POLICY_CONFIGURATION_DISTRIBUTED_TRACING باستخدام السطر الإضافي من التعليمات البرمجية، سيعكس سلوك التتبع للجهاز تغييرات التتبع الموزعة التي تم إجراؤها على الجهاز المزدوج.

  4. للإبقاء على نموذج التطبيق قيد التشغيل دون استخدام كل حصتك، أضف تأخيراً مدته ثانية واحدة في نهاية حلقة إرسال الرسائل:

        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);

تجميع وتشغيل

  1. انتقل إلى iothub_ll_telemetry_sample دليل المشروع من دليل CMake (azure-iot-sdk-c/cmake) الذي قمت بإنشائه سابقا، وقم بتجميع النموذج:

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

  2. قم بتشغيل التطبيق: يرسل الجهاز بيانات تتبع الاستخدام التي تدعم التتبع الموزع.

    Debug/iothub_ll_telemetry_sample.exe

  3. استمر في تشغيل التطبيق. يمكنك مراقبة الرسائل التي يتم إرسالها إلى IoT Hub في نافذة وحدة التحكم.

بالنسبة لتطبيق العميل الذي يمكنه تلقي قرارات أخذ العينات من السحابة، جرب نموذج iothub_devicetwin_sample.c في مستودع عينة التتبع الموزع.

الحل البديل للعملاء غير التابعين ل Microsoft

يعد تنفيذ ميزة التتبع الموزع دون استخدام C SDK أكثر تعقيدا. لا نوصي بذلك.

أولا، يجب عليك تنفيذ جميع البدائيات لبروتوكول IoT Hub في رسائلك باتباع دليل المطور إنشاء رسائل IoT Hub وقراءتها. ثم قم بتحرير خصائص البروتوكول في رسائل MQTT وAMQP لإضافتها tracestate كخاصية نظام.

على وجه التحديد:

  • بالنسبة إلى MQTT، أضف %24.tracestate=timestamp%3d1539243209 إلى موضوع الرسالة. استبدل 1539243209 بوقت إنشاء الرسالة بتنسيق الطابع الزمني Unix. على سبيل المثال، راجع التنفيذ في C SDK.
  • بالنسبة إلى AMQP، أضف key("tracestate") وvalue("timestamp=1539243209") كتعليق توضيحي للرسالة. لتنفيذ مرجع، راجع ملف uamqp_messaging.c .

للتحكم في النسبة المئوية للرسائل التي تحتوي على هذه الخاصية، قم بتنفيذ المنطق للاستماع إلى الأحداث التي بدأتها السحابة مثل التحديثات المزدوجة.

الخطوات التالية