مشاركة عبر

الترحيل من .NET Application Insights SDKs إلى Azure Monitor OpenTelemetry

  • مقالة

يوفر هذا الدليل إرشادات خطوة بخطوة لترحيل تطبيقات .NET المختلفة من استخدام مجموعات تطوير برامج Application Insights (SDKs) إلى قياس Azure Monitor OpenTelemetry.

توقع تجربة مماثلة مع Azure Monitor OpenTelemetry instrumentation كما هو الحال مع Application Insights SDKs. لمزيد من المعلومات ومقارنة الميزات حسب الميزات، راجع حالة إصدار الميزات.

إذا كنت تبدأ باستخدام Application Insights ولا تحتاج إلى الترحيل من واجهة برمجة التطبيقات الكلاسيكية، فشاهد تمكين القياس المفتوح ل Azure Monitor.

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

  • تطبيق ويب ASP.NET Core تم تجهيزه بالفعل باستخدام Application Insights دون أي تخصيصات
  • إصدار مدعوم بنشاط من .NET

تلميح

تسعى مجموعة منتجاتنا بنشاط للحصول على تعليقات حول هذه الوثائق. قدم ملاحظات إلى otel@microsoft.com قسم الدعم أو راجعه.

إزالة Application Insights SDK

إشعار

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

  1. إزالة حزم NuGet

    قم بإزالة الحزمة Microsoft.ApplicationInsights.AspNetCore من .csproj

    dotnet remove package Microsoft.ApplicationInsights.AspNetCore

  2. إزالة التعليمات البرمجية للتهيئة والتخصيصات

    قم بإزالة أي مراجع إلى أنواع Application Insights في قاعدة التعليمات البرمجية الخاصة بك.

    تلميح

    بعد إزالة حزمة Application Insights، يمكنك إعادة إنشاء التطبيق الخاص بك للحصول على قائمة بالمراجع التي تحتاج إلى إزالتها.

    • قم بإزالة Application Insights من الخاص بك ServiceCollection عن طريق حذف السطر التالي:

      builder.Services.AddApplicationInsightsTelemetry();

    • قم بإزالة ApplicationInsights المقطع من appsettings.json.

      {
    "ApplicationInsights": {
        "ConnectionString": "<Your Connection String>"
    }
}

  3. تنظيف وبناء

    افحص دليل الحاوية للتحقق من إزالة كافة المراجع إلى Microsoft.ApplicationInsights.* .

  4. اختبار التطبيق الخاص بك

    تحقق من أن التطبيق الخاص بك ليس له عواقب غير متوقعة.

تلميح

تسعى مجموعة منتجاتنا بنشاط للحصول على تعليقات حول هذه الوثائق. قدم ملاحظات إلى otel@microsoft.com قسم الدعم أو راجعه.

تمكين OpenTelemetry

نوصي بإنشاء مورد تطوير واستخدام سلسلة الاتصال الخاصة به عند اتباع هذه الإرشادات.

لقطة شاشة تعرض نظرة عامة حول Application Insights وسلسلة الاتصال.

خطط لتحديث سلسلة الاتصال لإرسال بيانات تتبع الاستخدام إلى المورد الأصلي بعد تأكيد نجاح الترحيل.

  1. تثبيت Azure Monitor Distro

    يتيح Azure Monitor Distro بيانات تتبع الاستخدام التلقائية من خلال تضمين مكتبات أدوات القياس المفتوح لجمع التتبعات والمقاييس والسجلات والاستثناءات، ويسمح بجمع بيانات تتبع الاستخدام المخصصة.

    تثبيت Azure Monitor Distro يجلب OpenTelemetry SDK كتبعية.

    dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

  2. إضافة وتكوين كل من OpenTelemetry وAzure Monitor

    يجب تكوين OpenTelemery SDK عند بدء تشغيل التطبيق كجزء من ServiceCollection، عادة في Program.cs.

    لدى OpenTelemetry مفهوم ثلاث إشارات؛ التتبعات والمقاييس والسجلات. يقوم Azure Monitor Distro بتكوين كل من هذه الإشارات.

Program.cs

يوضح نموذج التعليمات البرمجية التالي الأساسيات.

using Azure.Monitor.OpenTelemetry.AspNetCore;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        // Call AddOpenTelemetry() to add OpenTelemetry to your ServiceCollection.
        // Call UseAzureMonitor() to fully configure OpenTelemetry.
        builder.Services.AddOpenTelemetry().UseAzureMonitor();

        var app = builder.Build();
        app.MapGet("/", () => "Hello World!");
        app.Run();
    }
}

نوصي بتعيين سلسلة الاتصال في متغير بيئة:

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

يتم تفصيل المزيد من الخيارات لتكوين سلسلة الاتصال هنا: تكوين سلسلة اتصال Application Insights.

تلميح

تسعى مجموعة منتجاتنا بنشاط للحصول على تعليقات حول هذه الوثائق. قدم ملاحظات إلى otel@microsoft.com قسم الدعم أو راجعه.

تثبيت مكتبات الأجهزة وتكوينها

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

يتم تضمين المكتبات التالية في Distro.

تخصيص مكتبات الأجهزة

يتضمن Azure Monitor Distro أجهزة .NET OpenTelemetry ل ASP.NET Core وHttpClient وSQLClient. يمكنك تخصيص هذه الأجهزة المضمنة أو إضافة أدوات إضافية يدويا بنفسك باستخدام OpenTelemetry API.

فيما يلي بعض الأمثلة حول كيفية تخصيص تقرير عن حالة النظام:

تخصيص AspNetCoreTraceInstrumentationOptions
builder.Services.AddOpenTelemetry().UseAzureMonitor();
builder.Services.Configure<AspNetCoreTraceInstrumentationOptions>(options =>
{
    options.RecordException = true;
    options.Filter = (httpContext) =>
    {
        // only collect telemetry about HTTP GET requests
        return HttpMethods.IsGet(httpContext.Request.Method);
    };
});
تخصيص HttpClientTraceInstrumentationOptions
builder.Services.AddOpenTelemetry().UseAzureMonitor();
builder.Services.Configure<HttpClientTraceInstrumentationOptions>(options =>
{
    options.RecordException = true;
    options.FilterHttpRequestMessage = (httpRequestMessage) =>
    {
        // only collect telemetry about HTTP GET requests
        return HttpMethods.IsGet(httpRequestMessage.Method.Method);
    };
});
تخصيص SqlClientInstrumentationOptions

نحن المورد SQLClient تقرير عن حالة النظام داخل حزمتنا في حين أنها لا تزال في بيتا. عندما يصل إلى إصدار مستقر، نقوم بتضمينه كمرجع حزمة قياسي. حتى ذلك الحين، لتخصيص تقرير عن حالة النظام SQLClient، أضف مرجع الحزمة OpenTelemetry.Instrumentation.SqlClient إلى مشروعك واستخدم واجهة برمجة التطبيقات العامة الخاصة به.

dotnet add package --prerelease OpenTelemetry.Instrumentation.SqlClient

builder.Services.AddOpenTelemetry().UseAzureMonitor().WithTracing(builder =>
{
    builder.AddSqlClientInstrumentation(options =>
    {
        options.SetDbStatementForStoredProcedure = false;
    });
});

تكوين Azure Monitor

قدمت Application Insights العديد من خيارات التكوين الأخرى عبر ApplicationInsightsServiceOptions.

إعداد Application Insights OpenTelemetry Alternative
AddAutoCollectedMetricExtractor ‏‫غير متوفر‬
إصدار التطبيق تعيين "service.version" على Resource
سلسلة الاتصال راجع إرشادات حول تكوين سلسلة الاتصال.
عمليات تجميع التبعية N/A. لتخصيص التبعيات، راجع خيارات التكوين المتوفرة لمكتبات الأجهزة القابلة للتطبيق.
DeveloperMode ‏‫غير متوفر‬
EnableActiveTelemetryConfigurationSetup ‏‫غير متوفر‬
EnableAdaptiveSampling N/A. يتم دعم أخذ العينات بمعدل ثابت فقط.
EnableAppServicesHeartbeatTelemetryModule ‏‫غير متوفر‬
EnableAuthenticationTrackingJavaScript ‏‫غير متوفر‬
EnableAzureInstanceMetadataTelemetryModule ‏‫غير متوفر‬
EnableDependencyTrackingTelemetryModule راجع إرشادات حول تصفية التتبعات.
EnableDiagnosticsTelemetryModule ‏‫غير متوفر‬
EnableEventCounterCollectionModule ‏‫غير متوفر‬
EnableHeartbeat ‏‫غير متوفر‬
EnablePerformanceCounterCollectionModule ‏‫غير متوفر‬
تمكين QuickPulseMetricStream AzureMonitorOptions.EnableLiveMetrics
EnableRequestTrackingTelemetryModule راجع إرشادات حول تصفية التتبعات.
عنوان نقطة النهاية استخدم ConnectionString.
مفتاح الأجهزة استخدم ConnectionString.
عمليات تجميع الطلبات N/A. راجع خيارات OpenTelemetry.Instrumentation.AspNetCore.

إزالة التكوينات المخصصة

السيناريوهات التالية اختيارية وتنطبق فقط على المستخدمين المتقدمين.

  • إذا كان لديك أي مراجع أخرى إلى TelemetryClient، والتي يمكن استخدامها لتسجيل بيانات تتبع الاستخدام يدويا، فيجب إزالتها.

  • إذا أضفت أي تصفية مخصصة أو إثراء في شكل مخصص TelemetryProcessor أو TelemetryInitializer، فيجب إزالتها. يمكن العثور عليها في .ServiceCollection

    builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();

    builder.Services.AddApplicationInsightsTelemetryProcessor<MyCustomTelemetryProcessor>();

  • إزالة مقتطف JavaScript

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

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

  • إزالة أي أدوات Visual Studio

    إذا استخدمت Visual Studio للإلحاق ب Application Insights، فقد يكون لديك المزيد من الملفات المتبقية في مشروعك.

    • Properties/ServiceDependencies قد يكون للدليل مرجع إلى مورد Application Insights الخاص بك.

تلميح

تسعى مجموعة منتجاتنا بنشاط للحصول على تعليقات حول هذه الوثائق. قدم ملاحظات إلى otel@microsoft.com قسم الدعم أو راجعه.

الأسئلة الشائعة

هذا القسم مخصص للعملاء الذين يستخدمون مهيئات بيانات تتبع الاستخدام أو المعالجات، أو يكتبون تعليمات برمجية مخصصة مقابل واجهة برمجة تطبيقات Application Insights الكلاسيكية لإنشاء بيانات تتبع الاستخدام المخصصة.

كيف تقوم خريطة واجهة برمجة تطبيقات SDK بمفاهيم القياس المفتوح؟

OpenTelemetry هو إطار عمل ملاحظ محايد للمورد. لا توجد واجهات برمجة تطبيقات Application Insights في OpenTelemetry SDK أو المكتبات. قبل الترحيل، من المهم فهم بعض مفاهيم OpenTelemetry.

  • في Application Insights، تمت إدارة جميع بيانات تتبع الاستخدام من خلال واحد TelemetryClient و TelemetryConfiguration. في OpenTelemetry، لكل من إشارات القياس عن بعد الثلاثة (التتبعات والمقاييس والسجلات) تكوينها الخاص. يمكنك إنشاء بيانات تتبع الاستخدام يدويا عبر وقت تشغيل .NET دون مكتبات خارجية. لمزيد من المعلومات، راجع أدلة .NET حول التتبع الموزع والمقاييس والتسجيل.

  • يستخدم TelemetryModules Application Insights لجمع القياس عن بعد تلقائيا لتطبيقك. بدلا من ذلك، يستخدم OpenTelemetry مكتبات الأجهزة لجمع بيانات تتبع الاستخدام من مكونات معينة (مثل AspNetCore للطلبات وHttpClient للتبعيات).

  • يستخدم TelemetryInitializers Application Insights لإثراء بيانات تتبع الاستخدام بمعلومات إضافية أو لتجاوز الخصائص. باستخدام OpenTelemetry، يمكنك كتابة معالج لتخصيص إشارة معينة. بالإضافة إلى ذلك، تقدم Enrich العديد من مكتبات OpenTelemetry Instrumentation طريقة لتخصيص بيانات تتبع الاستخدام التي تم إنشاؤها بواسطة هذا المكون المحدد.

  • Application Insights المستخدم TelemetryProcessors لتصفية بيانات تتبع الاستخدام. يمكن أيضا استخدام معالج القياس المفتوح لتطبيق قواعد التصفية على إشارة معينة.

كيف يتم تعيين أنواع بيانات تتبع الاستخدام ل Application Insights إلى OpenTelemetry؟

يعين هذا الجدول أنواع بيانات Application Insights إلى مفاهيم القياس المفتوح وتطبيقات .NET الخاصة بها.

جدول Azure Monitor نوع بيانات Application Insights OpenTelemetry DataType تنفيذ .NET
أحداث مخصصة EventTelemetry ‏‫غير متوفر‬ ‏‫غير متوفر‬
قياسات مخصصة القياس القياسي المقاييس System.Diagnostics.Metrics.Meter
التبعيات تتبع التبعية الامتدادات (العميل، الداخلي، المستهلك) System.Diagnostics.Activity
الاستثناءات بيانات تتبع الاستثناء استثناءات النظام.استثناء
الطلبات قياس الطلب النطاقات (الخادم، المنتج) System.Diagnostics.Activity
آثار تتبع القياس السجلات Microsoft.Extensions.Logging.ILogger

توفر المستندات التالية المزيد من المعلومات.

كيف يتم تعيين مفاهيم أخذ عينات Application Insights إلى OpenTelemetry؟

بينما قدمت Application Insights خيارات متعددة لتكوين أخذ العينات، يقدم Azure Monitor Exporter أو Azure Monitor Distro أخذ عينات بمعدل ثابت فقط. يمكن أخذ عينات فقط من الطلبات والتبعيات (تتبعات القياس المفتوح).

للحصول على نماذج التعليمات البرمجية التي توضح بالتفصيل كيفية تكوين أخذ العينات، راجع دليلنا تمكين أخذ العينات

كيف يتم تعيين معالجات القياس عن بعد والمهايئات إلى OpenTelemetry؟

في Application Insights .NET SDK، استخدم معالجات بيانات تتبع الاستخدام لتصفية بيانات تتبع الاستخدام وتعديلها أو تجاهلها. استخدم مهيئات بيانات تتبع الاستخدام لإضافة خصائص مخصصة أو تعديلها. لمزيد من المعلومات، راجع وثائق Azure Monitor. يستبدل OpenTelemetry هذه المفاهيم بمعالجات النشاط أو السجل، والتي تثري بيانات تتبع الاستخدام وتصفيتها.

تصفية التتبعات

لتصفية بيانات تتبع الاستخدام في OpenTelemetry، يمكنك تنفيذ معالج نشاط. هذا المثال يعادل مثال Application Insights لتصفية بيانات تتبع الاستخدام كما هو موضح في وثائق Azure Monitor. يوضح المثال مكان تصفية استدعاءات التبعية غير الناجحة.

using System.Diagnostics;
using OpenTelemetry;

internal sealed class SuccessfulDependencyFilterProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        if (!OKtoSend(activity))
        {
            activity.ActivityTraceFlags &= ~ActivityTraceFlags.Recorded;
        }
    }

    private bool OKtoSend(Activity activity)
    {
        return activity.Kind == ActivityKind.Client && activity.Status == ActivityStatusCode.Ok;
    }
}

لاستخدام هذا المعالج، تحتاج إلى إنشاء TracerProvider وإضافة المعالج قبل AddAzureMonitorTraceExporter.

using OpenTelemetry.Trace;

public static void Main()
{
    var tracerProvider = Sdk.CreateTracerProviderBuilder()
        .AddProcessor(new SuccessfulDependencyFilterProcessor())
        .AddAzureMonitorTraceExporter()
        .Build();
}

تصفية السجلات

تطبيقات ILogger لديها آلية مضمنة لتطبيق تصفية السجل. تتيح لك هذه التصفية التحكم في السجلات التي يتم إرسالها إلى كل موفر مسجل، بما في OpenTelemetryLoggerProviderذلك . "OpenTelemetry" هو الاسم المستعار ل OpenTelemetryLoggerProvider، المستخدم في تكوين قواعد التصفية.

يعرف المثال التالي "خطأ" على أنه الافتراضي LogLevel ويعرف أيضا "تحذير" على أنه الحد الأدنى LogLevel لفئة معرفة من قبل المستخدم. تنطبق هذه القواعد كما هو محدد فقط على OpenTelemetryLoggerProvider.

builder.AddFilter<OpenTelemetryLoggerProvider>("*", LogLevel.Error);
builder.AddFilter<OpenTelemetryLoggerProvider>("MyProduct.MyLibrary.MyClass", LogLevel.Warning);

لمزيد من المعلومات، يرجى قراءة وثائق OpenTelemetry .NET على السجلات.

إضافة خصائص مخصصة إلى عمليات التتبع

في OpenTelemetry، يمكنك استخدام معالجات النشاط لإثراء بيانات تتبع الاستخدام بمزيد من الخصائص. إنه مشابه لاستخدام مهيئات بيانات تتبع الاستخدام في Application Insights، حيث يمكنك تعديل خصائص بيانات تتبع الاستخدام.

بشكل افتراضي، يقوم مصدر Azure Monitor بوضع علامة على أي طلب HTTP مع رمز استجابة 400 أو أكبر كفشل. ومع ذلك، إذا كنت ترغب في التعامل مع 400 كنجاح، يمكنك إضافة معالج نشاط إثراء يحدد النجاح على النشاط ويضيف علامة لتضمين المزيد من خصائص القياس عن بعد. إنه مشابه لإضافة أو تعديل الخصائص باستخدام المهيئ في Application Insights كما هو موضح في وثائق Azure Monitor.

فيما يلي مثال على كيفية إضافة خصائص مخصصة وتجاوز السلوك الافتراضي لبعض رموز الاستجابة:

using System.Diagnostics;
using OpenTelemetry;

/// <summary>
/// Custom Processor that overrides the default behavior of treating response codes >= 400 as failed requests.
/// </summary>
internal class MyEnrichingProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        if (activity.Kind == ActivityKind.Server)
        {
            int responseCode = GetResponseCode(activity);

            if (responseCode >= 400 && responseCode < 500)
            {
                // If we set the Success property, the SDK won't change it
                activity.SetStatus(ActivityStatusCode.Ok);

                // Allow to filter these requests in the portal
                activity.SetTag("Overridden400s", "true");
            }

            // else leave the SDK to set the Success property
        }
    }

    private int GetResponseCode(Activity activity)
    {
        foreach (ref readonly var tag in activity.EnumerateTagObjects())
        {
            if (tag.Key == "http.response.status_code" && tag.Value is int value)
            {
                return value;
            }
        }

        return 0;
    }
}

لاستخدام هذا المعالج، تحتاج إلى إنشاء TracerProvider وإضافة المعالج قبل AddAzureMonitorTraceExporter.

using OpenTelemetry.Trace;

public static void Main()
{
    var tracerProvider = Sdk.CreateTracerProviderBuilder()
        .AddSource("Company.Product.Name")
        .AddProcessor(new MyEnrichingProcessor())
        .AddAzureMonitorTraceExporter()
        .Build();
}

كيف أعمل تتبع بيانات تتبع الاستخدام يدويا باستخدام OpenTelemetry؟

إرسال التتبعات - يدوي

يتم تخزين التتبعات في Application Insights ك RequestTelemetry و DependencyTelemetry. في OpenTelemetry، يتم تصميم التتبعات على أنها Span تستخدم Activity الفئة .

يستخدم OpenTelemetry .NET فئتي ActivitySource و Activity للتتبع، والتي تعد جزءا من وقت تشغيل .NET. هذا النهج مميز لأن تنفيذ .NET يدمج واجهة برمجة تطبيقات التتبع مباشرة في وقت التشغيل نفسه. System.Diagnostics.DiagnosticSource تسمح الحزمة للمطورين باستخدام ActivitySource لإنشاء المثيلات وإدارتهاActivity. يوفر هذا الأسلوب طريقة سلسة لإضافة التتبع إلى تطبيقات .NET دون الاعتماد على المكتبات الخارجية، وتطبيق القدرات المضمنة للنظام البنائي .NET. لمزيد من المعلومات التفصيلية ، راجع إرشادات أدوات التتبع الموزعة.

فيما يلي كيفية ترحيل التتبع اليدوي:

إشعار

في Application Insights، يمكن تعيين اسم الدور ومثيل الدور على مستوى القياس عن بعد. ومع ذلك، مع مصدر Azure Monitor، لا يمكننا التخصيص على مستوى بيانات تتبع الاستخدام. يتم استخراج اسم الدور ومثيل الدور من مورد OpenTelemetry وتطبيقهما عبر جميع بيانات تتبع الاستخدام. يرجى قراءة هذا المستند لمزيد من المعلومات: تعيين اسم دور السحابة ومثيل دور السحابة.

تتبع التبعية

يتم استخدام Application Insights DependencyTelemetry لنمذجة الطلبات الصادرة. فيما يلي كيفية تحويله إلى OpenTelemetry:

مثال Application Insights:

DependencyTelemetry dep = new DependencyTelemetry
{
   Name = "DependencyName",
   Data = "https://www.example.com/",
   Type = "Http",
   Target = "www.example.com",
   Duration = TimeSpan.FromSeconds(10),
   ResultCode = "500",
   Success = false
};

dep.Context.Cloud.RoleName = "MyRole";
dep.Context.Cloud.RoleInstance = "MyRoleInstance";
dep.Properties["customprop1"] = "custom value1";
client.TrackDependency(dep);

مثال على OpenTelemetry:

var activitySource = new ActivitySource("Company.Product.Name");
var resourceAttributes = new Dictionary<string, object>
{
   { "service.name", "MyRole" },
   { "service.instance.id", "MyRoleInstance" }
};

var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
  .SetResourceBuilder(resourceBuilder)
  .AddSource(activitySource.Name)
  .AddAzureMonitorTraceExporter()
  .Build();

// Emit traces
using (var activity = activitySource.StartActivity("DependencyName", ActivityKind.Client))
{
  activity?.SetTag("url.full", "https://www.example.com/");
  activity?.SetTag("server.address", "www.example.com");
  activity?.SetTag("http.request.method", "GET");
  activity?.SetTag("http.response.status_code", "500");
  activity?.SetTag("customprop1", "custom value1");
  activity?.SetStatus(ActivityStatusCode.Error);
  activity?.SetEndTime(activity.StartTimeUtc.AddSeconds(10));
}

قياس الطلب

نماذج Application Insights RequestTelemetry الطلبات الواردة. فيما يلي كيفية ترحيله إلى OpenTelemetry:

مثال Application Insights:

RequestTelemetry req = new RequestTelemetry
{
   Name = "RequestName",
   Url = new Uri("http://example.com"),
   Duration = TimeSpan.FromSeconds(10),
   ResponseCode = "200",
   Success = true,
   Properties = { ["customprop1"] = "custom value1" }
};

req.Context.Cloud.RoleName = "MyRole";
req.Context.Cloud.RoleInstance = "MyRoleInstance";
client.TrackRequest(req);

مثال على OpenTelemetry:

var activitySource = new ActivitySource("Company.Product.Name");
var resourceAttributes = new Dictionary<string, object>
{
   { "service.name", "MyRole" },
   { "service.instance.id", "MyRoleInstance" }
};

var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
  .SetResourceBuilder(resourceBuilder)
  .AddSource(activitySource.Name)
  .AddAzureMonitorTraceExporter()
  .Build();

// Emit traces
using (var activity = activitySource.StartActivity("RequestName", ActivityKind.Server))
{
  activity?.SetTag("url.scheme", "https");
  activity?.SetTag("server.address", "www.example.com");
  activity?.SetTag("url.path", "/");
  activity?.SetTag("http.response.status_code", "200");
  activity?.SetTag("customprop1", "custom value1");
  activity?.SetStatus(ActivityStatusCode.Ok);
}

تعقب العمليات المخصصة

في Application Insights، تعقب العمليات المخصصة باستخدام StartOperation وأساليب StopOperation . تحقيق ذلك باستخدام ActivitySource و Activity في OpenTelemetry .NET. بالنسبة للعمليات مع ActivityKind.Server و ActivityKind.Consumer، يقوم Azure Monitor Exporter بإنشاء RequestTelemetry. بالنسبة إلى ActivityKind.Clientو ActivityKind.Producerو ActivityKind.Internal، فإنه ينشئ DependencyTelemetry. لمزيد من المعلومات حول تعقب العمليات المخصصة، راجع وثائق Azure Monitor. لمزيد من التفاصيل حول استخدام ActivitySource و Activity في .NET، راجع الإرشادات التفصيلية لأدوات التتبع الموزعة .NET.

فيما يلي مثال على كيفية بدء نشاط وإيقافه للعمليات المخصصة:

using System.Diagnostics;
using OpenTelemetry;

var activitySource = new ActivitySource("Company.Product.Name");

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource(activitySource.Name)
    .AddAzureMonitorTraceExporter()
    .Build();

// Start a new activity
using (var activity = activitySource.StartActivity("CustomOperation", ActivityKind.Server))
{
    activity?.SetTag("customTag", "customValue");

    // Perform your custom operation logic here

    // No need to explicitly call Activity.Stop() because the using block automatically disposes the Activity object, which stops it.
}

إرسال السجلات

يتم تخزين السجلات في Application Insights ك TraceTelemetry و ExceptionTelemetry.

تتبع القياس

في OpenTelemetry، يتم دمج التسجيل عبر الواجهة ILogger . فيما يلي كيفية الترحيل TraceTelemetry:

مثال Application Insights:

TraceTelemetry traceTelemetry = new TraceTelemetry
{
   Message = "hello from tomato 2.99",
   SeverityLevel = SeverityLevel.Warning,
};

traceTelemetry.Context.Cloud.RoleName = "MyRole";
traceTelemetry.Context.Cloud.RoleInstance = "MyRoleInstance";
client.TrackTrace(traceTelemetry);

مثال على OpenTelemetry:

var resourceAttributes = new Dictionary<string, object>
{
   { "service.name", "MyRole" },
   { "service.instance.id", "MyRoleInstance" }
};

var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);

using var loggerFactory = LoggerFactory.Create(builder => builder
   .AddOpenTelemetry(logging =>
   {
       logging.SetResourceBuilder(resourceBuilder);
       logging.AddAzureMonitorLogExporter();
   }));

// Create a new instance `ILogger` from the above LoggerFactory
var logger = loggerFactory.CreateLogger<Program>();

// Use the logger instance to write a new log
logger.FoodPrice("tomato", 2.99);

internal static partial class LoggerExtensions
{
    [LoggerMessage(LogLevel.Warning, "Hello from `{name}` `{price}`.")]
    public static partial void FoodPrice(this ILogger logger, string name, double price);
}
بيانات تتبع الاستثناء

يستخدم ExceptionTelemetry Application Insights لتسجيل الاستثناءات. فيما يلي كيفية الترحيل إلى OpenTelemetry:

مثال Application Insights:

ExceptionTelemetry exceptionTelemetry = new ExceptionTelemetry(new Exception("Test exception"))
{
    SeverityLevel = SeverityLevel.Error
};

exceptionTelemetry.Context.Cloud.RoleName = "MyRole";
exceptionTelemetry.Context.Cloud.RoleInstance = "MyRoleInstance";
exceptionTelemetry.Properties["customprop1"] = "custom value1";
client.TrackException(exceptionTelemetry);

مثال على OpenTelemetry:

var resourceAttributes = new Dictionary<string, object>
{
   { "service.name", "MyRole" },
   { "service.instance.id", "MyRoleInstance" }
};

var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);

using var loggerFactory = LoggerFactory.Create(builder => builder
   .AddOpenTelemetry(logging =>
   {
       logging.SetResourceBuilder(resourceBuilder);
       logging.AddAzureMonitorLogExporter();
   }));

// Create a new instance `ILogger` from the above LoggerFactory.
var logger = loggerFactory.CreateLogger<Program>();

try
{
    // Simulate exception
    throw new Exception("Test exception");
}
catch (Exception ex)
{
    logger?.LogError(ex, "An error occurred");
}

إرسال المقاييس

يتم تخزين المقاييس في Application Insights ك MetricTelemetry. في OpenTelemetry، يتم تصميم المقاييس كما هو الحال Meter من الحزمة System.Diagnostics.DiagnosticSource .

يحتوي Application Insights على كل من واجهات برمجة التطبيقات القياسية غير التجميع المسبق (TrackMetric()) والتجميع المسبق (GetMetric().TrackValue()). على عكس OpenTelemetry، لا يحتوي Application Insights على فكرة عن الأدوات. يحتوي Application Insights على نفس واجهة برمجة التطبيقات لجميع سيناريوهات القياس.

من ناحية أخرى، يتطلب OpenTelemetry من المستخدمين اختيار أداة القياس الصحيحة أولا استنادا إلى الدلالات الفعلية للمقياس. على سبيل المثال، إذا كانت النية هي حساب شيء ما (مثل عدد إجمالي طلبات الخادم المستلمة، وما إلى ذلك)، يجب استخدام OpenTelemetry Counter . إذا كانت النية هي حساب النسب المئوية المختلفة (مثل قيمة P99 لزمن انتقال الخادم)، فيجب استخدام أداة المدرج التكراري OpenTelemetry. نظرا لهذا الاختلاف الأساسي بين Application Insights وOpenTelemetry، لا يتم إجراء مقارنة مباشرة بينهما.

على عكس Application Insights، لا يوفر OpenTelemetry آليات مضمنة لإثراء المقاييس أو تصفيتها. في Application Insights، يمكن استخدام معالجات القياس عن بعد والمهايئات لتعديل المقاييس أو تجاهلها، ولكن هذه الإمكانية غير متوفرة في OpenTelemetry.

بالإضافة إلى ذلك، لا يدعم OpenTelemetry إرسال المقاييس الأولية مباشرة، حيث لا يوجد ما يعادل TrackMetric() الوظائف الموجودة في Application Insights.

يتضمن الترحيل من Application Insights إلى OpenTelemetry استبدال جميع استخدامات Application Insights Metric API بواجهة برمجة تطبيقات OpenTelemetry. يتطلب فهم أدوات القياس المفتوح المختلفة ودلالاتها.

تلميح

المدرج التكراري هو الأكثر تنوعا وأقرب مكافئ لواجهة برمجة تطبيقات Application Insights GetMetric().TrackValue() . يمكنك استبدال Application Insights Metric APIs بم مدرج تكراري لتحقيق نفس الغرض.

أنواع بيانات تتبع الاستخدام الأخرى

أحداث مخصصة

غير معتمد في OpenTelemetry.

مثال Application Insights:

TelemetryClient.TrackEvent()
AvailabilityTelemetry

غير معتمد في OpenTelemetry.

مثال Application Insights:

TelemetryClient.TrackAvailability()
PageViewTelemetry

غير معتمد في OpenTelemetry.

مثال Application Insights:

TelemetryClient.TrackPageView()

هل يمكنني الحصول على مقاييس مباشرة لتطبيقات وحدة التحكم وخدمة العامل؟

نوصي Azure Monitor OpenTelemetry Exporter لوحدة التحكم وتطبيقات خدمة العامل، والتي لا تتضمن مقاييس مباشرة.

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

تلميح

تسعى مجموعة منتجاتنا بنشاط للحصول على تعليقات حول هذه الوثائق. قدم ملاحظات إلى otel@microsoft.com قسم الدعم أو راجعه.

يدعم

  • بالنسبة إلى مشكلات دعم Azure، افتح تذكرة دعم Azure.
  • بالنسبة إلى مشكلات القياس عن بُعد المفتوح، اتصل بمجتمع القياس عن بُعد المفتوح مباشرة.
  • للحصول على قائمة بالمشكلات المفتوحة المتعلقة بمصدر Azure Monitor، راجع صفحة مشكلات GitHub.