مكتبة عميل Azure Monitor Ingestion ل Python - الإصدار 1.0.3

مقالة
11/07/2023

تستخدم مكتبة عميل استيعاب Azure Monitor لإرسال سجلات مخصصة إلى Azure Monitor باستخدام واجهة برمجة تطبيقات استيعاب السجلات.

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

الموارد:

الشروع في العمل

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

تثبيت الحِزَمة

قم بتثبيت مكتبة عميل Azure Monitor Ingestion ل Python باستخدام pip:

pip install azure-monitor-ingestion

إنشاء العميل

مطلوب عميل مصادق عليه لتحميل السجلات إلى Azure Monitor. تتضمن المكتبة كلا من النماذج المتزامنة وغير المتزامنة للعملاء. للمصادقة، أنشئ مثيلا لبيانات اعتماد الرمز المميز. استخدم هذا المثيل عند إنشاء LogsIngestionClient. تستخدم DefaultAzureCredential الأمثلة التالية من حزمة azure-identity .

العملاء المتزامنون

ضع في اعتبارك المثال التالي، الذي ينشئ عملاء متزامنين لتحميل السجلات:

import os
from azure.identity import DefaultAzureCredential
from azure.monitor.ingestion import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()
logs_client = LogsIngestionClient(endpoint, credential)

عملاء غير متزامنين

يتم العثور على النماذج غير المتزامنة لواجهات برمجة تطبيقات العميل في .aioمساحة الاسم -اللاحقة. على سبيل المثال:

import os
from azure.identity.aio import DefaultAzureCredential
from azure.monitor.ingestion.aio import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()
logs_client = LogsIngestionClient(endpoint, credential)

تكوين العملاء لسحب Azure غير العامة

بشكل افتراضي، LogsIngestionClient يتم تكوين للاتصال بسحابة Azure العامة. للاتصال بسحابات Azure غير العامة، يلزم وجود بعض التكوين الإضافي. يجب توفير النطاق المناسب للمصادقة باستخدام وسيطة credential_scopes الكلمة الأساسية. يوضح المثال التالي كيفية تكوين العميل للاتصال ب Azure US Government:

logs_client = LogsIngestionClient(endpoint, credential_scopes=["https://monitor.azure.us//.default"])

المفاهيم الرئيسية

نقطة نهاية جمع البيانات

تسمح لك نقاط نهاية تجميع البيانات (DCEs) بتكوين إعدادات الاستيعاب بشكل فريد لـ Azure Monitor. توفر هذه المقالة نظرة عامة على نقاط نهاية جمع البيانات بما في ذلك محتوياتها وبنيتها وكيفية إنشائها والعمل معها.

قاعدة جمع البيانات

تحدد قواعد جمع البيانات (DCR) البيانات التي تم جمعها بواسطة Azure Monitor وتحدد كيفية ومكان إرسال تلك البيانات أو تخزينها. يجب أن يحدد استدعاء REST API DCR لاستخدامه. يمكن أن يدعم DCE واحد عدة DCRs، بحيث يمكنك تحديد DCR مختلف لمصادر مختلفة وجداول الهدف.

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

لمزيد من المعلومات، راجع قواعد جمع البيانات في Azure Monitor، وشاهد هذه المقالة للحصول على تفاصيل حول بنية DCR. للحصول على معلومات حول كيفية استرداد معرف DCR، راجع هذا البرنامج التعليمي.

جداول مساحة عمل Log Analytics

يمكن للسجلات المخصصة إرسال البيانات إلى أي جدول مخصص تقوم بإنشائه وإلى جداول مضمنة معينة في مساحة عمل Log Analytics. يجب أن يكون الجدول الهدف موجودًا قبل أن تتمكن من إرسال البيانات إليه. الجداول المضمنة التالية مدعومة حاليًا:

استرداد السجلات

يمكن الاستعلام عن السجلات التي تم تحميلها باستخدام هذه المكتبة باستخدام مكتبة عميل استعلام Azure Monitor .

تحميل سجلات مخصصة

يوضح هذا المثال تحميل السجلات إلى Azure Monitor.

import os

from azure.core.exceptions import HttpResponseError
from azure.identity import DefaultAzureCredential
from azure.monitor.ingestion import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()

client = LogsIngestionClient(endpoint=endpoint, credential=credential, logging_enable=True)

rule_id = os.environ['LOGS_DCR_RULE_ID']
body = [
      {
        "Time": "2021-12-08T23:51:14.1104269Z",
        "Computer": "Computer1",
        "AdditionalContext": "context-2"
      },
      {
        "Time": "2021-12-08T23:51:14.1104269Z",
        "Computer": "Computer2",
        "AdditionalContext": "context"
      }
    ]

try:
    client.upload(rule_id=rule_id, stream_name=os.environ['LOGS_DCR_STREAM_NAME'], logs=body)
except HttpResponseError as e:
    print(f"Upload failed: {e}")

التحميل باستخدام معالجة الأخطاء المخصصة

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

# Example 1: Collect all logs that failed to upload.
failed_logs = []
def on_error(error):
    print("Log chunk failed to upload with error: ", error.error)
    failed_logs.extend(error.failed_logs)

# Example 2: Ignore all errors.
def on_error_pass(error):
    pass

client.upload(rule_id=rule_id, stream_name=os.environ['LOGS_DCR_STREAM_NAME'], logs=body, on_error=on_error)

استكشاف الأخطاء وإصلاحها

للحصول على تفاصيل حول تشخيص سيناريوهات الفشل المختلفة، راجع دليل استكشاف الأخطاء وإصلاحها.

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

لمعرفة المزيد حول Azure Monitor، راجع وثائق خدمة Azure Monitor.

عينات

تظهر نماذج التعليمات البرمجية التالية سيناريوهات شائعة مع مكتبة عميل Azure Monitor Ingestion.

عينات استيعاب السجلات

المساهمة

هذا المشروع يرحب بالمساهمات والاقتراحات. معظم المساهمات تتطلب منك الموافقة على اتفاقية ترخيص المساهم (CLA) التي تعلن أن لديك الحق في منحنا حق استخدام مساهمتك. للحصول على التفاصيل، تفضل بزيارة cla.microsoft.com.

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

اعتمد هذا المشروع مدونة السلوك من المصادر المفتوحة من Microsoft. لمزيد من المعلومات، راجع الأسئلة الشائعة حول مدونة قواعد السلوك أو الاتصال بأي أسئلة أو تعليقات opencode@microsoft.com إضافية.

Share via