diff --git a/dd-java-agent/instrumentation/aws-java-sdk-1.11.0/src/main/java/datadog/trace/instrumentation/aws/v0/AwsSdkModule.java b/dd-java-agent/instrumentation/aws-java-sdk-1.11.0/src/main/java/datadog/trace/instrumentation/aws/v0/AwsSdkModule.java index 499ba1f9cea..b237a8b70b0 100644 --- a/dd-java-agent/instrumentation/aws-java-sdk-1.11.0/src/main/java/datadog/trace/instrumentation/aws/v0/AwsSdkModule.java +++ b/dd-java-agent/instrumentation/aws-java-sdk-1.11.0/src/main/java/datadog/trace/instrumentation/aws/v0/AwsSdkModule.java @@ -7,6 +7,7 @@ import java.util.List; import java.util.Map; +/** Groups the instrumentations for AWS SDK 1.11.0+. */ @AutoService(InstrumenterModule.class) public final class AwsSdkModule extends InstrumenterModule.Tracing { diff --git a/docs/how_instrumentations_work.md b/docs/how_instrumentations_work.md index 2fcb8c48bde..ea7b63b977e 100644 --- a/docs/how_instrumentations_work.md +++ b/docs/how_instrumentations_work.md @@ -101,7 +101,7 @@ At this point the instrumentation should override the method `muzzleDirective()` ## Instrumentation classes -The Instrumentation class is where the Instrumentation begins. It will: +The Instrumentation class is where the instrumentation begins. It will: 1. Use Matchers to choose target types (i.e., classes) 2. From only those target types, use Matchers to select the members (i.e., methods) to instrument. @@ -110,8 +110,9 @@ The Instrumentation class is where the Instrumentation begins. It will: Instrumentation classes: 1. Must be annotated with `@AutoService(InstrumenterModule.class)` -2. Should extend one of the six abstract TargetSystem `InstrumenterModule` classes -3. Should implement one of the `Instrumenter` interfaces +2. Should be declared in a file that ends with `Instrumentation.java` +3. Should extend one of the six abstract TargetSystem `InstrumenterModule` classes +4. Should implement one of the `Instrumenter` interfaces For example: @@ -136,6 +137,31 @@ public class RabbitChannelInstrumentation extends InstrumenterModule.Tracing | `InstrumenterModule.`[`Usm`](https://github.com/DataDog/dd-trace-java/blob/82a3400cd210f4051b92fe1a86cd1b64a17e005e/dd-java-agent/agent-tooling/src/main/java/datadog/trace/agent/tooling/InstrumenterModule.java#L273) | | | [`InstrumenterModule`](https://github.com/DataDog/dd-trace-java/blob/82a3400cd210f4051b92fe1a86cd1b64a17e005e/dd-java-agent/agent-tooling/src/main/java/datadog/trace/agent/tooling/InstrumenterModule.java) | Avoid extending `InstrumenterModule` directly. When no other TargetGroup is applicable we generally default to `InstrumenterModule.Tracing` | +### Grouping Instrumentations + +Related instrumentations may be grouped under a single `InstrumenterModule` to share common details +such as integration name, helpers, context store use, and optional `classLoaderMatcher()`. + +Module classes: + +1. Must be annotated with `@AutoService(InstrumenterModule.class)` +2. Should be declared in a file that ends with `Module.java` +3. Should extend one of the six abstract TargetSystem `InstrumenterModule` classes +4. Should have a `typeInstrumentations()` method that returns the instrumentations in the group +5. Should NOT implement one of the `Instrumenter` interfaces + +> [!WARNING] +> Grouped instrumentations must NOT be annotated with `@AutoService(InstrumenterModule.class) +> and must NOT extend any of the six abstract TargetSystem `InstrumenterModule` classes + +Existing instrumentations can be grouped under a new module, assuming they share the same integration name. + +For each member instrumentation: +1. Remove `@AutoService(InstrumenterModule.class)` +2. Remove `extends InstrumenterModule...` +3. Move the list of helpers to the module, merging as necessary +4. Move the context store map to the module, merging as necessary + ### Type Matching Instrumentation classes should implement an