Stetho — what it is, debugging Android through Chrome DevTools

What Stetho is and how it works

Stetho is a Java library that runs a local WebSocket server inside an Android application. Chrome DevTools connects to this server through an adb port, gaining access to the application's internal components: databases, network requests, preferences and the view hierarchy. All communication goes through the Chrome DevTools Protocol, which allows using standard browser tools without installing additional software.

Architecture and components

The library consists of modules: stetho (core), stetho-okhttp (traffic interception through OkHttp), stetho-urlconnection (interception through HttpURLConnection) and stetho-js-rhino (support for JavaScript plugins). The core opens a UNIX socket to which Chrome connects through adb forward. Each inspector is implemented as a separate plugin registered when Stetho is initialized.

Requirements and limitations

Stetho supports Android 4.4+ (API 19) and only works in debug builds. On devices with Android 11+, an explicit INTERNET permission is required in the manifest. The library is officially unsupported by Facebook since 2020, but the code remains open and is used in legacy projects. For new projects Google recommends Android Studio Profiler and Network Inspector.

Connecting and configuring Stetho in an Android project

Connection is done through a Gradle dependency with the debugImplementation flag so that Stetho only works in the debug build. Initialization happens in the Application.onCreate() method with a single Stetho.initializeWithDefaults(this) call. For the Network Inspector, integration with OkHttp through an Interceptor is required.

// build.gradle (app) — adding Stetho
dependencies {
    debugImplementation 'com.facebook.stetho:stetho:1.6.0'
    debugImplementation 'com.facebook.stetho:stetho-okhttp3:1.6.0'
}

// Initialization in the Application class
public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Stetho.initializeWithDefaults(this);
    }
}

Configuring the Network Interceptor

To intercept network requests through OkHttp, add StethoInterceptor to the interceptor chain. Stetho automatically logs the URL, request and response headers, status code and execution time. The data is displayed in the Network tab in Chrome DevTools after connecting to the device through chrome://inspect.

Network Inspector: intercepting HTTP traffic

Network Inspector in Stetho displays all HTTP requests of the application in chronological order. For each request the following are available: method, URL, status code, request and response headers, request and response body (including JSON and binary data). The Preview tab shows the response body in a formatted view.

Filtering and searching requests

Chrome DevTools supports filtering requests by type (XHR, JS, CSS, Doc), status code and domain. The search field filters by URL and content. For mobile development it is useful to group requests by API domain and check the call sequence when testing application screens.

// OkHttp client with Stetho interceptor
OkHttpClient client = new OkHttpClient.Builder()
    .addNetworkInterceptor(new StethoInterceptor())
    .build();

// Executing a request
Request request = new Request.Builder()
    .url("https://api.example.com/users")
    .build();
client.newCall(request).enqueue(callback);

Database Inspector: working with SQLite

Database Inspector in Stetho connects to the application's SQLite databases through Chrome DevTools. In the Resources → Web SQL tab all open databases, their tables and contents are displayed. Viewing the table structure, indexes and running arbitrary SQL queries is available.

Running SQL queries through DevTools

In the Chrome DevTools console you can run SQL queries directly against the application database: SELECT, INSERT, UPDATE, DELETE. This is useful for clearing data before testing, verifying the correctness of migrations and manually fixing incorrect records without rebuilding the application. All changes are immediately visible on the device.

Dumpapp and custom plugins

Dumpapp is Stetho's shell interface that allows running custom commands through adb. Dumpapp plugins are registered when Stetho is initialized and can export any application state: cache, settings, DI container state. Commands are executed as adb forward tcp:12345 localabstract:stetho_dumpapp.

Creating a custom Dumpapp plugin

A plugin implements the DumperContext interface and is registered through Stetho.initialize with a custom InspectorModules. The example below shows a plugin for dumping SharedPreferences: the data is serialized to JSON and output to the terminal through an adb command.

// Custom Dumpapp plugin for SharedPreferences
public class PrefsDumper implements DumperContext {
    @Override
    public String getName() {
        return "prefs";
    }
    @Override
    public void dump(DumperContext ctx) {
        SharedPreferences sp = ctx.getContext()
            .getSharedPreferences("app_prefs", Context.MODE_PRIVATE);
        ctx.getStdout().println(sp.getAll().toString());
    }
}

Stetho vs Android Studio Inspector: comparison

Android Studio provides built-in profiling tools: Network Profiler, Database Inspector and View Inspector, introduced in Android Studio 4.1+. Stetho was popular before these tools were introduced and remains relevant for projects that use OkHttp and require integration with Chrome DevTools.

When to choose Stetho

Stetho is justified in legacy projects where OkHttp is already used and the team is used to Chrome DevTools. For new projects Android Studio Inspector covers most debugging scenarios. However, Chrome DevTools is still more convenient for SQLite queries: the built-in console with SQL autocompletion is faster than sequential clicks in the IDE.

Inspecting the View Hierarchy through Stetho

View Hierarchy in Stetho is displayed in the Elements tab of Chrome DevTools as a DOM-like tree. Each View is represented as an HTML element with attributes: id, layout_width, layout_height, padding, margin, visibility and text. Changes in the tree are synchronized in real time on screen rotation or UI updates.

Viewing and changing properties

By selecting an element in the tree, you can view its properties on the Styles panel — similar to inspecting web pages. Stetho displays computed sizes, paddings, background color and state (pressed, focused, enabled). Changing some properties in DevTools is immediately applied to the application, which speeds up selecting UI parameters without rebuilding.

Finding memory leaks through View Inspector

Stetho helps detect memory leaks related to View: if an Activity is not destroyed after finish(), its root View remains in the tree. By regularly checking the Elements tab you can notice phantom Activities and find the leak source — usually static references to Context or unclosed dialogs.

Practical debugging techniques

Stetho is effective for checking JSON serialization before sending it to the server. Open the Network Inspector, find the request and view the body in Raw mode to check the data structure and correctness of the fields.

Debugging SQLiteOpenHelper

Stetho displays all databases created through SQLiteOpenHelper. If the database does not appear in Chrome DevTools — check that getWritableDatabase() has been called at least once in the application code.

Interceptor order in OkHttp

Stetho must be the last interceptor in the OkHttp chain to see modified requests. The correct order: AuthInterceptor first, then LoggingInterceptor, then StethoInterceptor last.

Practical debugging techniques with Stetho

Stetho is effective for checking the correctness of JSON serialization before sending to the server. Open the Network Inspector, find the request and view the request body in Raw mode to make sure the field structure and data types are correct.

Debugging SQLiteOpenHelper and ContentProvider

Stetho displays all databases created through SQLiteOpenHelper. If the database does not appear in Chrome DevTools — check that the getWritableDatabase() method has been called at least once in the application code. For migrations, run ALTER TABLE through the SQL console and verify the result with a SELECT query.

Interceptor order in the OkHttp chain

Stetho must be the last interceptor in the OkHttp chain to display the final modified requests. The correct sequence: AuthInterceptor first, then LoggingInterceptor, then StethoInterceptor last for correct logging.