Performance¶

Metro strives to be a performant solution with minimal overhead at build-time and generating fast, efficient code at runtime.

Benchmarks¶

The benchmark project generates a deterministic multi-module workload for every framework. Its README documents the workload, generator, and runner commands.

Every ratio below compares frameworks within one run. The dated tabs preserve older measurements, but absolute values across tabs are not controlled comparisons because the tools, host environments, and Android versions changed.

Modes

• Metro: Metro’s compiler plugin and runtime.
• Dagger (KSP): Dagger KSP with Anvil KSP contribution merging.
• Dagger (KAPT): Dagger KAPT with Anvil KSP contribution merging.
• kotlin-inject: kotlin-inject with kotlin-inject-anvil contribution merging.
• Koin: Koin’s compiler plugin and runtime container.

Build Performance¶

Metro’s compiler plugin is designed to be fast. Running as a compiler plugin allows it to:

• Avoid generating new sources that need to be compiled.
• Avoid running KSP or KAPT.
• Generate IR that lowers directly into target platforms.
• Hook directly into kotlinc’s incremental compilation APIs.

Methodology¶

The build benchmarks use Gradle Profiler and report the median of ten measured builds without clean builds.

Each scenario targets a different kind of work:

• ABI and non-ABI scenarios change a lower-level module file that does use DI.
• Plain Kotlin variants change code that does not participate in DI.
• Graph Processing reruns the top-level graph or container processing task.

The benchmark README documents warm-ups, Kotlin compiler execution, cache settings, and stability checks.

Published Build Results¶

Runtime Performance¶

Metro’s compiler generates Dagger-style factory classes for every injection site. The same factory classes are reused across modules and downstream builds, so there’s no duplicated glue code or runtime discovery cost.

Because the full dependency graph is wired at compile-time, each binding is accessed through a direct provider field reference or direct invocation in the generated code. There are no reflection calls, hashmap lookups, or runtime service locator hops.

kotlin-inject generates an inner LazyMap in its component impl that is populated at component init.

Koin does not generate a graph impl at compile-time and instead resolves all dependencies at runtime.

Methodology¶

The JVM and R8 measurements use JMH average-time mode. Android uses an AndroidX microbenchmark and consumes each returned component through BlackHole.consume. The benchmark README documents the full runner configuration.

Published Runtime Results¶

Real-World Results¶

Below are some results from real-world projects, shared with the developers’ permission.

Scaling to Very Large Graphs¶

For graphs aggregating thousands of contributions, two opt-in knobs help work around JVM and Kotlin metadata size limits. Both are power-user features and unnecessary for typical graphs.

@MergeContributionsInIr¶

Annotating a graph with @MergeContributionsInIr opts it out of FIR-side contribution-supertype merging. Contributions are still merged into the graph during IR, so runtime behavior is unchanged. The trade-off is that contributions become invisible in the graph’s Kotlin metadata:

• Code consuming the graph as an @Includes dependency will not see contributed members.
• IDE support will not surface contributed members on the graph type.
• Kotlin/Native ObjC framework export will not include contributed interfaces in the graph’s supertype list.

This annotation is @DelicateMetroApi and requires explicit opt-in. You should only use this if you have a very specific reason to.

merged-supertype-chunk-size¶

The merged-supertype-chunk-size Metro compiler option groups merged contribution supertypes into synthetic intermediate interfaces of at most N contributions each. This is useful for graphs whose merged supertype list would otherwise exceed the JVM’s 65535-byte class signature limit, which the JVM emits whenever at least one supertype is generic.

metro {
  compilerOptions.put("merged-supertype-chunk-size", "200")
}

Default 0 disables chunking. Each chunk holds up to N contributions plus their promoted parent interfaces, so the chunk count tracks the contribution count rather than the raw supertype count. Most useful paired with @MergeContributionsInIr for the largest graphs.

Shortening generated member names¶

For very large graphs, the descriptive declaration names Metro generates on can contribute a measurable amount of bytecode/string-table size. The member-naming-strategy compiler option swaps them for a smaller vocabulary.

metro {
  compilerOptions.put("member-naming-strategy", "TYPED")
}

Three values are accepted:

• DESCRIPTIVE (default): names derived from binding types and parameters (e.g. httpClientProvider, databaseProvider).
• TYPED: short kinded prefixes for graph supplemental and graph-as-shard binding properties (provider, provider2, …; instance, instance2, …; factory, factory2, …).
• MINIMAL: single short vocabulary; every kind collapses to provider (e.g. provider, provider2, provider3, …).

When sharding is active and a graph splits into multiple shard classes, each shard’s binding properties always collapse to MINIMAL regardless of the chosen strategy (so long as it is not DESCRIPTIVE), and each shard uses its own name allocator. The same name string (provider, provider2, …) therefore recurs across shard classes.

When this matters¶

• Graph classes with thousands of fields shrink because each field name in the constant pool’s UTF-8 strings is shorter.
• Multi-shard graphs additionally benefit from cross-class deduplication since the same short strings recur across shard classes.
• Factory (and similar) classes benefit similarly via cross-class dedup in DEX, where the small fixed vocabulary recurs across thousands of generated factory classes.

When this does not matter¶

Builds shrunk by R8/ProGuard: Private generated field names are renamed/inlined/etc by the shrinker regardless of what Metro emits. There is effectively no artifact-size difference between DESCRIPTIVE, TYPED, and MINIMAL once R8 has run. The option is most useful for pipelines that ship un-minified bytecode (pure JVM server apps, distributed library AARs at author dev time, debug Android builds).

Default is DESCRIPTIVE so generated code stays readable. Opt in only if you have a specific size constraint that benefits.

Tracing¶

Compiler tracing¶

If you want to investigate the performance of Metro’s compiler pipeline, you can enable tracing in the Gradle DSL.

metro {
  traceDestination.set(layout.buildDirectory.dir("metro/trace"))
}

This will output one or more Perfetto trace files after the compilation that you can then load into https://ui.perfetto.dev.

Filenames follow the pattern <id>-<phase>-<moduleName>.perfetto-trace, where <id> is a yyMMdd-HHmmss timestamp shared across every file produced by the same compilation, <phase> is fir or ir, and <moduleName> identifies the FIR session or IR module fragment. KMP source-set hierarchies and multi-fragment IR each produce their own files. Load whichever file corresponds to the phase you want to inspect.

Note that these traces probably do require a bit of familiarity with the Metro compiler internals.

Runtime tracing¶

Metro can also emit traces from generated graph code. For example, this is useful when you want to see which bindings are created or invoked during app startup or another measured runtime path.

Enable it in the Gradle DSL:

metro {
  enableRuntimeTracing.set(true)
}

When automatic runtime dependencies are enabled, Metro adds the JVM-only metro-trace helper artifact to JVM/Android JVM compilations.

Each root graph should take an AndroidX Tracer as a graph input. Metro uses this input while initializing the graph’s trace context, before ordinary binding traces can be emitted:

@DependencyGraph
interface AppGraph {
  @DependencyGraph.Factory
  interface Factory {
    fun create(@Provides tracer: Tracer): AppGraph
  }
}

On Android, prefer owning a single app-level TraceDriver and passing its tracer into the root graph from Application.onCreate():

class MyApplication : Application(), AbstractTraceDriver.Factory {
  private val sink = TraceSink(context = this)
  // isCategoryEnabled = { true } here means that Tracing is unconditionally enabled.
  // This makes local iteration fast and easy. In production, you might want to use another explicit signal
  // (or UI affordance) to turn on in-process tracing.
  private val driver = TraceDriver(context = this, sink = sink, isCategoryEnabled = { true })

  lateinit var appGraph: AppGraph
    private set

  @OptIn(DelicateTracingApi::class)
  override fun onCreate() {
    super.onCreate()
    Tracer.setGlobalTracer(driver.tracer)
    appGraph = createGraphFactory<AppGraph.Factory>().create(driver.tracer)
  }

  override fun create(): AbstractTraceDriver = driver
}

AbstractTraceDriver.Factory lets AndroidX’s profiler tooling discover the same driver that Metro uses. Tracer.setGlobalTracer(...) also makes the tracer available to other libraries using AndroidX’s global tracer discovery. Also, disable the default TraceDriver initialization hook (androidx.tracing.profiler.ConnectedProfilerTracingInitializer) so it does not eagerly set Tracer.setGlobalTracer(...).

<!-- Use MyApplications's TraceDriver so sample traces and profiler broadcasts share one sink and is always enabled. -->
<meta-data
    android:name="androidx.tracing.profiler.ConnectedProfilerTracingInitializer"
    android:value="androidx.startup"
    tools:node="remove" />

With AndroidX Tracing 2.0.0-alpha09 and newer, TraceSink defers file setup. Graph creation no longer needs to be delayed with lazy just to avoid early trace output initialization.

@Provides
fun provideDatabase(driver: SqlDriver, tracer: Tracer): AppDatabase =
  tracer.trace(category = "app.database", name = "Open database") {
    AppDatabase(driver)
  }

Suspend bindings use coroutine-aware trace sections, so their spans remain connected across suspension points and thread changes. Suspend accessors emit the same instant events as other accessors. A scoped suspend binding emits a span only when it computes the value; cache hits emit none. See Coroutines Support.

Generated binding spans use the short rendered binding name, including the qualifier when present. Entry-point markers, such as accessors and member injectors, are emitted as instant events named after the implemented graph callable. Requested MembersInjector<T> values also emit instant events named like MembersInjector<T> when injectMembers(...) is called. Metro also attaches string metadata for filtering and grouping:

• metro.graph: the graph that owns the binding.
• metro.graph_path: the root-to-current graph path, useful for graph extensions.

Binding span metadata:

• metro.type: the canonical unqualified type.
• metro.binding_kind: the generated binding implementation kind, such as Provided, ConstructorInjected, or Multibinding.

Entry-point instant metadata:

• metro.callable: the callable name without the graph prefix, such as foo for AppGraph.foo.
• metro.type: the canonical unqualified requested type.
• metro.entry_point_kind: the generated graph entry-point kind, such as Accessor or Member Injector.

Both binding spans and entry-point instants may also include:

• metro.contextual_type: the requested unqualified type, when it differs from metro.type, such as Provider<T> or Lazy<T>.
• metro.qualifier: the binding qualifier, when present.

Here is what a trace looks like.

Here is the link to the sample app with the right setup for runtime tracing.

adb shell am broadcast -a androidx.tracing.profiler.action.FLUSH_TRACES_GET_PATH <targetPackage>/androidx.tracing.profiler.ConnectedProfilerTracingReceiver