OkHttp interceptors for network monitoring

To monitor network calls in an Android app, add an application interceptor to record failed requests (4xx, 5xx, timeouts, connection errors) and an EventListener to record timings (DNS, connect, TLS, time to first byte, total). Use HttpLoggingInterceptor only in debug builds: at HEADERS or BODY level it can leak Authorization headers, cookies and request bodies into your logs. Whatever you record, strip query strings and redact credentials before the data leaves the device.

This guide shows each piece with Kotlin code, then how Codeskop's tracker-okhttp adapter does the same with one line. If you're working on app stability in general, read Android ANRs: causes, detection and fixes, because blocking on network calls is a classic ANR cause. The Codeskop side is in the network capture docs. Flutter teams using Dio can apply the same ideas; see Flutter error handling.

Application vs network interceptors#

OkHttp lets you register an interceptor at two points. The OkHttp interceptors docs compare them:

For monitoring, use an application interceptor. It sees one outcome per logical call, including the final result after redirects and retries, which is what your users experience. Use a network interceptor when you need to see what actually went over the wire, for example to debug a redirect loop or check compression headers.

1val client = OkHttpClient.Builder()2    .addInterceptor(FailureInterceptor())          // application: one outcome per call3    .addNetworkInterceptor(WireDebugInterceptor()) // network: every hop, debug only4    .build()

HttpLoggingInterceptor and its pitfalls#

OkHttp's logging interceptor is the quickest way to see traffic. Keep its version in step with your OkHttp version (the BOM helps):

1dependencies {2    implementation(platform("com.squareup.okhttp3:okhttp-bom:5.5.0"))3    implementation("com.squareup.okhttp3:okhttp")4    implementation("com.squareup.okhttp3:logging-interceptor")5}

The levels are NONE, BASIC (request line and response status), HEADERS and BODY. OkHttp's own README warns that logs at HEADERS or BODY level "have the potential to leak sensitive information such as 'Authorization' or 'Cookie' headers and the contents of request and response bodies", and should only be used in a controlled way or outside production.

A safe configuration:

1val logging = HttpLoggingInterceptor().apply {2    level = if (BuildConfig.DEBUG) {3        HttpLoggingInterceptor.Level.BODY4    } else {5        HttpLoggingInterceptor.Level.NONE6    }7    redactHeader("Authorization")8    redactHeader("Cookie")9    redactHeader("Set-Cookie")10}

The pitfalls we see most often:

• Shipping BODY in release. Logcat ends up in bug reports and in any log-forwarding SDK. Phone numbers, OTPs, M-Pesa transaction details and tokens in request bodies all leak this way.
• Forgetting custom auth headers. redactHeader only redacts what you name. If your API uses X-Api-Key or X-Session-Token, add them.
• Tokens in query strings. redactHeader doesn't touch URLs. ?token=... is logged as-is at every level.
• Using logs as monitoring. Logs on a user's phone never reach you. Logging is a debugging tool; monitoring means sending structured, redacted events to a server.

Recording failures with an application interceptor#

This interceptor records every call that fails: a non-2xx response or an IOException (timeout, DNS failure, connection reset). It never changes the response, and it rethrows exceptions so your app behaves exactly as before.

1class FailureInterceptor(2    private val recorder: NetworkRecorder,3) : Interceptor {4 5    override fun intercept(chain: Interceptor.Chain): Response {6        val request = chain.request()7        val started = System.nanoTime()8        val path = request.url.encodedPath          // no query string9 10        val response = try {11            chain.proceed(request)12        } catch (e: IOException) {13            recorder.failure(request.method, request.url.host, path,14                status = null, kind = errorKind(e), tookMs = elapsedMs(started))15            throw e16        }17 18        if (!response.isSuccessful) {19            recorder.failure(request.method, request.url.host, path,20                status = response.code,21                kind = if (response.code >= 500) "http_5xx" else "http_4xx",22                tookMs = elapsedMs(started))23        }24        return response25    }26 27    private fun errorKind(e: IOException) = when (e) {28        is SocketTimeoutException -> "timeout"29        is UnknownHostException -> "dns"30        is InterruptedIOException -> "timeout"   // includes call timeouts31        else -> "network_error"32    }33 34    private fun elapsedMs(start: Long) = (System.nanoTime() - start) / 1_000_00035}

Two details matter when you aggregate. First, use the path, not the full URL, and collapse IDs (/orders/42 → /orders/{id}) so failures group sensibly. Second, record a 3xx only if your client doesn't follow redirects. By default OkHttp follows them, and the application interceptor sees the final response.

Measuring latency with EventListener#

An interceptor can time a whole call, but it can't tell you where the time went. EventListener receives callbacks for each phase: callStart, dnsStart/dnsEnd, connectStart, secureConnectStart/secureConnectEnd, connectEnd, connectionAcquired, the request and response header and body events, connectionReleased and finally callEnd, or callFailed if the call fails permanently.

Because calls run concurrently, create one listener per call with a Factory:

1class TimingListener(2    private val call: Call,3    private val sink: (CallTiming) -> Unit,4) : EventListener() {5    private val start = System.nanoTime()6    private var dnsStart = 0L; private var dnsMs = -1L7    private var connectStart = 0L; private var connectMs = -1L8    private var tlsStart = 0L; private var tlsMs = -1L9    private var ttfbMs = -1L10 11    override fun dnsStart(call: Call, domainName: String) { dnsStart = System.nanoTime() }12    override fun dnsEnd(call: Call, domainName: String, inetAddressList: List<InetAddress>) {13        dnsMs = ms(dnsStart)14    }15    override fun connectStart(call: Call, inetSocketAddress: InetSocketAddress, proxy: Proxy) {16        connectStart = System.nanoTime()17    }18    override fun secureConnectStart(call: Call) { tlsStart = System.nanoTime() }19    override fun secureConnectEnd(call: Call, handshake: Handshake?) { tlsMs = ms(tlsStart) }20    override fun connectEnd(call: Call, inetSocketAddress: InetSocketAddress, proxy: Proxy, protocol: Protocol?) {21        connectMs = ms(connectStart)22    }23    override fun responseHeadersStart(call: Call) { ttfbMs = ms(start) }24    override fun callEnd(call: Call) = emit(failed = false)25    override fun callFailed(call: Call, ioe: IOException) = emit(failed = true)26 27    private fun emit(failed: Boolean) = sink(28        CallTiming(call.request().method, call.request().url.encodedPath,29            dnsMs, connectMs, tlsMs, ttfbMs, totalMs = ms(start), failed = failed)30    )31    private fun ms(from: Long) = (System.nanoTime() - from) / 1_000_00032 33    class Factory(private val sink: (CallTiming) -> Unit) : EventListener.Factory {34        override fun create(call: Call): EventListener = TimingListener(call, sink)35    }36}37 38val client = OkHttpClient.Builder()39    .addInterceptor(FailureInterceptor(recorder))40    .eventListenerFactory(TimingListener.Factory { timing -> recorder.timing(timing) })41    .build()

Things to know:

• Pooled connections skip DNS, connect and TLS. The OkHttp docs show a second request to the same host firing only connectionAcquired and the request/response events. A -1 for those phases is normal.
• Retries fire events more than once. connectFailed() isn't terminal if OkHttp recovers, so keep the last value or sum them, but be consistent.
• Keep callbacks cheap. They run on OkHttp's threads, inside the call. Hand the data to a queue; don't do disk or network I/O in the callback.
• One factory per client. eventListenerFactory takes a single factory. To combine several listeners, write a small delegating listener.
• Sample timings, not failures. Every call produces a timing, so sample those (the docs show a factory returning EventListener.NONE for 90% of calls). Keep every failure.

Measuring failures and latency that matter#

Once you have the data, a few views answer most questions:

• Failure rate per endpoint (method + path), split by status class and error kind. A spike in timeout with no rise in http_5xx points at the network or a slow dependency, not a crashing server.
• p50 and p95 total time per endpoint, and the phase breakdown for slow calls. High DNS and connect times with a normal TTFB is a network problem; high TTFB is a server problem.
• Breakdown by app version, device and network type, so you can tell a bad release from a bad area.

This matters in markets like Kenya. Outside the main cities, 3G coverage is patchy and DNS and TLS setup on a congested cell can dominate total time. Payment flows that call the M-Pesa Daraja API can time out while waiting on a callback. A per-phase breakdown tells you whether to fix your server, your timeouts or your retry logic.

Redacting headers and URLs#

Before sending anything off the device:

1. Drop the query string: request.url.newBuilder().query(null).build(), or just record encodedPath.
2. Allow-list headers rather than block-listing them. Record Content-Type, Content-Length and Cache-Control; never Authorization, Cookie or Set-Cookie.
3. Never record bodies in production monitoring. Record sizes instead (request.body?.contentLength(), Content-Length on the response).
4. Collapse IDs in paths so user or order numbers don't become personal data in your metrics.

Network capture with Codeskop#

If you'd rather not build and maintain this yourself, Codeskop's tracker-okhttp adapter registers both pieces, a failure interceptor and an event listener, with one line. Network capture is included on the Starter plan and above ($49/month as of October 2026; see pricing). On Free, the SDK doesn't capture network calls even with the adapter installed; upgrading switches it on without a new release.

1dependencies {2    implementation("com.codeskop.sdk:tracker-android:0.3.0")3    implementation("com.codeskop.sdk:tracker-okhttp:0.3.0") // optional: network capture4}

1import com.codeskop.sdk.okhttp.codeskop2import okhttp3.OkHttpClient3 4val client = OkHttpClient.Builder()5    .codeskop()   // failed requests + timing for every request6    .build()

OkHttp has no global hook, so adding the dependency alone captures nothing. Build the client your app actually uses (including the one you pass to Retrofit) with .codeskop(). If you already set your own eventListenerFactory, keep it and add just the interceptor:

1val client = OkHttpClient.Builder()2    .addInterceptor(CodeskopOkHttpInterceptor())   // keep your own eventListenerFactory3    .eventListenerFactory(myListenerFactory)4    .build()

What it records, per the network capture docs:

• Failures: any 4xx or 5xx response, timeout or connection failure, with error kinds http_4xx, http_5xx, timeout or network_error. Your exception still reaches your code unchanged.
• Timings: DNS, connect, TLS, time to first byte and total for each completed request. Timings are sampled through remote config; failures are always kept.
• Context: method, host and path, request and response sizes, and the device, app version and user.
• Never captured: request and response bodies, query strings, and the Authorization, Cookie and Set-Cookie headers. Any header in redactHeaders is masked as a second safeguard.

Failed requests become issues grouped by method, path and status, with IDs collapsed (POST /orders/{id} → 500). Latency charts built from the timings are coming to the dashboard; failures are there today. Events are queued on the device and uploaded by WorkManager when there's a connection, so failures that happen because the user lost signal are still reported later.