Code review guide: instrumentation module renames

Author: trask

.github/agents/knowledge/README.md

@@ -8,7 +8,7 @@ Load only files relevant to the current scope to reduce noise and avoid over-con
 
 | File | Load when |
 | --- | --- |
-| `api-deprecation-policy.md` | Public API removal, rename, or deprecation; stable vs alpha breaking changes |
+| `api-deprecation-policy.md` | Public API removal, rename, or deprecation; stable vs alpha breaking changes; module renames that touch config keys or emitted scope names |
 | `config-property-stability.md` | `otel.instrumentation.*` property add, remove, rename, or deprecation |
 | `general-rules.md` | Always — review checklist table and core rules enforced on every review |
 | `metadata-yaml-format.md` | Always — mandatory review of metadata.yaml for config coverage |

.github/agents/knowledge/api-deprecation-policy.md

@@ -2,8 +2,23 @@
 
 ## Quick Reference
 
-- Use when: reviewing public API removals/renames, `@Deprecated` usage, stable-vs-alpha compatibility
-- Review focus: deprecate-then-remove timing, delegation direction, required Javadoc/CHANGELOG coverage
+- Use when: reviewing public API removals/renames, `@Deprecated` usage, stable-vs-alpha compatibility, or any module rename that touches user-facing config keys or emitted telemetry identity
+- Review focus: deprecate-then-remove timing, delegation direction, required Javadoc/CHANGELOG coverage, v3-preview gating for config keys and scope names
+
+## What Counts as "Public API"
+
+"API" here means **anything a user's code or configuration depends on by name**, including:
+
+- Java symbols in published artifacts (classes, methods, fields in `:library`, `:testing`,
+  `instrumentation-api*`).
+- User-facing configuration keys — `otel.instrumentation.<name>.enabled`, any
+  `otel.instrumentation.*` property, and the equivalent declarative YAML keys.
+- Outgoing telemetry identity — anything users can match on in their backend, including
+  `otel.scope.name`, span names, metric names, attribute keys, and attribute values. Users
+  build dashboards, filters, and alerts on these values, so silently renaming them is a
+  breaking change.
+
+A rename of any of these surfaces is a breaking change even if no Java symbol moved.
 
 ## When Are Breaking Changes Allowed?
 
@@ -75,6 +90,71 @@ default void configure(IgnoredTypesBuilder builder, ConfigProperties config) {
 }
 ```
 
+## Module renames: config keys and emitted scope names
+
+A module rename touches **two user-facing API surfaces** that must each be preserved by default
+and only change under `otel.instrumentation.common.v3-preview`. Both cases use
+`AgentCommonConfig.get().isV3Preview()` to gate the switch, but the mechanism differs because
+the surfaces are different: config keys can coexist as aliases, emitted scope names cannot.
+
+### 1. `InstrumentationModule` names (controls `otel.instrumentation.<name>.enabled`)
+
+The names passed to the `InstrumentationModule` constructor drive the
+`otel.instrumentation.<name>.enabled` config keys. A rename silently breaks users who have
+the old key in their config.
+
+Keep the pre-rename name as an **additional alias at the end of the list**, and drop it under
+v3-preview:
+
+```java
+public CxfInstrumentationModule() {
+  super("cxf", additionalNames());
+}
+
+private static String[] additionalNames() {
+  if (AgentCommonConfig.get().isV3Preview()) {
+    return new String[] {"jaxws-2.0-cxf-3.0", "jaxws"};
+  }
+  return new String[] {"jaxws-2.0-cxf-3.0", "jaxws", "jaxws-cxf-3.0"};
+}
+```
+
+Order matters: `AgentDistributionConfig#isInstrumentationEnabled` checks names in the order
+given and returns on the first explicit setting. Put the alias **last** so the new name wins
+when both are set.
+
+### 2. Emitted instrumentation scope name (`INSTRUMENTATION_NAME` in `*Singletons`)
+
+The `INSTRUMENTATION_NAME` string passed to `Instrumenter.builder(...)` becomes the
+`otel.scope.name` attribute on every emitted span / metric / log. A rename silently breaks
+dashboards and filters that match on the old scope.
+
+Keep emitting the **pre-rename** scope name by default, and switch to the new one only under
+v3-preview:
+
+```java
+public class CxfSingletons {
+  private static final String INSTRUMENTATION_NAME =
+      AgentCommonConfig.get().isV3Preview()
+          ? "io.opentelemetry.jaxws-2.0-cxf-3.0"
+          : "io.opentelemetry.jaxws-cxf-3.0";
+  ...
+}
+```
+
+Note the asymmetry with the config-key case: there the list contains **both** names at once
+(aliases); here only **one** scope name is emitted at a time, and the default is the **old**
+one.
+
+### CHANGELOG
+
+The rename is **not** a breaking change or a deprecation in the current release: by default
+the old config keys and scope names continue to work unchanged, and the new names are only
+visible under `otel.instrumentation.common.v3-preview` — a preview flag that users are not
+generally encouraged to enable. Do not add a `⚠️ Breaking changes to non-stable APIs` or
+`🚫 Deprecations` entry for this kind of rename.
+The breaking change will be recorded when v3-preview becomes the default in 3.0.
+
 ## What to Flag in Review
 
 - **Breaking change without a prior deprecation**: a method/class was removed or its signature
@@ -98,3 +178,7 @@ default void configure(IgnoredTypesBuilder builder, ConfigProperties config) {
 
 - **Missing CHANGELOG entry**: a breaking change PR that does not add an
   `⚠️ Breaking changes to non-stable APIs` bullet in the `Unreleased` section of `CHANGELOG.md`.
+
+- **Module rename without backcompat**: `InstrumentationModule` constructor doesn't list the
+  pre-rename name as an alias, and/or `*Singletons#INSTRUMENTATION_NAME` was changed
+  unconditionally instead of being gated on `AgentCommonConfig.get().isV3Preview()`.

.github/agents/knowledge/module-naming.md

@@ -88,6 +88,14 @@ General rules:
 - Library packages use `io.opentelemetry.instrumentation.<lib>...`
 - Internal-only classes go in a `.internal` subpackage
 
+## Renaming an existing module: backwards compatibility
+
+A module rename touches two user-facing API surfaces — the
+`otel.instrumentation.<name>.enabled` config keys and the emitted `otel.scope.name` — that
+must both be preserved by default and only change under `otel.instrumentation.common.v3-preview`.
+See [api-deprecation-policy.md](api-deprecation-policy.md#module-renames-config-keys-and-emitted-scope-names)
+for the required pattern.
+
 ## What to Flag in Review
 
 - **Module directory name missing the minimum version** for a third-party library.