Getting Started

In order to allow Instabug App Performance Monitoring to capture network requests, you will need to include our Gradle plugin in your project. Currently, we support capturing requests made via OkHttpClient and HTTPURLConnection.

1. Add the dependency to your project's build.gradle file.

plugins {
  id("com.instabug.library") version "12.4.1" apply false // adds instabug plugin
}

buildscript {
    dependencies {
        // ...
        classpath 'com.instabug.library:instabug-plugin:13.0.1'
    }
}

2. Add the plugin in your application's build.gradle:

plugins { 
  id("instabug-apm") // Instabug APM Plugin
}

apply plugin: 'instabug-apm'

📘

The Plugin DSL in Kotlin is supported starting SDK version 12.4.1.

Plugin Alternatives:

You can always use a manual approach to capture requests made via the OkHttpClient by adding our Interceptor and EventListener using the below code snippets:

new OkHttpClient.Builder()
        // add your interceptors here
        .addInterceptor(new InstabugAPMOkhttpInterceptor())

        // Add Instabug EventListener
        .eventListener(new InstabugApmOkHttpEventListener(/** optional: add your own EventListener here **/))
        // Or Add Instabug EventListenerFactory
        .eventListenerFactory(new InstabugApmOkHttpEventListener.Factory(/** optional: add your own EventListener factory here **/))
        .build();

OkHttpClient.Builder()
    // add your interceptors here
    .addInterceptor(InstabugAPMOkhttpInterceptor())

    // Add Instabug EventListener
    .eventListener(InstabugApmOkHttpEventListener(/** optional: add your own EventListener here **/))
    // Or Add Instabug EventListenerFactory
    .eventListenerFactory(InstabugApmOkHttpEventListener.Factory(/** optional: add your own EventListener factory here **/))
    .build()

📘

GraphQL Support

Instabug supports capturing requests made via the OkHttpClient including GraphQl and HTTPURLConnection.

📘

APM Network Logs are independent from Bug and Crash Reporting

Please note that Network Logs that are captured in Bug and Crash reports will not be captured by APM, the only way to enabled Network performance monitoring in APM is by adding this plugin. Enabling Network performance monitoring has no effect on Network Logs captured in Bug and Crash reports, these are configured separately and are completely independent from APM.

gRPC Support

Instabug supports the logging of gRPC requests. You'll first need to add the gRPC intereceptor module to your dependencies.

Integration

With Instabug already integrated and added to your dependencies, you'll only need to add the following dependency to your applications build.gradle:

implementation 'com.instabug.library:instabug-apm-grpc-interceptor:$INSTABUG_VERSION

📘

Minimum SDK Version

The gRPC interceptor is supported starting SDK version 10.13.0.

Intercepting gRPC requests

When creating a gRPC channel using your preferred builder, create a new instance of InstabugAPMGrpcInterceptor and attach it to the builder using intercept method as shown in the example below:

OkHttpChannelBuilder.forAddress(host, port)
    .intercept(InstabugAPMGrpcInterceptor())
    .build()

OkHttpChannelBuilder.forAddress(host, port)
    .intercept(InstabugAPMGrpcInterceptor())
    .build();

Trace Attributes

Sometimes, you may need to add additional data or attributes to your network traces. This can be done using the API below.

APM.addOnNetworkTraceListener(
    object: OnNetworkTraceListener(
                UrlPredicate { url:String ->
                    // Add filter here the URL 
                    // return boolean
                }
    )
    {
        override fun addAttributesOnFinish(trace: NetworkTrace?): MutableMap<String, String?> {
            // Return map of Pairs (i.e. keys and values)
            return mutableMapOf(
              			// Up to five attributes
                    Pair("Key", "Value")
            )
        }
    }
)

APM.addOnNetworkTraceListener(new OnNetworkTraceListener(
    new UrlPredicate() {
        @Override
        public boolean check(@NonNull String url) {
            // Add filter here the URL 
            // return boolean
        }
    }); 
    {
        @Override
        public Map<String, String> addAttributesOnFinish(NetworkTrace trace) {
            Map<String, String> map;
            map.put("Key", "Value");
            // Up to five attributes
            return map;
        }
    }
);

📘

You can add up to 20 unique trace attributes per each trace.

Payload Size

By default, Instabug captures the payload size of the request and response; this should help with determining if the payload size could be causing any issues with network delays. The payload size is the size of the payload itself, so it does not include the header's size.

Instabug automatically buckets payload sizes into different buckets based on the distribution of the data per network group, with a minimum sensitivity of 10 bytes per bucket.

URL Patterns

URL patterns are used to group the relevant network call occurrences and aggregate their numbers. Let's take the following examples:

• sample.com/list/3/item/1
• sample.com/list/3/item/2
• sample.com/profile/

It looks like 1 and 2 are the same request, but asking for different resources. While 3 is an entirely different one. Those three examples result in the following 2 URL patterns:

• sample.com/list/*/item/*
• sample.com/profile/

What Are the URL Pattern Components?

• Plain text: works with exact string matching
• *: matches with any URL part. * matches with only one part at a time. For example if you are mapping sample.com/part/variable1/variable2, your pattern should be sample.com/part/*/* and not sample.com/part/*

Does Instabug Detect Patterns Automatically?

Instabug automatically detects numbers and hexadecimal tokens in your URLs and replaces them with *.

Can You Create Custom Patterns?

If you are using more complex URLs where variable parts may contain plain text and not only numbers and hexadecimal, we recommend defining your custom patterns. Just click on the "Create URL pattern" button in your network list.

Here are a few examples:

Some notes to consider while creating your URL patterns:

• Custom URL patterns that you define have higher precedence than the auto-generated ones. If the same call matches with a custom and an auto pattern, it gets grouped with the custom.
• At any point, you can delete a pattern to prevent grouping new calls with it.
• URL patterns shouldn't overlap. Each incoming network call gets grouped with only one pattern. In case of conflict, it gets merged with the newest pattern.

📘

Creating or deleting patterns doesn’t affect your old data that has already been grouped. It only affects the upcoming network requests.

Network Calls Apdex

Instabug calculates an Apdex score for every network request (URL pattern) in your app. Apdex score ranges between 0 and 1. The higher the value, the closer you are to satisfying user experience:

• Apdex score ≥ 0.94 equates to Excellent performance.
• Apdex score ≥ 0.85 and < 0.94 equates to Good performance.
• Apdex score ≥ 0.7 and < 0.85 equates to Fair performance.
• Apdex score ≥ 0.5 and < 0.7 equates to Poor performance.
• Apdex score < 0.5 is considered Unacceptable.

How Is the Network Calls Apdex Calculated?

When a network call occurrence is collected, it is flagged based on a pre-defined target (T). A network call occurrence is considered:

• Satisfying: if its duration ≤ T
• Tolerable: if its duration > T and ≤ 4T
• Frustrating: if its duration > 4T or if it fails due to a server-side or client-side error.

Then based on the bucketing explained above, the Apdex is calculated:

• Total occurrences = Satisfying occurrences + Tolerable occurrences + Frustrating occurrences
• Apdex score = (Satisfying occurrences + 0.5 * Tolerable occurrences) / Total occurrences

How Can You Control a Specific Network Call's Target?

By default, it is set to 0.5 seconds; however, you can easily change this number from your dashboard by clicking on the action highlighted in the screenshots below.

📘

Please note that updating your response time target does not affect the already stored occurrences, only future occurrences will be flagged using the new target.

Network Latency Breakdown

You can see the P50s, P95s, and the frequency of each stage/operation that occurred inside a network group. These are the stages/operations that were made to send the network request and receive its response from the server.

The feature works out-of-the-box without any instrumentation, and the stages are shown inside the Spans table inside the Network metric.

The spans table contains the following stages:

• DNS Lookup
• Connection Handshake
• TLS Connection
• Uploading Request
• Downloading Response
• Server Processing

You can also see the breakdown and visualize the stages' timeline on an occurrence level inside the occurrences page.

📘

• The minimum required SDK version for this feature is v12.0.0
• The minimum required Okhttp version is 3.13.0
• The minimum required Android version is 5.0 & API Level 21

Disabling/Enabling Network Performance Monitoring

Once you include the plugin as described in the Getting Started section, capturing network requests is enabled by default. However, you can still disable Network performance monitoring by configuring the plugin in your build.gradle file as described below:

Instabug {
    APM {
        networkInterceptingEnabled false
    }
}

📘

Please note that does not control network logs captured in Bug and Crash reports, it only controls APM.