Clarify singleton accessor rule only applies to zero-arg field accessors

Author: trask

.github/agents/knowledge/javaagent-singletons-patterns.md

@@ -17,7 +17,9 @@ Javaagent modules keep shared `Instrumenter` instances and related collaborators
   `"io.opentelemetry.<module-name>"`.
 - For exported collaborators, keep the field `private`, use a lower camel case field name, and
   give the accessor method the exact same name as the field. Do not prefix these accessors with
-  `get`.
+  `get`. This rule applies only to zero-arg methods that directly return a stored singleton
+  field; methods that take arguments or compute a value are not singleton accessors and keep
+  their normal names (including `get*` when appropriate).
   - `instrumenter` -> `instrumenter()`
   - `helper` -> `helper()`
   - `setter` -> `setter()`
@@ -34,6 +36,9 @@ Javaagent modules keep shared `Instrumenter` instances and related collaborators
 - Keep verb-named helper methods as verbs when they perform work instead of returning a stored
   field. These methods are not singleton accessors and should not be static imported under this
   rule.
+- Methods on a `*Singletons` class that take arguments (for example `addressAndPort(client)` or
+  `getAddressAndPort(client)`) are not singleton accessors. Do not apply the field-style
+  accessor naming rule to them, and do not flag their `get*` prefix on that basis.
 
 ## Preferred Pattern
 
@@ -103,7 +108,8 @@ class MyInstrumentation implements TypeInstrumentation {
   final` field would be clearer and matches the naming guidance, including semantic keys/handles
   and immutable value constants.
 - Accessor methods named `getInstrumenter()`, `getHelper()`, `getSetter()`, and similar when they
-  simply return a backing field.
+  simply return a backing field. Do not flag `get*`-prefixed methods that take arguments or
+  compute a value rather than returning a stored singleton field.
 - Call sites that qualify singleton accessor or uppercase constant-like field usage with the holder
   class instead of static importing the accessor or field.
 - Static imports of non-accessor helper methods on a `*Singletons` class when the method performs

.github/agents/knowledge/metadata-yaml-format.md

@@ -48,9 +48,11 @@ For `otel.instrumentation.*` properties not in SPECIAL_MAPPINGS:
 
 1. Strip `otel.instrumentation.` prefix
 2. Replace `-` with `_` (kebab-case → snake_case)
-3. Handle `experimental`:
-   - `experimental.` path segment → remove, add `/development` to next segment
-   - `experimental-` in name → add `/development` to that segment
+3. Handle `experimental` per path segment:
+
+- a segment that is exactly `experimental` is removed, and `/development` is appended to the following segment
+- a segment that already contains `experimental` keeps that text in the segment name, and `/development` is appended to that same segment
+
 4. Prepend `java.`
 
 Examples:
@@ -59,6 +61,7 @@ Examples:
 |------------------------------------------------------------------------------|-------------------------------------------------------------|
 | `otel.instrumentation.grpc.emit-message-events`                              | `java.grpc.emit_message_events`                             |
 | `otel.instrumentation.grpc.experimental-span-attributes`                     | `java.grpc.experimental_span_attributes/development`        |
+| `otel.instrumentation.http.client.emit-experimental-telemetry`               | `java.http.client.emit_experimental_telemetry/development`  |
 | `otel.instrumentation.logback-appender.experimental.capture-code-attributes` | `java.logback_appender.capture_code_attributes/development` |
 | `otel.instrumentation.common.experimental.controller-telemetry.enabled`      | `java.common.controller_telemetry/development.enabled`      |
 
@@ -81,9 +84,19 @@ Add `examples` only for module-specific configs with non-obvious format (lists,
 
 ### 1. Validate experimental markers match
 
-- `/development` in declarative_name ↔ `experimental` in flat name (MUST match both ways)
+- `/development` in `declarative_name` means the flat property must be experimental, but there are two valid shapes:
+- standalone `experimental` segment before the target segment:
+  `java.common.controller_telemetry/development.enabled` ↔ `otel.instrumentation.common.experimental.controller-telemetry.enabled`
+- `experimental` already embedded in the target segment:
+  `java.grpc.experimental_span_attributes/development` ↔ `otel.instrumentation.grpc.experimental-span-attributes`
+- another embedded example:
+  `java.http.client.emit_experimental_telemetry/development` ↔ `otel.instrumentation.http.client.emit-experimental-telemetry`
 - WRONG: `otel.instrumentation.servlet.capture-request-parameters` + `java.servlet.capture_request_parameters/development`
+- WRONG: `otel.instrumentation.grpc.span-attributes` + `java.grpc.experimental_span_attributes/development`
 - RIGHT: `otel.instrumentation.servlet.experimental.capture-request-parameters` + `java.servlet.capture_request_parameters/development`
+- RIGHT: `otel.instrumentation.grpc.experimental-span-attributes` + `java.grpc.experimental_span_attributes/development`
+
+This matches `translateName()` in `ConfigPropertiesBackedDeclarativeConfigProperties`: when a `/development` segment already contains `experimental`, do not insert an extra `experimental.` path segment in the flat property.
 
 ### 2. Verify config is used