الاستعلام عن واجهات برمجة تطبيقات EventStore لأحداث نظام المجموعة

تتناول هذه المقالة كيفية الاستعلام عن واجهات برمجة تطبيقات EventStore المتوفرة في الإصدار 6.2 من Service Fabric والإصدارات الأحدث - إذا كنت ترغب في معرفة المزيد حول خدمة EventStore، فراجع نظرة عامة على خدمة EventStore. حالياً، يمكن لخدمة EventStore الوصول إلى البيانات لآخر 7 أيام فقط (يعتمد ذلك على نهج استبقاء بيانات التشخيص الخاص بمجموعتك).

ملاحظة

واجهات برمجة تطبيقات EventStore هي GA اعتباراً من الإصدار 6.4 من Service Fabric لمجموعات Windows فقط التي تعمل على Azure.

يمكن الوصول إلى واجهات برمجة تطبيقات EventStore مباشرة عبر نقطة نهاية REST أو برمجياً. اعتماداً على الاستعلام، هناك العديد من المعلمات المطلوبة لجمع البيانات الصحيحة. تتضمن هذه المعلمات عادة:

• api-version: إصدار واجهات برمجة تطبيقات EventStore التي تستخدمها
• StartTimeUtc: يحدد بداية الفترة التي ترغب في النظر إليها
• EndTimeUtc: نهاية الفترة الزمنية

بالإضافة إلى هذه المعلمات، هناك معلمات اختيارية متاحة أيضاً، مثل:

• timeout: تجاوز المهلة الافتراضية البالغة 60 ثانية لتنفيذ عملية الطلب
• eventstypesfilter: يمنحك خياراً لتصفية أنواع أحداث محددة
• ExcludeAnalysisEvents: لا ترجع أحداث "التحليل". بشكل افتراضي، ستعود استعلامات EventStore مع أحداث "التحليل" حيثما أمكن ذلك. أحداث التحليل هي أحداث قناة تشغيلية أكثر ثراء تحتوي على سياق أو معلومات إضافية تتجاوز حدث Service Fabric العادي وتوفر المزيد من العمق.
• SkipCorrelationLookup: لا تبحث عن الأحداث المرتبطة المحتملة في المجموعة. بشكل افتراضي، سيحاول EventStore ربط الأحداث عبر نظام المجموعة، وربط الأحداث معاً كلما أمكن ذلك.

يمكن أن يكون كل كيان في نظام المجموعة استعلامات للأحداث. يمكنك أيضاً الاستعلام عن الأحداث لجميع الكيانات من هذا النوع. على سبيل المثال، يمكنك الاستعلام عن أحداث لعقدة معينة، أو لجميع العقد في مجموعتك. مجموعة الكيانات الحالية التي يمكنك الاستعلام عن الأحداث لها هي (مع كيفية هيكلة الاستعلام):

• نظام مجموعة: /EventsStore/Cluster/Events
• عُقد: /EventsStore/Nodes/Events
• عقدة: /EventsStore/Nodes/<NodeName>/$/Events
• تطبيقات: /EventsStore/Applications/Events
• تطبيق: /EventsStore/Applications/<AppName>/$/Events
• خدمات: /EventsStore/Services/Events
• خدمة: /EventsStore/Services/<ServiceName>/$/Events
• أقسام: /EventsStore/Partitions/Events
• قسم: /EventsStore/Partitions/<PartitionID>/$/Events
• نسخ متماثلة: /EventsStore/Partitions/<PartitionID>/$/Replicas/Events
• نسخة متماثلة: /EventsStore/Partitions/<PartitionID>/$/Replicas/<ReplicaID>/$/Events

ملاحظة

عند الإشارة إلى اسم تطبيق أو خدمة، لا يحتاج الاستعلام إلى تضمين بادئة "fabric:/". وبالإضافة إلى ذلك، إذا كانت أسماء التطبيقات أو الخدمات تحتوي على "/"، فقم بتبديلها إلى "~" للحفاظ على عمل الاستعلام. على سبيل المثال، إذا ظهر تطبيقك كـ "fabric:/App1/FrontendApp"، فستتم هيكلة الاستعلامات الخاصة بالتطبيق على النحو التالي /EventsStore/Applications/App1~FrontendApp/$/Events. وبالإضافة إلى ذلك، تظهر التقارير الصحية للخدمات اليوم ضمن التطبيق المقابل؛ لذلك يمكنك الاستعلام عن الأحداث DeployedServiceHealthReportCreated الخاصة بكيان التطبيق المناسب.

الاستعلام عن EventStore عبر نقاط نهاية واجهة برمجة تطبيقات REST

يمكنك الاستعلام عن EventStore مباشرة عبر نقطة نهاية REST، عن طريق تقديم طلبات GET إلى: <your cluster address>/EventsStore/<entity>/Events/.

على سبيل المثال، من أجل الاستعلام عن جميع أحداث المجموعة بين 2018-04-03T18:00:00Z و2018-04-04T18:00:00Z، سيبدو طلبك كما يلي:

Method: GET 
URL: http://mycluster:19080/EventsStore/Cluster/Events?api-version=6.4&StartTimeUtc=2018-04-03T18:00:00Z&EndTimeUtc=2018-04-04T18:00:00Z

قد لا يؤدي هذا إلى إرجاع أي أحداث أو إرجاع قائمة الأحداث بتنسيق json:

Response: 200
Body:
[
  {
    "Kind": "ClusterUpgradeStart",
    "CurrentClusterVersion": "0.0.0.0:",
    "TargetClusterVersion": "6.2:1.0",
    "UpgradeType": "Rolling",
    "RollingUpgradeMode": "UnmonitoredAuto",
    "FailureAction": "Manual",
    "EventInstanceId": "090add3c-8f56-4d35-8d57-a855745b6064",
    "TimeStamp": "2018-04-03T20:18:59.4313064Z",
    "HasCorrelatedEvents": false
  },
  {
    "Kind": "ClusterUpgradeDomainComplete",
    "TargetClusterVersion": "6.2:1.0",
    "UpgradeState": "RollingForward",
    "UpgradeDomains": "(0 1 2)",
    "UpgradeDomainElapsedTimeInMs": "78.5288",
    "EventInstanceId": "090add3c-8f56-4d35-8d57-a855745b6064",
    "TimeStamp": "2018-04-03T20:19:59.5729953Z",
    "HasCorrelatedEvents": false
  },
  {
    "Kind": "ClusterUpgradeDomainComplete",
    "TargetClusterVersion": "6.2:1.0",
    "UpgradeState": "RollingForward",
    "UpgradeDomains": "(3 4)",
    "UpgradeDomainElapsedTimeInMs": "0",
    "EventInstanceId": "090add3c-8f56-4d35-8d57-a855745b6064",
    "TimeStamp": "2018-04-03T20:20:59.6271949Z",
    "HasCorrelatedEvents": false
  },
  {
    "Kind": "ClusterUpgradeComplete",
    "TargetClusterVersion": "6.2:1.0",
    "OverallUpgradeElapsedTimeInMs": "120196.5212",
    "EventInstanceId": "090add3c-8f56-4d35-8d57-a855745b6064",
    "TimeStamp": "2018-04-03T20:20:59.8134457Z",
    "HasCorrelatedEvents": false
  }
]

هنا يمكننا رؤيته بين 2018-04-03T18:00:00Z و2018-04-04T18:00:00Z، أكملت هذه المجموعة ترقيتها الأولى بنجاح عندما تم الوقوف لأول مرة، من "CurrentClusterVersion": "0.0.0.0:" إلى "TargetClusterVersion": "6.2:1.0"، في "OverallUpgradeElapsedTimeInMs": "120196.5212".

استعلام EventStore برمجياً

يمكنك أيضاً الاستعلام عن EventStore برمجياً، عبر مكتبة عميل Service Fabric.

بمجرد إعداد عميل Service Fabric الخاص بك، يمكنك الاستعلام عن الأحداث عن طريق الوصول إلى EventStore على النحو التالي: sfhttpClient.EventStore.<request>

فيما يلي مثال لطلب جميع أحداث المجموعة بين 2018-04-03T18:00:00Z و2018-04-04T18:00:00Z، عبر الدالة GetClusterEventListAsync.

var sfhttpClient = ServiceFabricClientFactory.Create(clusterUrl, settings);

var clstrEvents = sfhttpClient.EventsStore.GetClusterEventListAsync(
    "2018-04-03T18:00:00Z",
    "2018-04-04T18:00:00Z")
    .GetAwaiter()
    .GetResult()
    .ToList();

فيما يلي مثال آخر يقوم بالاستعلام عن صحة نظام المجموعة وجميع أحداث العقدة في سبتمبر 2018 ويطبعها.

  const int timeoutSecs = 60;
  var clusterUrl = new Uri(@"http://localhost:19080"); // This example is for a Local cluster
  var sfhttpClient = ServiceFabricClientFactory.Create(clusterUrl);

  var clusterHealth = sfhttpClient.Cluster.GetClusterHealthAsync().GetAwaiter().GetResult();
  Console.WriteLine("Cluster Health: {0}", clusterHealth.AggregatedHealthState.Value.ToString());

  
  Console.WriteLine("Querying for node events...");
  var nodesEvents = sfhttpClient.EventsStore.GetNodesEventListAsync(
      "2018-09-01T00:00:00Z",
      "2018-09-30T23:59:59Z",
      timeoutSecs,
      "NodeDown,NodeUp")
      .GetAwaiter()
      .GetResult()
      .ToList();
  Console.WriteLine("Result Count: {0}", nodesEvents.Count());

  foreach (var nodeEvent in nodesEvents)
  {
      Console.Write("Node event happened at {0}, Node name: {1} ", nodeEvent.TimeStamp, nodeEvent.NodeName);
      if (nodeEvent is NodeDownEvent)
      {
          var nodeDownEvent = nodeEvent as NodeDownEvent;
          Console.WriteLine("(Node is down, and it was last up at {0})", nodeDownEvent.LastNodeUpAt);
      }
      else if (nodeEvent is NodeUpEvent)
      {
          var nodeUpEvent = nodeEvent as NodeUpEvent;
          Console.WriteLine("(Node is up, and it was last down at {0})", nodeUpEvent.LastNodeDownAt);
      }
  }

عينات السيناريوهات والاستعلامات

فيما يلي بعض الأمثلة حول كيفية استدعاء واجهات برمجة تطبيقات Event Store REST لفهم حالة مجموعتك.

ترقيات نظام المجموعة:

لمعرفة آخر مرة تمت فيها ترقية مجموعتك بنجاح أو محاولة ترقيتها خلال الأسبوع الماضي، يمكنك الاستعلام عن واجهات برمجة التطبيقات للترقيات التي تم إكمالها مؤخراً إلى مجموعتك، عن طريق الاستعلام عن أحداث "ClusterUpgradeComplete" في EventStore: https://mycluster.cloudapp.azure.com:19080/EventsStore/Cluster/Events?api-version=6.4&starttimeutc=2017-04-22T17:01:51Z&endtimeutc=2018-04-29T17:02:51Z&EventsTypesFilter=ClusterUpgradeCompleted

مشكلات ترقية نظام مجموعة:

وبالمثل، إذا كانت هناك مشكلات تتعلق بترقية نظام مجموعة حديثة، فيمكنك الاستعلام عن كافة الأحداث الخاصة بكيان نظام المجموعة. سترى العديد من الأحداث، بما في ذلك بدء الترقيات وكل UD تم تنفيذ الترقية له بنجاح. سترى أيضاً أحداثاً للنقطة التي بدأ فيها التراجع والأحداث الصحية المقابلة. إليك الاستعلام الذي ستستخدمه لهذا الغرض: https://mycluster.cloudapp.azure.com:19080/EventsStore/Cluster/Events?api-version=6.4&starttimeutc=2017-04-22T17:01:51Z&endtimeutc=2018-04-29T17:02:51Z

تغييرات حالة العقدة:

لرؤية تغييرات حالة العقدة خلال الأيام القليلة الماضية -عندما زادت العقد أو نقصت، أو تم تنشيطها أو إلغاء تنشيطها (إما بواسطة النظام الأساسي أو خدمة Chaos أو من إدخال المستخدم) - استخدم الاستعلام التالي: https://mycluster.cloudapp.azure.com:19080/EventsStore/Nodes/Events?api-version=6.4&starttimeutc=2017-04-22T17:01:51Z&endtimeutc=2018-04-29T17:02:51Z

أحداث التطبيق:

يمكنك أيضاً تعقب عمليات توزيع التطبيقات الأخيرة وترقياتها. استخدم الاستعلام التالي لعرض كافة أحداث التطبيق في مجموعتك: https://mycluster.cloudapp.azure.com:19080/EventsStore/Applications/Events?api-version=6.4&starttimeutc=2017-04-22T17:01:51Z&endtimeutc=2018-04-29T17:02:51Z

صحة المحفوظات للتطبيق:

بالإضافة إلى مجرد رؤية أحداث دورة حياة التطبيق، قد ترغب أيضاً في الاطلاع على بيانات المحفوظات الخاصة بسلامة تطبيق معين. يمكنك القيام بذلك عن طريق تحديد اسم التطبيق الذي تريد جمع البيانات له. استخدم هذا الاستعلام للحصول على كافة أحداث سلامة التطبيق: https://mycluster.cloudapp.azure.com:19080/EventsStore/Applications/myApp/$/Events?api-version=6.4&starttimeutc=2018-03-24T17:01:51Z&endtimeutc=2018-03-29T17:02:51Z&EventsTypesFilter=ApplicationNewHealthReport. إذا كنت تريد تضمين أحداث صحية ربما انتهت صلاحيتها (مرت مدة بقائها (TTL))، فأضف ,ApplicationHealthReportExpired إلى نهاية الاستعلام، للتصفية على نوعين من الأحداث.

صحة المحفوظات لجميع الخدمات في "myApp":

حالياً، تظهر أحداث التقرير الصحي للخدمات كأحداث DeployedServicePackageNewHealthReport ضمن كيان التطبيق المقابل. لمعرفة كيفية أداء خدماتك لـ "App1"، استخدم الاستعلام التالي: https://mycluster.cloudapp.azure.com:19080/EventsStore/Applications/myapp/$/Events?api-version=6.4&starttimeutc=2017-04-22T17:01:51Z&endtimeutc=2018-04-29T17:02:51Z&EventsTypesFilter=DeployedServicePackageNewHealthReport

إعادة تكوين القسم:

للاطلاع على كافة حركات الأقسام التي حدثت في نظام المجموعة، قم بالاستعلام عن الحدث PartitionReconfigured. يمكن أن يساعدك ذلك في معرفة أحمال العمل التي يتم تشغيلها على أي عقدة في أوقات محددة، عند تشخيص المشكلات في مجموعتك. فيما يلي نموذج استعلام يقوم بذلك: https://mycluster.cloudapp.azure.com:19080/EventsStore/Partitions/Events?api-version=6.4&starttimeutc=2018-04-22T17:01:51Z&endtimeutc=2018-04-29T17:02:51Z&EventsTypesFilter=PartitionReconfigured

خدمة Chaos:

هناك حدث عند بدء تشغيل خدمة Chaos أو إيقافها يتم كشفه على مستوى المجموعة. للاطلاع على استخدامك الأخير لخدمة Chaos، استخدم الاستعلام التالي: https://mycluster.cloudapp.azure.com:19080/EventsStore/Cluster/Events?api-version=6.4&starttimeutc=2017-04-22T17:01:51Z&endtimeutc=2018-04-29T17:02:51Z&EventsTypesFilter=ChaosStarted,ChaosStopped