Android Monitoring API

Setup

We recommend initializing Instana in your Application class' onCreate(), right after super.onCreate():

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

Current configuration

To check the current Instana configuration, simply access the InstanaConfig instance:

val currentConfig = Instana.config

Session identifier

Each Instana agent instance has an unique session identifier you could use for other purposes in your app.

val sessionId = Instana.sessionId

Automatic HTTP monitoring

By default, HTTP sessions will be be captured automatically. Upon initializing Instana (after installing the Instana Android Plugin and Instana Android SDK), the Agent will take care of the rest.

The Instana Android agent will automatically weave code to provide monitoring of HTTP requests for the supported clients:

• OkHttp3
• HttpURLConnection
• Retrofit

Automatic HTTP monitoring can be disabled in favor of manual HTTP monitoring, as explained in the following section.

Manual HTTP monitoring

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

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)
}

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);

Views

Instana can segment mobile app insights by logical views. To do so, set the view name via the Instana.setView(String) method. The view will then be associated to all monitored beacons until the view changes once setView is called again.

We recommend not to use technical or generic names like the Class (e.g. WebViewActivity) to define views. We recommend the usage of readable names for views, for example product detail page or payment selection. Focusing on what users are experience will allow team members without intimate knowledge of the codebase to understand the insights provided.

Note: Instana.setView(String) should be called when a screen is presented to the user, rather than when a screen is created (as in a Fragment which could be created once but shown multiple times). Setting the view name will also enable Instana to track page transitions in addition to page loads.

class WebViewActivity : AppCompatActivity() {

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

Identifying users

User-specific information can optionally be sent with data transmitted to Instana. This information can then be used to unlock additional capabilities such as:

• calculate the number of users affected by errors,
• to filter data for specific users and
• to see which user initiated a view change or HTTP request.

By default, Instana will not associate any user-identifiable information to beacons. Please be aware of the respective data protection laws when choosing to do so. We generally recommend identification of users via a user ID. For Instana this is a completely transparent String that is only used to calculate certain metrics. userName and userEmail can also be used to have access to more filters and a more pleasant presentation of user information.

In cases in which you are handling anonymous users and thus don't have access to user IDs you could alternatively use session IDs. Session IDs are not as helpful as user IDs when filtering data but they are a good indicator to calculate affected/unique user metrics. We recommend setting a user name such as Anonymous to have a clear differentiation between authenticated and unauthenticated users. Session IDs can be sensitive data (depending on the framework/platform used). Please consider hashing session IDs to avoid transmitting data to Instana that can grant access.

It is important to note that data already transmitted to Instana's server cannot be retroactively updated. For this reason it is important to call this API as early as possible in the app launch process.

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 data

Arbitrary meta data can optionally be attached to all data transmitted to Instana. Consider using this to track UI configuration values, settings, feature flags… any additional context that might be useful for analysis.

Note: Currently, up to 50 meta key/value pairs are supported. The key can be up to 98 characters, and the value can be up to 1024 characters.

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")
    }
}

Excluding URLs from monitoring

URLs can be ignored by providing regular expressions, by adding them to the ignoreURLs list. A good scenario for usage of this function would be to ignore all HTTP requests that contain any sensitive data like a password.

Only automatically monitored URLs will be ignored. Manually monitored URLs will not be ignored.

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())
    }
}

Report custom events

Custom events enable reporting about non-standard activities, important interactions and custom timings to Instana. This can be especially helpful when analyzing uncaught errors (breadcrumbs) and to track additional performance metrics.

Instana {
    fun reportEvent(event: CustomEvent)
}

The Instana-provided CustomEvent allows you to set multiple parameters, eventName (in its constructor) being the only mandatory one.

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 play services

You can explicitly tell Instana whether Google Play Services are available for a given user & session.

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'
}

Logging facade

By default, Instana will log directly into LogCat. You can pipe these logs by providing an object implementing the Logger interface:

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'")
    }
}

Logging levels

By default, Instana will generate INFO level logs. You change this by defining any log level out of the common android.util.Log levels (android.util.Log.INFO, android.util.Log.ERROR, ...):

Instana {
    var logLevel: Int
}

Instana.logLevel = android.util.Log.ERROR

Enable/Disable Data Collection

You can enable or disable data collection and submission at any time, such as at agent startup or during runtime.

This is most useful in scenarios where explicit user consent is required before the collection of data can proceed.

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

Instana.setCollectionEnabled(true)

Redact URL Query parameters

Query parameters in collected URLs might contain sensitive data. Therefore, the Instana agent supports the specification of regex patterns for query parameter keys whose values should be redacted; any redacted value will be replaced with <redacted>.

Redaction happens within the Instana agent, before reporting to the Instana server. Consequently, secrets will not reach the Instana servers for processing and will not be available for analysis in the UI or retrieval by using Instana API.

By default, the Instana agent is configured with a list of three regex patterns to automatically redact query parameter values:

• "key"
• "secret"
• "password"

Redaction will only be applied to automatically monitored requests and their associated logs. Manually monitored requests are not redacted.

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 headers

Optionally, the Instana agent can capture the HTTP headers of every tracked request/response.

A list of regex patterns can be defined to determine which headers will be captured.

If the same header name is present in both a request and its response, only the response's header value will be kept.

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())
    }
}

Slow sending mode

The slow sending mode feature is disabled by default. If required, you can enable this feature.

By default, if a beacon sending fails, the Instana agent tries to resend the beacon until the sending is successful. This doesn't work well with some cellular networks. By enabling the slow sending mode feature, the beacon sending interval is changed to the time value that is assigned to the slowSendIntervalMillis parameter. Each beacon sending consists of only one beacon instead of a batch (maximum 100 beacons in a batch). The Instana agent stays in slow sending mode until one beacon is sent successfully.

The valid time range for slowSendIntervalMillis is 2000-3600000 milliseconds.

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Instana.setup(
            this,
            InstanaConfig(
                key = BuildConfig.INSTANA_KEY,
                reportingURL = BuildConfig.INSTANA_REPORTING_URL,
                slowSendIntervalMillis = 60000
            )
        )
    }
}