.NET Tracking SDK

التتبع مع Intreass هو آلي ولكن اذا كنت تريد رؤية أكثر في كود مهيأ ، أو مساحة تطبيق محددة أو بعض المكونات الداخلية ، يمكنك استخدام .NET Tracking SDK الخاص به كما هو مفصل بأسفل.

تركيب SDK

سنقدم SDK الى .NET كمجموعة برامج نووية على وحدة المعلومات المسترجعة الرسمية لموقع nuget.org. برجاء البحث عنInstana.ManagedTracing.Sdkلايجاده واضافته الى المشروع الخاص بك. بعد التركيب ، سيحتوي المشروع الخاص بك على اثنين من المراجع الاضافية (Instana.ManagedTracing.SdkوInstana.ManagedTracing.Api)

تتبع الكود الخاص بك

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

ملحوظة : SDK يتم تحت التطوير الفعال ، لذلك تأكد من اعادة النظر في هذه الصفحة عند التعديل للتأكد من استخدام أحدث استخدام APIs.

تكوين امتداد بسيط

تعد أبسط طريقة لتتبع طريقة استدعاء الطريقة هي استخدامCustomSpan.Create(آبي)

public void MyTracedMethod()
{
    using(var span = CustomSpan.Create())
    {
        // your original code here
    }
}

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

اذا كان بدلا من استخدام وسيط تريد تكوين ادخال أو امتداد له ، فان هناك sIPA ملائمة لذلك (تم استدعاؤهCustomSpan.CreateEntryوCustomSpan.CreateExitعلى التوالي).

تكوين امتداد بسيط واستثناء التقاط

في حالة أنك ترغب في توضيح spanspans التي تم تكوينها بأي أخطاء تحدث أثناء تشغيل نص الطريقة ، يمكنك بالطبع القيام بذلك يدويا ، باستخدامCustomSpan.SetErrorAPI مثل هذا.

public void MyTracedMethod()
{
    using(var span = CustomSpan.Create())
    {
        try
        {
        // your original code here
        }
        catch(Exception e)
        {
            span.SetError(e);
        }
    }
}

نهج أسهل-ومفضل-هو استخدامCustomSpan.WrapActionأوCustomSpan.Wrap<T>APIs بدلا من ذلك.

public void MyTracedMethod()
{
    using(var span = CustomSpan.Create())
    {
        // setting the second argument to "false" will prevent exceptions from being thrown. Instead they will be
        // captured in the span and swallowed. Setting it to true will let you handle exceptions yourself.
        span.WrapAction(
            ()=>{
                // your original code here
            }, true);
    }
}

اذا كانت مجموعة الكود التي تريد التفافها تقوم بارجاع شيء تحتاج اليه لمزيد من التشغيل ، قم باستخدامCustomSpan.Wrap<T>API بدلا من ذلك.

public void MyTracedMethod()
{
    using(var span = CustomSpan.Create())
    {
        // setting the second argument to "false" will prevent exceptions from being thrown. Instead they will be
        // captured in the span and swallowed. Setting it to true will let you handle exceptions yourself.
        bool result = span.Wrap<bool>(
            ()=>{
                // your original code here
                return myBooleanValue;
            }, true);
    }
}

لذا فإننا نعرف الآن كيف نخلق مداخل ، مخارج ومواد وسيطة. وقد تعلمنا أيضا كيفية الحصول على الاستثناءات باستخدام أي منSetErrorأوWrapAction/Wrap<T>APIs.

اضافة بيانات الى spans الخاصة بك

امتداد بحد ذاته يتكون فقط من توقيت ، وككومة واسم. ذلك جيد ، لكن ليس مفيد جدا في أغلب السيناريوهات. لذا ماذا عن إضافة بعض البيانات إلى امتدادك ؟ يمكن أن يحتوي الامتداد علىDataوTagsالذي تم بالنسبة لهCustomSpanتقوم الفئة بعرض APIs البسيطة.

public void MyTracedMethod(string userName, string someSuperRelevantData)
{
    using(var span = CustomSpan.Create())
    {
        span.SetData("username", userName);
        span.SetData("relevant", someSuperRelevantData);
        span.WrapAction(
            ()=>{
                // your original code here
            }, true);
    }
}

يتم نقل البيانات الى النهاية الخلفية ويمكن تحميلها من واجهة تعامل المستخدم من خلال تحميل التتبع. ولكن ، البيانات التي تم وضعها هنا لا يتم عرضها في واجهة تعامل المستخدم.

اضافة شارات تعليم الى spans الخاصة بك

بدلا من استخدامSetDataيمكنك أيضا استخدامSetTag، التي تأخذ مصفوفة من مجموعات الحروف باعتبارها المفتاح (الذي يمكن استخدامه لتنظيم البيانات التي تقوم بتمريرها الى الامتداد كتسلسل هرمي).

public void MyTracedMethod(string userName, string someSuperRelevantData)
{
    using(var span = CustomSpan.Create())
    {
        span.SetTag("username", userName);
        span.SetTag("relevant", someSuperRelevantData);
        span.WrapAction(
            ()=>{
                // your original code here
            }, true);
    }
}

سيتم عرض شارات التعليم في مشاهدة تفاصيل الاتصال مباشرة ويمكن البحث عنها أيضا في تحليلات لا يتم تحديدها.

مناظرة spans المهيأة الخاصة بك الى خدمة

عادة ما تريد ارفاق spans المهيأة الخاصة بك مع خدمة منطقية في تطبيق Incass's application-speالمشاهدات. هذا سهل الاتصال بهSetServicenameAPI ، الذي يقوم ببساطة بأخذ مجموعة حروف. للتمييز بين نقاط النهاية التي يتم تنفيذها باستخدام SDK ، يمكنك أيضا اتاحة نقطة نهاية لمناظرة أكثر تفصيلا معSetEndpointName(آبي)

public void MyTracedMethod(string userName, string someSuperRelevantData)
{
    using(var span = CustomSpan.Create())
    {
        span.SetServiceName("AwesomeSDKService");
        span.SetEndpointName("TracingEndpoint");
        .
        .
        .
    }
}

بينما يمكنك تحديد خدمة ونقطة نهاية على كل امتداد ، فمن المهم ملاحظة أن هذه المحددات سيتم استبعادها في حالةINTERMEDIATEspan (سيتم توارثها من آخر عملية تم الحصول عليهاENTRY)

التقاط نتيجة الفترة الزمنية الخاصة بك

لنقل الطريقة التي تقوم باستخدامها بارجاع قيمة. لنفترض أن وجود هذه القيمة في التتبع الخاص بك سيكون مفيدا لتصحيح الأخطاء. أدخلSetResultapi.

public bool MyTracedMethod(string userName, string someSuperRelevantData)
{
    using(var span = CustomSpan.Create())
    {
        bool result = span.Wrap<bool>(
            ()=>{
                // your original code here
                return resultingBoolean;
            }, true);

        span.SetResult(result.ToString());
        return result;
    }
}

تسربات البانعات

إن تداخل spans هو بنفس السهولة التي يتم بها استدعاء طريقة واحدة من أخرى. للتأكد من الكمال ، هنا هو مثال. ونحن نفترض أن أحد الطرق يعمل كمدخل ، في حين أن عمر الطفل هو وسيط متوسط.

public bool MyTracedEntryMethod(string userName, string someSuperRelevantData)
{
    using(var span = CustomSpan.CreateEntry())
    {
        bool result = span.Wrap<bool>(
            ()=>{
                List<string> data = this.GetSomeDataFromSomewhere();
                // do some heavy processing
                return theResultICameUpWith;
            }, true);

        span.SetResult(result.ToString());
        return result;
    }
}


private List<string> GetSomeDataFromSomewhere()
{
    using(var span = CustomSpan.Create())
    {
        List<string> result = span.WrapAction(
            ()=>{
                // read data from somewhere...
                return theListICameUpWith;
            }, true);

        span.SetResult(result.ToString());
        return result;
    }
}

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

النظر فيdistributedفي التتبع الموزع

كل spans التي كنا ننظر إليها حتى الآن كانت تقتصر على خدمة واحدة. ولم تصل قط إلى عنصر آخر ، وهو ما من شأنه أيضا أن يتتبع نشاطها. لتحقيق تتبع توزيع صحيح عبر حدود الخدمة ، تحتاج الى تطبيق بعض الارتباط.

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

لتحقيق ذلك ، فان CustomSpan لديه حمولة زائدة منCustomSpan.CreateExitوCustomSpan.CreateEntryالطرق.

أثناءCustomSpan.CreateExitيمكن أن يستهلكAction<string, string>كحجةCustomSpan.CreateEntryسيأخذFunc<DistributedTraceInformation>.

لذا كيف يعمل ذلك ؟

افترض ان لدينا صغيرMessageالصف ، الذي نمر به إلى الخدمة البعيدة التي نحن ندعو.

    public class Message
    {
        public Message()
        {
            this.Tags = new Dictionary<string, string>();
        }
        public Dictionary<string, string> Tags { get; private set; }
        public int Payload { get; set; }

        public void AddTag(string tagName, string tagValue)
        {
            this.Tags.Add(tagName, tagValue);
        }
    }

الجزء ذو الصلة هنا هوAddTagالطريقة ، التي تأخذ اثنين من مجموعات الحروف. هذا هو التوقيع الذي نحن بحاجة لتوفيرهCustomSpan.CreateExit.

استخدام هذه الطريقة عند الاتصالCreateExitسيتم كتابة بيانات الارتباط الى النسخة الخاصة بنا منMessage.

public void MyLocalEntryMethod()
{
    // this methd will create an entry span and then call our method
    // that communicates with the remote-service (and thus create our exit span)
    using(var span = CustomSpan.CreateEntry())
    {
        span.WrapAction(()=>{
            CallRemoteService();
        })
    }
}

public void CallRemoteService()
{
    Message message = new Message();
    using(var exitSpan = CustomSpan.CreateExit(this, message.AddTag))
    {
        exitSpan.WrapAction( ()=>{
            var service = new RemoteService();
            service.ValidateRequest(message);
        }
    }
}

لذلك عندما تترك رسالتنا نطاق المكون المحلي الخاص بنا مع مكالمة الىservice.ValidateRequest(message)، انه يحمل بيانات الارتباط في كشف شارات التعليم الخاص به. لنرى كيف سيتم إستخراجها من موقع (كالي)

public void ValidateRequest(Message message)
{
    using(var span = CustomSpan.CreateEntry(this, ()=>ExtractCorrelationData(message))
    {
        // do whatever this method is supposed to do, we only care for extraction
        // if the correlation-data anyway :-)
    }
}

private DistributedTraceInformation ExtractCorrelationData(Message message)
{
    var dti = new DistributedTraceInformation();
    dti.ParentSpanId = Convert.ToInt64(message.Tags[TracingConstants.ExternalParentSpanIdHeader], 16);
    dti.TraceId = Convert.ToInt64(message.Tags[TracingConstants.ExternalTraceIdHeader], 16);
    return dti;
}

الجزء ذو الصلة هناExtractCorrelationData. منذ أن استخدمناMessage.AddTagالطريقة الخاصة بتكوين الخروج ، SDK تقوم بكتابة الكود ذو الصلة (هوية-امتداد-أصل وهوية-تتبع) الى كشف شارات التعليم الخاص بالرسالة قبل ارسالها الى الخدمة.

الآن يمكن للخدمة أن تقوم باستخراج هذه القيم مرة أخرى عن طريق قراءة شارات التعليم (يمكننا تعريفهم بواسطة الثوابت التي يتم استخدامها كمفاتيح في الكود السابق). نسخة منDistributedTraceInformationسيتم استخدامه بواسطة SDK للحاق المخرج الذي تم تكوينه حديثا الى التتبع الموجود بالفعل. وبذلك يكون مدى الادخال الذي نقوم بتكوينه هو نظير الخروج على الخدمة المحلية.

تقسيم تتبعات

توجد أمثلة عندما يقوم التتبع الآلي بالكثير ، ويكون التتبع الذي يتم تكوينه طويل للغاية بحيث لا يمكن فهمه. على سبيل المثال ، يمكن أن يحدث هذا في اتصالات WCF المزدوجة الطويلة عند قيام وحدة الخدمة بدفع التعديلات للوحدات التابعة من خلال callback على التقدم الذي تم تنفيذه لمهمة خلفية طويلة الأجل. هذا النوع من الاتصالات سينتج عنه تتبع طويل يمكن أن يكون أطول من اللازم ليتم عرضه في UI.

في مثل هذه الحالات ، يوجد اختيار لتقسيم التتبع الى العديد من عمليات التتبع ، بشكل أكثر تحديدا ، لفصل كل من عمليات الاتصال الخاصة بالوحدة التابعة في عملية تتبع منفصلة. للقيام بذلك ، يمكنك استخدامCreateEntryForNewTraceمنCustomSpanلايقاف عملية التتبع الحالية ولتكوين واحدة جديدة من هذه النقطة. قد ترغب في القيام بذلك على جانب وحدة الخدمة ، قبل الاتصال بالوحدة التابعة :

var callbackChanell = OperationContext.Current.GetCallbackChannel<IMathResult>();
if (callbackChanell != null)
{
    using (var span = CustomSpan.CreateEntryForNewTrace(this))
    {
        callbackChanell.SendStatusUpdate(new MathArguments() { InParam = args.InParam, Progress = (float)i / args.InParam, Result = generator.Next(1000, 9999) });
    }
}

حصلت عليه ؟

وبحلول الآن ، يجب أن تكون قادرا على تكوين أول تتبع مهيأة باستخدام SDK الخاص بك. إذا كان لديك أي أسئلة (أو رغبات !) فيما يتعلق ب SDK ، يمكنك الحصول على حرية الاتصال بنا من خلال دعم. ! تعقب سعيد