# Instrumentation

# Instrumentation

<br />

```
public interface Instrumentation
```

<br />

*** ** * ** ***

Options to register asm class visitors and to configure the instrumentation process.

## Summary

|                                                                                                                                                                                                          ### Public methods                                                                                                                                                                                                          |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `abstract @`[NonNull](https://developer.android.com/reference/tools/gradle-api/8.3/null/androidx/annotation/NonNull)` `[SetProperty](https://docs.gradle.org/current/javadoc/org/gradle/api/provider/SetProperty.html)`<@`[NonNull](https://developer.android.com/reference/tools/gradle-api/8.3/null/androidx/annotation/NonNull)` `[String](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html)`>` | [getExcludes](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/variant/Instrumentation#getExcludes())`()` The set of glob patterns to exclude from instrumentation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `abstract void`                                                                                                                                                                                                                                                                                                                                                                                                                      | [setAsmFramesComputationMode](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/variant/Instrumentation#setAsmFramesComputationMode(com.android.build.api.instrumentation.FramesComputationMode))`(@`[NonNull](https://developer.android.com/reference/tools/gradle-api/8.3/null/androidx/annotation/NonNull)` `[FramesComputationMode](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/instrumentation/FramesComputationMode)` mode)` Sets the frame computation mode that will be applied to the bytecode of the classes instrumented by ASM visitors registered through[transformClassesWith](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/variant/Instrumentation#transformClassesWith(java.lang.Class,com.android.build.api.instrumentation.InstrumentationScope,kotlin.Function1)).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `abstract void`                                                                                                                                                                                                                                                                                                                                                                                                                      | `<ParamT extends `[InstrumentationParameters](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/instrumentation/InstrumentationParameters)`> `[transformClassesWith](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/variant/Instrumentation#transformClassesWith(java.lang.Class,com.android.build.api.instrumentation.InstrumentationScope,kotlin.Function1))`(` ` @`[NonNull](https://developer.android.com/reference/tools/gradle-api/8.3/null/androidx/annotation/NonNull)` `[Class](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Class.html)`<@`[NonNull](https://developer.android.com/reference/tools/gradle-api/8.3/null/androidx/annotation/NonNull)` `[AsmClassVisitorFactory](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/instrumentation/AsmClassVisitorFactory)`<@`[NonNull](https://developer.android.com/reference/tools/gradle-api/8.3/null/androidx/annotation/NonNull)` ParamT>> classVisitorFactoryImplClass,` ` @`[NonNull](https://developer.android.com/reference/tools/gradle-api/8.3/null/androidx/annotation/NonNull)` `[InstrumentationScope](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/instrumentation/InstrumentationScope)` scope,` ` @`[NonNull](https://developer.android.com/reference/tools/gradle-api/8.3/null/androidx/annotation/NonNull)` Function1<@`[NonNull](https://developer.android.com/reference/tools/gradle-api/8.3/null/androidx/annotation/NonNull)` ParamT, `[Unit](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)`> instrumentationParamsConfig` `)` Registers an asm class visitor to instrument the classes defined by the given scope. |

## Public methods

### getExcludes

```
abstract @NonNull SetProperty<@NonNull String> getExcludes()
```

The set of glob patterns to exclude from instrumentation. Classes matching any of these patterns in the project sources and dependencies jars do not get instrumented by any[AsmClassVisitorFactory](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/instrumentation/AsmClassVisitorFactory)registered via[transformClassesWith](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/variant/Instrumentation#transformClassesWith(java.lang.Class,com.android.build.api.instrumentation.InstrumentationScope,kotlin.Function1)).

Do not add the file extension to the end as the filtration is done on compiled classes and the`.class`suffix is not included in the pattern matching.

Example usage:  

```mysql
androidComponents {
    onVariants(selector().all(), {
        instrumentation.excludes.add("com`/`example`/`donotinstrument`/`**")
        instrumentation.excludes.add("**`/`*Test")
    })
}
```  

### setAsmFramesComputationMode

```
abstract void setAsmFramesComputationMode(@NonNull FramesComputationMode mode)
```

Sets the frame computation mode that will be applied to the bytecode of the classes instrumented by ASM visitors registered through[transformClassesWith](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/variant/Instrumentation#transformClassesWith(java.lang.Class,com.android.build.api.instrumentation.InstrumentationScope,kotlin.Function1)). The default mode is to[copy frames](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/instrumentation/FramesComputationMode#COPY_FRAMES).

When setting this multiple times, the mode with the highest enum value will be selected.  

### transformClassesWith

```
abstract void <ParamT extends InstrumentationParameters> transformClassesWith(
    @NonNull Class<@NonNull AsmClassVisitorFactory<@NonNull ParamT>> classVisitorFactoryImplClass,
    @NonNull InstrumentationScope scope,
    @NonNull Function1<@NonNull ParamT, Unit> instrumentationParamsConfig
)
```

Registers an asm class visitor to instrument the classes defined by the given scope. An instance of the factory will be instantiated and used to create visitors for each class.

Example:  

```scdoc
androidComponents {
    onVariants(selector().all(), {
        instrumentation.transformClassesWith(AsmClassVisitorFactoryImpl.class,
                                             InstrumentationScope.Project) { params ->
            params.x = "value"
        }
        instrumentation.setAsmFramesComputationMode(COMPUTE_FRAMES_FOR_INSTRUMENTED_METHODS)
    })
}
```  

|                                                                                                                                                                                                                                                                                                             Parameters                                                                                                                                                                                                                                                                                                              |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `@`[NonNull](https://developer.android.com/reference/tools/gradle-api/8.3/null/androidx/annotation/NonNull)` `[Class](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Class.html)`<@`[NonNull](https://developer.android.com/reference/tools/gradle-api/8.3/null/androidx/annotation/NonNull)` `[AsmClassVisitorFactory](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/instrumentation/AsmClassVisitorFactory)`<@`[NonNull](https://developer.android.com/reference/tools/gradle-api/8.3/null/androidx/annotation/NonNull)` ParamT>> classVisitorFactoryImplClass` | the factory class implementing[AsmClassVisitorFactory](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/instrumentation/AsmClassVisitorFactory)                                                                                                                                                                                                                                                                                                                                              |
| `@`[NonNull](https://developer.android.com/reference/tools/gradle-api/8.3/null/androidx/annotation/NonNull)` `[InstrumentationScope](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/instrumentation/InstrumentationScope)` scope`                                                                                                                                                                                                                                                                                                                                                          | either instrumenting the classes of the current project or the project and its dependencies                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `@`[NonNull](https://developer.android.com/reference/tools/gradle-api/8.3/null/androidx/annotation/NonNull)` Function1<@`[NonNull](https://developer.android.com/reference/tools/gradle-api/8.3/null/androidx/annotation/NonNull)` ParamT, `[Unit](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)`> instrumentationParamsConfig`                                                                                                                                                                                                                                                                             | the configuration function to be applied to the instantiated[InstrumentationParameters](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/instrumentation/InstrumentationParameters)object before passed to[AsmClassVisitorFactory.createClassVisitor](https://developer.android.com/reference/tools/gradle-api/8.3/null/com/android/build/api/instrumentation/AsmClassVisitorFactory#createClassVisitor(com.android.build.api.instrumentation.ClassContext,org.objectweb.asm.ClassVisitor)). |