From f7dd371cabf645b1bf90eb07f4813ab3b0d7cf07 Mon Sep 17 00:00:00 2001 From: Andrea Marziali Date: Mon, 1 Jun 2026 09:59:49 +0200 Subject: [PATCH 1/3] Cover documentation for config inversion json checks --- .claude/skills/add-apm-integrations/SKILL.md | 12 ++++++++++++ docs/add_new_instrumentation.md | 11 +++++++++++ 2 files changed, 23 insertions(+) diff --git a/.claude/skills/add-apm-integrations/SKILL.md b/.claude/skills/add-apm-integrations/SKILL.md index 2b8b79486ce..78907daea6b 100644 --- a/.claude/skills/add-apm-integrations/SKILL.md +++ b/.claude/skills/add-apm-integrations/SKILL.md @@ -63,6 +63,13 @@ pattern before writing new code. Use it as a template. - `testImplementation` dependencies for tests - `muzzle { pass { } }` directives (see Step 9) 4. Register the new module in `settings.gradle.kts` in **alphabetical order** +5. Register the integration name in `metadata/supported-configurations.json`. The name you pass to + the `InstrumenterModule` `super(...)` constructor maps to env var `DD_TRACE__ENABLED` + (`.` and `-` become `_`, then uppercased — e.g. `couchbase-3` → `DD_TRACE_COUCHBASE_3_ENABLED`). + Add a `boolean`/`default: "true"` entry with the two standard aliases + `DD_TRACE_INTEGRATION__ENABLED` and `DD_INTEGRATION__ENABLED`, keeping the key in + alphabetical order. A module declaring multiple names (`super("a", "b")`) needs **one entry per + name**. Omitting this fails the `checkInstrumenterModuleConfigurations` Gradle task. ## Step 5 – Write the InstrumenterModule @@ -193,11 +200,15 @@ Run these commands in order and fix any failures before proceeding: ./gradlew :dd-java-agent:instrumentation:$framework-$version:muzzle ./gradlew :dd-java-agent:instrumentation:$framework-$version:test ./gradlew :dd-java-agent:instrumentation:$framework-$version:latestDepTest +./gradlew checkInstrumenterModuleConfigurations ./gradlew spotlessCheck ``` **If muzzle fails:** check for missing helper class names in `helperClassNames()`. +**If `checkInstrumenterModuleConfigurations` fails:** an integration name from `super(...)` is missing +(or mismatched) in `metadata/supported-configurations.json` — see Step 4, item 5. + **If tests fail:** verify span lifecycle order (start → activate → error → finish → close), helper registration, and `contextStore()` map entries match actual usage. @@ -208,6 +219,7 @@ and `contextStore()` map entries match actual usage. Output this checklist and confirm each item is satisfied: - [ ] `settings.gradle.kts` entry added in alphabetical order +- [ ] `metadata/supported-configurations.json` has a `DD_TRACE__ENABLED` entry (+ the two aliases) for every name passed to `super(...)` - [ ] `build.gradle` has `compileOnly` deps and `muzzle` directives with `assertInverse = true` - [ ] `@AutoService(InstrumenterModule.class)` annotation present on the module class - [ ] `helperClassNames()` lists ALL referenced helpers (including inner, anonymous, and enum synthetic classes) diff --git a/docs/add_new_instrumentation.md b/docs/add_new_instrumentation.md index c5375eb397c..609890e335e 100644 --- a/docs/add_new_instrumentation.md +++ b/docs/add_new_instrumentation.md @@ -67,6 +67,17 @@ public class GoogleHttpClientInstrumentation extends InstrumenterModule.Tracing } ``` +> [!IMPORTANT] +> **The instrumentation name controls a config flag that must be registered.** The name passed to +> `super(...)` becomes the config key `dd.trace..enabled` → environment variable +> `DD_TRACE__ENABLED` (`.` and `-` become `_`, then uppercased — e.g. `couchbase-3` → +> `DD_TRACE_COUCHBASE_3_ENABLED`). Every such name must be registered in +> `metadata/supported-configurations.json` with the two standard aliases +> (`DD_TRACE_INTEGRATION__ENABLED` and `DD_INTEGRATION__ENABLED`), or the +> `checkInstrumenterModuleConfigurations` Gradle task fails the build. A module declaring multiple +> names (`super("a", "b")`) needs **one entry per name**. See +> [Add new configurations](./add_new_configurations.md) for the JSON entry shape. + ## Match the target class In this case we target only one known class to instrument. This is the class which contains the method this From e1b298f561142c829a11a6d5a6345ce40ad0df51 Mon Sep 17 00:00:00 2001 From: Andrea Marziali Date: Mon, 1 Jun 2026 10:08:32 +0200 Subject: [PATCH 2/3] precisions --- .claude/skills/add-apm-integrations/SKILL.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/.claude/skills/add-apm-integrations/SKILL.md b/.claude/skills/add-apm-integrations/SKILL.md index 78907daea6b..e5ae11109ae 100644 --- a/.claude/skills/add-apm-integrations/SKILL.md +++ b/.claude/skills/add-apm-integrations/SKILL.md @@ -63,13 +63,14 @@ pattern before writing new code. Use it as a template. - `testImplementation` dependencies for tests - `muzzle { pass { } }` directives (see Step 9) 4. Register the new module in `settings.gradle.kts` in **alphabetical order** -5. Register the integration name in `metadata/supported-configurations.json`. The name you pass to - the `InstrumenterModule` `super(...)` constructor maps to env var `DD_TRACE__ENABLED` - (`.` and `-` become `_`, then uppercased — e.g. `couchbase-3` → `DD_TRACE_COUCHBASE_3_ENABLED`). - Add a `boolean`/`default: "true"` entry with the two standard aliases - `DD_TRACE_INTEGRATION__ENABLED` and `DD_INTEGRATION__ENABLED`, keeping the key in - alphabetical order. A module declaring multiple names (`super("a", "b")`) needs **one entry per - name**. Omitting this fails the `checkInstrumenterModuleConfigurations` Gradle task. +5. Register the integration name in `metadata/supported-configurations.json`, or + `checkInstrumenterModuleConfigurations` fails. The name in `super(...)` maps to env var + `DD_TRACE__ENABLED` (`.` and `-` become `_`, uppercased — `couchbase-3` → + `DD_TRACE_COUCHBASE_3_ENABLED`). Add a `"type": "boolean"` entry, in alphabetical order, with + aliases `DD_TRACE_INTEGRATION__ENABLED` and `DD_INTEGRATION__ENABLED`. Set `default` + to the module's real default — `"true"`, or `"false"` if it overrides `defaultEnabled()` (e.g. + OpenTelemetry, Hazelcast); the task won't catch a wrong default, but it ships misleading + metadata. Declaring several names (`super("a", "b")`) means one entry each. ## Step 5 – Write the InstrumenterModule From 1812e7b82ad3745531e648cf4c3b2658f052d416 Mon Sep 17 00:00:00 2001 From: Andrea Marziali Date: Mon, 1 Jun 2026 12:49:27 +0200 Subject: [PATCH 3/3] remove unneeded info --- .claude/skills/add-apm-integrations/SKILL.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.claude/skills/add-apm-integrations/SKILL.md b/.claude/skills/add-apm-integrations/SKILL.md index e5ae11109ae..6b0e57414b0 100644 --- a/.claude/skills/add-apm-integrations/SKILL.md +++ b/.claude/skills/add-apm-integrations/SKILL.md @@ -69,8 +69,7 @@ pattern before writing new code. Use it as a template. `DD_TRACE_COUCHBASE_3_ENABLED`). Add a `"type": "boolean"` entry, in alphabetical order, with aliases `DD_TRACE_INTEGRATION__ENABLED` and `DD_INTEGRATION__ENABLED`. Set `default` to the module's real default — `"true"`, or `"false"` if it overrides `defaultEnabled()` (e.g. - OpenTelemetry, Hazelcast); the task won't catch a wrong default, but it ships misleading - metadata. Declaring several names (`super("a", "b")`) means one entry each. + OpenTelemetry, Hazelcast). Declaring several names (`super("a", "b")`) means one entry each. ## Step 5 – Write the InstrumenterModule