Repository navigation
Conversation
|
Tick the box to add this pull request to the merge queue (same as
|
🤖 GitHub commentsJust comment with:
|
There was a problem hiding this comment.
🟡 Changes recommended
The skill guide still recommends invalid span-type fallbacks, a JAR glob that prevents packaged-agent inspection, and a deprecated test runner incompatible with JUnit Jupiter suites.
3 open issues
What changed in this PR
Adds a reusable skill for developing and reviewing built-in Elastic APM Java instrumentation plugins. This PR changes development guidance only, not production behavior, APIs, or configuration.
Changes:
- Documents instrumentation selection, compatibility boundaries, class-loader safety, and span lifecycles.
- Covers telemetry semantics, sensitive-content handling, and metrics.
- Defines testing, agent assembly verification, documentation, and PR completion guidance.
| File | Description |
|---|---|
.agents/skills/create-java-agent-instrumentation-plugin/SKILL.md |
Adds end-to-end guidance and checklists for built-in instrumentation plugin development. |
Review effort: Balanced
|
|
||
| Do not invent a second field for data already represented by a standard attribute without a documented compatibility reason. | ||
|
|
||
| Keep semantic attributes separate from the agent's internal span taxonomy. External library values may be appropriate for attributes such as `db.system` or service-target metadata but invalid as APM `span.type`, `span.subtype`, or `span.action`. Check the repository's allowed span-type schema; use a schema-defined generic value such as `unknown` when no reliable mapping exists, and preserve the raw value only in an unconstrained semantic field. |
| Then verify that the packaged agent contains the transformed plugin classes/service entries and launch it once: | ||
|
|
||
| ```bash | ||
| unzip -l elastic-apm-agent/target/elastic-apm-agent-*.jar | rg '<plugin-package|plugin-artifact>' |
| The repository uses several complementary patterns: | ||
|
|
||
| 1. **In-process instrumentation tests.** Most library plugins extend `AbstractInstrumentationTest`, execute the real library API with Byte Buddy instrumentation active, and assert against `MockReporter`. Prefer this for matcher/advice behavior, span fields, context propagation, errors, configuration changes, and library calls that do not require packaging boundaries. | ||
| 2. **Isolated dependency-version tests.** Use the repository's dependency-loading test runner, such as `JUnit4TestClassWithDependencyRunner`, when the same behavioral suite must run against multiple library versions or when the application class path could hide class-loader problems. Explicitly include split transitive artifacts required by newer versions. |
There was a problem hiding this comment.
Yes, using TestClassWithDependencyRunner is preferred, migrating existing usages of the junit4 runner is not necessary.
| - It is high enough in the stack to avoid provider-specific duplication, but low enough to run for all intended entry paths. | ||
| - It runs once per logical operation. Watch for overload delegation, default methods, wrappers, retries, and implementations calling other instrumented methods. | ||
| - It preserves downstream work beneath the new span when a nested HTTP, database, or messaging span should be its child. | ||
| - It can be matched narrowly and cheaply. |
There was a problem hiding this comment.
For example, ideally the matching should be on FQN class/method name, use heuristics on name to make matching efficient, and rely on class hierarchy only when the number of classes has been reduced to a small number.
|
|
||
| Prefer a stable framework abstraction or canonical implementation method over: | ||
|
|
||
| - controllers or application code, which miss non-web use; |
There was a problem hiding this comment.
what does "non-web use" mean ?
| Prefer a stable framework abstraction or canonical implementation method over: | ||
|
|
||
| - controllers or application code, which miss non-web use; | ||
| - low-level network calls, which lose framework semantics and duplicate existing HTTP instrumentation; |
There was a problem hiding this comment.
| - low-level network calls, which lose framework semantics and duplicate existing HTTP instrumentation; | |
| - low-level network calls, which lose framework semantics and might duplicate existing framework instrumentation like HTTP or database clients. |
| - constructors, getters, builders, or hot utility methods without a logical operation boundary; | ||
| - internal implementation classes that vary by provider or patch release. | ||
|
|
||
| When an interface declares the operation, instrument concrete implementations with `hasSuperType(...)` and exclude interfaces. Add a cheap name-based prefilter when practical. Match the exact method name, argument count, argument types, return type, and relevant modifiers so unrelated overloads are not transformed. |
There was a problem hiding this comment.
when the implementation uses a nested method call, prefer to instrument the overload that is being delegated to as it will allow to instrument all overloads at once.
|
|
||
| When an interface declares the operation, instrument concrete implementations with `hasSuperType(...)` and exclude interfaces. Add a cheap name-based prefilter when practical. Match the exact method name, argument count, argument types, return type, and relevant modifiers so unrelated overloads are not transformed. | ||
|
|
||
| Test that one application call creates exactly one intended span. |
There was a problem hiding this comment.
where does this requirement comes from ?
|
|
||
| Test that one application call creates exactly one intended span. | ||
|
|
||
| Do not add call-depth suppression merely because wrappers might exist. First reproduce a wrapper or overload delegating into another matched method and assert the duplicate spans. If duplication is real, add a shared `CallDepth` guard, decrement it on every exit path including exceptions and no-span paths, and keep the regression test proving that only the outer logical call is reported. |
There was a problem hiding this comment.
In the case where nested method calls should be avoided as they produce duplicate or nested spans, use the CallDepth to guard and only create a span in the outer method call.
|
|
||
| The marker must distinguish the supported line from older versions that contain the common API. Put shared guards in a common base instrumentation so every instrumentation in the plugin uses the same boundary. | ||
|
|
||
| Add isolated compatibility tests that load dependency jars with a dedicated `URLClassLoader`, preferably with a `null` parent, and assert: |
There was a problem hiding this comment.
Use OpenTelemetryVersionIT test class as an example how to create tests to test multiple versions in a isolated way.

What does this PR do?
Adds a reusable agent skill for designing, implementing, validating, documenting, and reviewing built-in Elastic APM Java instrumentation plugins.
The skill is discoverable under
.agents/skills/create-java-agent-instrumentation-plugin/and captures repository-specific guidance for:The guidance incorporates lessons learned while implementing and reviewing the Spring AI instrumentation, but is intentionally technology-independent.
This PR changes only agent-development guidance. It does not modify production agent behavior, APIs, configuration, or supported technologies.
Checklist
I have updated CHANGELOG.next-release.md— Not applicable; this adds development guidance without changing agent behavior.