Android Monitoring API

• Indasa Android agent API
  • الاعداد
    • معاملات
  • مواصفات حالية
  • كود تعريف الجلسة
    • مثال
  • مراقبة آلية HTTP
  • مراقبة HTTP يدويا
    • بدء التقاط
      • معاملات
    • انهاء عملية الالتقاط
    • الغاء التقاط
    • أمثلة
  • المشاهدات
    • مثال
  • تعريف المستخدمين
    • مثال
  • بيانات Meta
    • خصائص
    • مثال
  • استبعاد عناوين URL من المراقبة
    • مثال
  • تسجيل الأحداث المهيأة
    • معاملات
    • أمثلة
  • خدمات جوجل للعب
    • مثال
  • واجهة التسجيل
    • معاملات
    • مثال
  • مستويات التسجيل
    • مثال
  • اتاحة / الغاء اتاحة تجميع البيانات
    • مثال
  • اعادة ادخال معاملات استعلام URL
    • مثال
  • التقاط نصوص رأس HTTP
    • مثال

Intasa Android agent API

ويصف الفرع التالي استخدام وكيل Antana Android agent. ويمكن استخدام أداة أندرويد للأندرويد من خلالInstanaطرق الفئة الموضحة بأسفل.

اعداد

نحن نوصي ببدء الفاعلية فيكApplicationفئة 'onCreate()، بعدsuper.onCreate():

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Instana.setup(
            this,
            InstanaConfig(
                key = "YOUR_APP_KEY",
                reportingURL = "YOUR_REPORTING_URL"
            )
        )
    }
}

معاملات

توصيف الحالي

للتحقق من توصيف Incastana الحالي ، قم ببساطة بالتوصل الىInstanaConfigالنسخة:

val currentConfig = Instana.config

كود تعريف جلسة

يكون لكل نسخة من نسخ Intance Agent كود تعريف جلسة متفرد يمكنك استخدامه لأغراض أخرى في التطبيق الخاص بك.

مثال

val sessionId = Instana.sessionId

مراقبة Automatic HTTP

افتراضيا ، سيتم التقاط جلسات HTTP آليا. عند بدء تشغيل Intarid (بعد تركيب Intana Andrid Plugin و InCasin Android SDK) ، سيقوم Agent برعاية البقية.

وسيقوم وكيل Intaria Android بتكوين الكود آليا لاتاحة مراقبة طلبات HTTP للوحدات التابعة التي يتم دعمها :

• OkHttp3
• وصلة HttpURLConnection
• telitaR

يمكن الغاء اتاحة المراقبة الآلية HTTP لصالح مراقبة HTTP يدويا ، كما هو موضح في القسم التالي.

مراقبة Manual HTTP

بدء التقاط

تقوم هذه الوظيفة بارجاعHTTPMarkerوالذي ستحتاج اليه لاحقا عندما يتم استكمال الطلب.

Instana {
    fun startCapture(url: String, viewName: String? = view, requestHeaders: Map<String,String>?): HTTPMarker?
}

معاملات

لارجاع : HTTP المميز لتحديد حجم الاستجابة ، قم باستدعاء حالة الانهاء أو الخطأ عندما يتم استكمال الطلب.

انهاء عملية التقاط

بمجرد اتمام الطلب ، يجب أن تقوم بالاتصالfinishبالرد علىHTTPMarkerواختياريةError:

HTTPMarker {
    fun finish(response: okhttp3.Response)
    fun finish(request: okhttp3.Request, error: Throwable)
    fun finish(connection: java.net.HttpURLConnection)
    fun finish(connection: java.net.HttpURLConnection, error: Throwable)
    fun finish(data: com.instana.android.instrumentation.HTTPMarkerData)
}

الغاء التقاط

قم باستدعاء هذه الطريقة فيHTTPMarkerاذا كان قد تم الغاء الطلب قبل الاتمام.

fun cancel()

أمثلة

val request = yourMethodToCreateRequest()
val marker = Instana.startCapture(request.url().toString(), viewName: "User Details")
val response = OkHttpClient().newCall(request).execute()
marker?.finish(response)

val marker = Instana.startCapture("https://example.com/user", viewName: "User Details")
// Complete request and manually obtain any relevant information
val httpMarkerData = HTTPMarkerData(
            requestMethod = "GET",
            responseStatusCode = 200,
            responseSizeEncodedBytes = 200,
            responseSizeDecodedBytes = 1000
        )
marker?.finish(httpMarkerData)

HTTPMarker marker = Instana.startCapture("https://example.com/user", "User Details");
// Complete request and manually obtain any relevant information
HTTPMarkerData data = new HTTPMarkerData.Builder()
        .requestMethod("GET")
        .responseStatusCode(200)
        .responseSizeEncodedBytes(200)
        .responseSizeDecodedBytes(1000)
        .build();
marker.finish(data);

مشاهدات

يمكن أن مقطع لمقاطع متنقل لتطبيق مشاهدات منطقية. للقيام بذلك ، حدد اسم المشاهدة من خلالInstana.setView(String)الطريقة. سيتم بعد ذلك ارفاق المشاهدة مع كل beacons المراقبة حتى يتم تغيير المشاهدة مرة واحدةsetViewيتم استدعائه مرة أخرى.

ونحن نوصي بعدم استخدام أسماء تقنية أو عامة مثل الفئة Class (على سبيل المثال ،WebViewActivity) لتعريف المشاهدات. ونحن نوصي باستخدام الأسماء التي يمكن قراءتها في المشاهدات ، على سبيل المثالproduct detail pageأوpayment selectionوبالتركيز على ما سيكون عليه المستخدمون ، فإنهم سيسمحون لأعضاء الفريق دون معرفة متعمقة بهذه المادة بفهم الأفكار المقدمة.

مذكرة:Instana.setView(String)يجب أن يتم استدعائه عندما يتم عرض شاشة على المستخدم ، بدلا من عند تكوين شاشة (كما في المقطع الذي يمكن تكوينه مرة واحدة ولكن يتم عرضه عدة مرات). تحديد اسم المشاهدة سيمكن أيضا من تتبع مسار انتقالات الصفحة بالاضافة الى تحميل الصفحة.

مثال

class WebViewActivity : AppCompatActivity() {

    override fun onResume() {
        super.onResume()
        Instana.view = "Webview: FitBit authorization"
    }
}

تعريف المستخدمين

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

• حساب عدد المستخدمين المتأثرين بالأخطاء ،
• لترشيح بيانات لمستخدمين محددين و
• لمشاهدة المستخدم الذي قام ببدء تغيير المشاهدة أو طلب HTTP.

افتراضيا ، لن تقوم شركة Incass بارفاق أي معلومات يمكن تعريفها بواسطة المستخدم لبرنامج beacons. ويرجى الانتباه إلى القوانين المعنية بحماية البيانات عند اختيارها للقيام بذلك. ونوصي عموما بتحديد هوية المستخدمين عن طريق هوية مستخدم. للاستانة هذا شفاف كلياStringيتم استخدام ذلك فقط لحساب مقاييس معينة.userNameوuserEmailيمكن أيضا استخدامها للحصول على المزيد من مرشحات البيانات والعرض الأكثر لطافة لمعلومات المستخدم.

في الحالات التي تقوم فيها بالتعامل مع المستخدمين غير المعروفين وبذلك لا يتوافر لديك امكانية توصل لهويات المستخدمين ، يمكنك استخدام أكواد الجلسة. هويات الجلسة ليست مفيدة كأكواد المستخدمين عند ترشيح البيانات ولكنها تعد مؤشرا جيدا لحساب قياسات المستخدم المتأثر / الفريد. نحن ننصح بتحديد اسم مستخدم مثلAnonymousأن يكون هناك تمييز واضح بين المستخدمين الموثقين وغير الموثقين. يمكن أن تكون أكواد الجلسة بيانات حساسة (طبقا لاطار العمل / بيئة التشغيل المستخدمة). برجاء التفكير في hashing أكواد الجلسة لتجنب ارسال البيانات الى Intana التي يمكنها منح امكانية التوصل.

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

Instana {
    void setUserId(@Nullable String)
    @Nullable String getUserId()
    void setUserName(@Nullable String)
    @Nullable String getUserName()
    void setUserEmail(@Nullable String)
    @Nullable String getUserEmail()
}

مثال

class MyApp : Application() {

    override fun onCreate() {
        super.onCreate()
        Instana.setup(
            this,
            InstanaConfig(
                key = BuildConfig.INSTANA_KEY,
                reportingURL = BuildConfig.INSTANA_REPORTING_URL
            )
        )
        Instana.userId = "1234567890"
        Instana.userEmail = "instana@example.com"
        Instana.userName = "instana android agent demo"
    }
}

بيانات Meta

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

ملاحظة : نحن حاليا ندعم ما يصل إلى 50 زوجا من المجالات الرئيسية / القيمة.

Instana {
     val meta = MaxCapacityMap<String, String>(50)
}

خصائص

مثال

class UserProfileActivity : AppCompatActivity() {

    override fun onResume() {
        super.onResume()
        Instana.meta.put("user authenticated", "true")
        Instana.meta.put("user type", "editor")
    }
}

استبعاد عناوين URL من المراقبة

يمكن تجاهل عناوين URL من خلال اتاحة التعبيرات المعتادة ، من خلال اضافتها الىignoreURLsقائمة. قد يكون هناك سيناريو جيد لاستخدام هذه الوظيفة لتجاهل كل طلبات HTTP التي تحتوي على أي بيانات حساسة مثل كلمة السرية.

سيتم تجاهل عناوين URL التي يتم مراقبتها آليا فقط. لن يتم تجاهل عناوين URL المراقبة يدويا.

Instana {
    val ignoreURLs = mutableListOf<Regex>()
}

Instana {
    List<Pattern> getIgnoreURLs()
}

مثال

class MyApp : Application() {

    override fun onCreate() {
        super.onCreate()
        Instana.setup(
            this,
            InstanaConfig(
                key = BuildConfig.INSTANA_KEY,
                reportingURL = BuildConfig.INSTANA_REPORTING_URL
            )
        )
        Instana.ignoreURLs.add("/.*([&?])password=.*/i".toRegex())
    }
}

سيقوم المثال بتجاهل كل عناوين URL التي تحتوي على كلمة سرية في الاستعلام.

الأحداث المهيأة لتقرير

تتيح الأحداث المهيأة التقارير عن الأنشطة غير القياسية والمعاملات الهامة والتوقيت المهيأ الى Incastis-Incasens-Incatsانه. وهذا يمكن أن يكون مفيدا بصفة خاصة عند تحليل الأخطاء التي لم يتم اكتشافها (breadcrumbs) ولتتبع مقاييس الأداء الاضافية.

Instana {
    fun reportEvent(event: CustomEvent)
}

Intastana-اتاحةCustomEventيسمح لك بتحديد معاملات متعددة ،eventName(في وحدة التكوين الخاصة به) كونه هو الزامي الوحيد.

معاملات

أمثلة

val myEvent = CustomEvent("MyCustomEvent").apply {
    duration = 300
    meta = mapOf("keyOne" to "valueOne", "keyTwo" to "valueTwo")
    backendTracingID = "1234567890"
}

Instana.reportEvent(myEvent)

Map<String,String> myMetas = new HashMap<>();
myMetas.put("keyOne", "valueOne");
myMetas.put("keyTwo", "valueTwo");

CustomEvent myEvent = new CustomEvent("MyCustomEvent");
myEvent.setDuration(300L, TimeUnit.MILLISECONDS);
myEvent.setMeta(myMetas);
myEvent.setBackendTracingID("1234567890");

Instana.reportEvent(myEvent);

خدمات تشغيل Google

يمكنك معرفة ما اذا كانت Google Play Services متاحة لمستخدم وجلسة محددة بوضوح.

Instana {
    val googlePlayServicesMissing: Boolean?
}

مثال

class MyApp : Application() {

    override fun onCreate() {
        super.onCreate()
        Instana.setup(
            this,
            InstanaConfig(
                key = BuildConfig.INSTANA_KEY,
                reportingURL = BuildConfig.INSTANA_REPORTING_URL
            )
        )
        Instana.googlePlayServicesMissing = GoogleApiAvailability.getInstance().isGooglePlayServicesAvailable(this) != ConnectionResult.SUCCESS
    }
}

//app/build.gradle
dependencies {
    implementation 'com.google.android.gms:play-services-basement:17.1.1'
    implementation 'com.google.android.gms:play-services-base:17.1.0'
}

واجهة التسجيل

افتراضيا ، سيقوم Incasy ببدء الاتصال مباشرة في Logat. يمكنك نقل هذه السجلات من خلال اتاحة عنصر يقوم باعداد واجهة تعامل أداة التسجيل :

interface Logger {
    fun log(level: Int, tag: String, message: String, error: Throwable?)
}

Instana {
    var logger: com.instana.android.Logger?
}

معاملات

مثال

Instana.logger = object : Logger {
    override fun log(level: Int, tag: String, message: String, error: Throwable?) {
        Log.d("my_tag", "intercepted Instana Android Agent log message: '$message'")
    }
}

مستويات التسجيل

افتراضيا ، سيقوم Ingass بتكوين سجلات مستوى INFO. يمكنك تغيير ذلك من خلال تعريف أي مستوى من مستويات السجل للمستوى العامandroid.util.Logمستويات (android.util.Log.INFO,android.util.Log.ERROR, ...):

Instana {
    var logLevel: Int
}

مثال

Instana.logLevel = android.util.Log.ERROR

اتاحة / الغاء اتاحة تجميع البيانات

يمكنك اتاحة أو الغاء اتاحة تجميع البيانات والاحالة في أي وقت ، مثل عند بدء agent أو أثناء وقت التشغيل.

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

Instana {
    fun setCollectionEnabled(enabled: Boolean)
    fun isCollectionEnabled()
}

مثال

Instana.setCollectionEnabled(true)

معاملات استعلام URL للاستعلام

قد تحتوي معاملات الاستعلام في عناوين URL التي تم تجميعها على بيانات حساسة. لذلك ، يقوم وكيل Ingreass بدعم المحددات الخاصة بنماذج regex keys لمفاتيح query parameter التي يجب تنقيح القيم الخاصة بها ؛ أي قيمة تم تنقيحها سيتم استبدالها بواسطة<redacted>.

يحدث تصرف Redaction في Inttana Agent ، قبل تسجيله لوحدة خدمة Inastana. وبالتالي ، فان الأسرار لن تصل الى وحدات خدمة Inastas للتشغيل ولن تكون متاحة للتحليل في UI أو الاسترجاع باستخدام Intana API.

وبصفة مفترضة ، يتم توصيف Intrea Agent مع كشف بثلاث نماذج regex لقيم معامل الاستعلام التي تم تحريرها آليا :

• "المفتاح"
• "سر"
• "كلمة السرية"

سيتم تطبيق Redaction فقط على الطلبات التي يتم مراقبتها آليا والسجلات المرتبطة بها. لم يتم تحرير الطلبات التي يتم مراقبتها يدويا.

Instana {
    val redactHTTPQuery = mutableListOf<Regex>()
}

مثال

class MyApp : Application() {

    override fun onCreate() {
        super.onCreate()
        Instana.setup(
            this,
            InstanaConfig(
                key = BuildConfig.INSTANA_KEY,
                reportingURL = BuildConfig.INSTANA_REPORTING_URL
            )
        )

        // in order to for example redact "https://example.com?secret=abcdef" into "https://example.com?secret=<redacted>"
        Instana.redactHTTPQuery.add("secret".toRegex())
        // in order to for example redact "https://example.com?hidden1=abcdef&hidden2=123456" into "https://example.com?hidden1=<redacted>&hidden2=<redacted>"
        Instana.redactHTTPQuery.add("^hidden[0-9]".toRegex())
    }
}

عناوين Capture HTTP

اختياريا ، يمكن أن يقوم وكيل Incure بالتقاط عناوين HTTP من كل request/responent.

يمكن تعريف كشف بنماذج regex لتحديد العناوين التي سيتم التقاطها.

سيتم التقاط العناوين فقط الخاصة بالطلبات / الردود التي يتم مراقبتها آليا. لا يتم التقاط العناوين الخاصة بالطلبات / الاستجابات التي يتم مراقبتها يدويا.

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

Instana {
    val captureHeaders = mutableListOf<Regex>()
}

مثال

class MyApp : Application() {

    override fun onCreate() {
        super.onCreate()
        Instana.setup(
            this,
            InstanaConfig(
                key = BuildConfig.INSTANA_KEY,
                reportingURL = BuildConfig.INSTANA_REPORTING_URL
            )
        )

        // in order to capture all request/response headers like: "X-MyCompany-name1", "X-MyCompany-name2"...
        Instana.captureHeaders.add("X-MyCompany-.*".toRegex())
    }
}