مشاركة عبر

مكتبة عميل Azure Monitor Opentelemetry Distro ل Python - الإصدار 1.1.1

  • مقالة

يوفر توزيع Azure Monitor ل Opentelemetry Python مكونات متعددة قابلة للتثبيت متاحة لحل مراقبة Opentelemetry Azure Monitor. يسمح لك بأداة تطبيقات Python لالتقاط بيانات تتبع الاستخدام والإبلاغ عنها إلى Azure Monitor عبر مصدري مراقبة Azure.

تقوم هذه التوزيعة تلقائيا بتثبيت المكتبات التالية:

الأجهزة المدعومة رسميا

تسمح أجهزة OpenTelemetry بالتحصيل التلقائي للطلبات المرسلة من المكتبات الآلية الأساسية. فيما يلي قائمة بأدوات OpenTelemetry التي تأتي مجمعة مع توزيعة مراقبة Azure. يتم تمكين هذه الأجهزة بشكل افتراضي. راجع قسم الاستخدام أدناه لمعرفة كيفية إلغاء الاشتراك في هذه الأجهزة.

تقرير عن حالة النظام اسم المكتبة المدعومة الإصدارات المدعومة
تتبع Azure Core OpenTelemetry azure_sdk
OpenTelemetry Django Instrumentation جانغو الرابط
OpenTelemetry FastApi Instrumentation fastapi الرابط
OpenTelemetry Flask Instrumentation قاروره الرابط
OpenTelemetry Psycopg2 Instrumentation psycopg2 الرابط
OpenTelemetry Requests Instrumentation requests الرابط
OpenTelemetry UrlLib Instrumentation urllib الكل
OpenTelemetry UrlLib3 Instrumentation urllib3 الرابط

إذا كنت ترغب في إضافة دعم لأجهزة OpenTelemetry أخرى، فالرجاء إرسال طلب ميزة. في غضون ذلك، يمكنك استخدام أدوات OpenTelemetry يدويا عبر واجهات برمجة التطبيقات الخاصة بها (أي instrument()) في التعليمات البرمجية الخاصة بك. راجع هذا للحصول على مثال.

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

تجمع هذه الحزمة سلسلة من مكونات OpenTelemetry وAzure Monitor لتمكين جمع وإرسال بيانات تتبع الاستخدام إلى Azure Monitor. بالنسبة ل MANUAL instrumentation، استخدم الدالة configure_azure_monitor . الأجهزة التلقائية غير مدعومة بعد.

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

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

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

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

لاستخدام هذه الحزمة، يجب أن يكون لديك:

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

تثبيت Azure Monitor Opentelemetry Distro مع pip:

pip install azure-monitor-opentelemetry

الاستخدام

يمكنك استخدام configure_azure_monitor لإعداد الأجهزة لتطبيقك على Azure Monitor. configure_azure_monitor يدعم الوسيطات الاختيارية التالية. تأخذ جميع معلمات المرور الأولوية على أي متغيرات بيئة ذات صلة.

المعلمة الوصف متغير البيئة
connection_string سلسلة الاتصال لمورد Application Insights الخاص بك. سيتم ملء سلسلة الاتصال تلقائيا من APPLICATIONINSIGHTS_CONNECTION_STRING متغير البيئة إذا لم يتم تمريره بشكل صريح. APPLICATIONINSIGHTS_CONNECTION_STRING
logger_name اسم مسجل Python الذي يتم بموجبه جمع بيانات تتبع الاستخدام. N/A
instrumentation_options قاموس متداخل يحدد الأجهزة التي يجب تمكينها أو تعطيلها. تتم الإشارة إلى الأجهزة بواسطة أسماء المكتبات الخاصة بها. على سبيل المثال، {"azure_sdk": {"enabled": False}, "flask": {"enabled": False}, "django": {"enabled": True}} سيعطيل Azure Core Tracing و Flask instrumentation ولكنه يترك Django والأجهزة الافتراضية الأخرى ممكنة. يمكن أيضا استخدام متغير البيئة الموضح OTEL_PYTHON_DISABLED_INSTRUMENTATIONS أدناه لتعطيل الأجهزة. N/A

يمكنك تكوين المزيد باستخدام متغيرات بيئة OpenTelemetry مثل: | متغير البيئة | الوصف | |-------------|----------------------| | OTEL_SERVICE_NAME، OTEL_RESOURCE_ATTRIBUTES | يحدد مورد OpenTelemetry المقترن بتطبيقك. | | OTEL_LOGS_EXPORTER | إذا تم تعيينه إلى None، يعطل جمع وتصدير بيانات تتبع الاستخدام للتسجيل. | | OTEL_METRICS_EXPORTER | إذا تم تعيينه إلى None، يعطل جمع وتصدير القياس عن بعد القياسي. | | OTEL_TRACES_EXPORTER | إذا تم تعيينه إلى None، يعطل جمع وتصدير بيانات تتبع الاستخدام الموزعة. | | OTEL_BLRP_SCHEDULE_DELAY | يحدد الفاصل الزمني لتصدير التسجيل بالمللي ثانية. الإعدادات الافتراضية إلى 5000. | | OTEL_BSP_SCHEDULE_DELAY | يحدد الفاصل الزمني لتصدير التتبع الموزع بالمللي ثانية. الإعدادات الافتراضية إلى 5000. | | OTEL_TRACES_SAMPLER_ARG | يحدد نسبة بيانات تتبع الاستخدام الموزعة التي سيتم أخذ عينات منها. القيم المقبولة موجودة في النطاق [0,1]. الإعدادات الافتراضية إلى 1.0، ما يعني أنه لا يتم أخذ عينات من بيانات تتبع الاستخدام. | | OTEL_PYTHON_DISABLED_INSTRUMENTATIONS | يحدد أي من الأجهزة المدعومة لتعطيلها. لن يتم وضع علامة على الأجهزة المعطلة كجزء من configure_azure_monitor. ومع ذلك، لا يزال من الممكن تجهيزها يدويا مباشرة instrument() . يقبل قائمة مفصولة بفواصل من أسماء المكتبات الصغيرة. على سبيل المثال، قم بتعيين إلى "psycopg2,fastapi" لتعطيل أجهزة Psycopg2 وFastAPI. الإعدادات الافتراضية لقائمة فارغة، مما يتيح جميع الأجهزة المدعومة. | | OTEL_EXPERIMENTAL_RESOURCE_DETECTORS | متغير بيئة OpenTelemetry تجريبي يستخدم لتحديد Resource Detectors لاستخدامه لإنشاء سمات الموارد. هذه ميزة تجريبية ويمكن أن يتغير اسم هذا المتغير وسلوكه بطريقة غير متوافقة مع الإصدارات السابقة. الإعدادات الافتراضية ل "azure_app_service،azure_vm" لتمكين Azure Resource Detectors ل Azure App Service وAzure VM. لإضافة كاشفات موارد معينة أو إزالتها، قم بتعيين متغير البيئة وفقا لذلك. راجع وثائق OpenTelemetry Python Resource Detector للحصول على المزيد. |

تكوينات مصدر OpenTelemetry لمراقبة Azure

يمكنك تمرير معلمات تكوين مصدر OpenTelemetry لمراقبة Azure مباشرة إلى configure_azure_monitor. راجع التكوين الإضافي المتعلق بالتصدير هنا.

...
configure_azure_monitor(
   connection_string="<your-connection-string>",
   disable_offline_storage=True,
)
...

أمثلة

تتوفر العينات هنا لتوضيح كيفية استخدام خيارات التكوين أعلاه.

المراقبة في Azure Functions

تتبع الارتباط

لن ترتبط الطلبات الواردة المتعقبة الواردة إلى تطبيق Python المستضاف في Azure Functions تلقائيا ببيانات تتبع الاستخدام التي يتم تعقبها داخله. يمكنك تحقيق ارتباط التتبع TraceContext يدويا عن طريق استخراج مباشرة كما هو موضح أدناه:


import azure.functions as func

from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace
from opentelemetry.propagate import extract

# Configure Azure monitor collection telemetry pipeline
configure_azure_monitor()

def main(req: func.HttpRequest, context) -> func.HttpResponse:
   ...
   # Store current TraceContext in dictionary format
   carrier = {
      "traceparent": context.trace_context.Traceparent,
      "tracestate": context.trace_context.Tracestate,
   }
   tracer = trace.get_tracer(__name__)
   # Start a span using the current context
   with tracer.start_as_current_span(
      "http_trigger_span",
      context=extract(carrier),
   ):
      ...

مشكلات التسجيل

يرسل عامل Azure Functions نفسه تسجيل القياس عن بعد نفسه دون استخدام azure monitor sdk (الاستدعاء إلى configure_azure_monitor()). سيؤدي ذلك إلى تجربة إدخالات بيانات تتبع الاستخدام المكررة عند إرسال بيانات تتبع الاستخدام للتسجيل. توصيتنا للعملاء هي استخدام SDK فقط لأنها ستسمح بميزات وبيانات تتبع الاستخدام أكثر ثراء من استخدام المضمنة التي يوفرها عامل Azure Functions. يمكنك إيقاف تشغيل مسجل بيانات تتبع الاستخدام Azure Functions عن طريق مسح قائمة معالجات المسجل.

...
root_logger = logging.getLogger()
for handler in root_logger.handlers[:]:
    root_logger.removeHandler(handler)
...

تأكد من استدعاء ما سبق قبل إعداد أي مسجلين أو استدعاء configure_azure_monitor() .

يمكنك أيضا تعطيل التسجيل من خلال تكوين Azure Functions.

v2.x+

...
{
  "logging": {
    ...
    "logLevel": {
      "default": "None",
      ...
    }
  }
}
...

v1.x

...
{
  "logger": {
    "categoryFilter": {
      "defaultLevel": "None",
      ...
    }
  }
}
...

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

يقوم المصدر برفع الاستثناءات المحددة في Azure Core.

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

تحقق من الوثائق لمزيد من المعلومات.

المساهمة

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

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

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

وثائق إضافية