Skip to content

feat(observability): add the legacy libs migration skill - #2

Open
jbachorik wants to merge 1 commit into
mainfrom
agent/btrace-legacy-libs-migration
Open

feat(observability): add the legacy libs migration skill#2
jbachorik wants to merge 1 commit into
mainfrom
agent/btrace-legacy-libs-migration

Conversation

@jbachorik

Copy link
Copy Markdown
Contributor

Completes the skill half of btraceio/btrace#906.

Summary

Adds btrace-legacy-libs-migration to the btrace-observability plugin, for moving custom system
support off the retired libs/profile packaging and into an extension.

It sits in this plugin rather than a new one because the two adjacent skills already live here and
answer different questions — btrace-extensions-and-permissions covers whether an extension is
warranted, btrace-startup-and-packaging covers fat agents — and the coordinator's routing table
can only reference skills in its own plugin.

Written from running the migration, not from reading about it

The guidance was drafted from the BTrace source first. Walking it end to end against a live JVM
contradicted that draft in several places, and the skill reflects what actually happened:

  • One project, not two modules. BTrace's own migration documentation described separate API and
    impl modules. 3.0 extensions are a single Gradle project with one src/main/java that the
    plugin partitions from the declared services. A migrator following the old text builds two
    modules and finds nowhere to apply the plugin.
  • Shading artifacts are not your services. A newly created extension declaring no provider file
    still shipped META-INF/services/javax.annotation.processing.Processor and
    org.slf4j.spi.SLF4JServiceProvider in its implementation artifact. Their presence says nothing
    about the extension's wiring; the declared services in the API manifest are what the runtime
    reads.
  • The most likely failure, observed. With the implementation moved into an impl subpackage
    and no provider file — the tidy-up a migrator naturally performs — the extension built,
    installed and loaded, then injection failed with
    No implementation available for service (interface returned). Moving it into the interface's
    package fixed it and the probe printed through the injected service.
  • Grants live in permissions.properties, not extensions.conf, which only enables and
    disables.
  • Injection throws by default, so marking an injection optional or selecting shim mode is what
    turns an unfinished migration into something that looks complete.

Also included

  • Routing rows in the coordinator and the plugin README.
  • An eval case whose mustAvoid names the wrong answers stale material tends to produce: an
    "API module" split, and extensions.conf for permission grants.
  • Two references/btrace-source-facts.txt pins on the manifest attribute names, so the skill fails
    validation if that documentation moves. Deliberately pinned to a document the companion BTrace PR
    does not touch — CI checks out BTrace at default-branch tip, so pinning text under edit would
    turn this repository red the moment that PR merged.

Verification

scripts/validate-marketplace.sh passes: 8 eval cases, 2 plugins, 13 skills.

Both gates were also confirmed to actually fail before trusting the green run — malformed front
matter is rejected, and a github.com/btraceio/btrace/blob/ link produces
error: copy operational guidance into skills; do not link to BTrace source docs. The blob-link
gate had to be exercised on its own, because the front-matter failure aborts the script before it
is reached.

Companion

btraceio/btrace#929 retires the mechanism this skill migrates away from, and corrects the
documentation that described it as working. The BTrace-side cross-reference to this skill lands
once this merges and there is a published path to point at.

The libs=<profile> mechanism has been retired in BTrace, so a target still
passing it loads nothing and the missing classes surface later as a probe
failing on a type it used to see. Nothing in the suite covered that, and the
two adjacent skills answer different questions: extensions-and-permissions
covers whether an extension is warranted, startup-and-packaging covers fat
agents.

The guidance is written from walking the migration against a running JVM rather
than from reading the source, which changed several points:

- Extensions are one project with a single source set partitioned by the
  plugin, not the separate API and impl modules the migration documentation
  described.
- Provider files for shaded dependencies appear in every built implementation
  artifact. A newly created extension that declares none still ships two, so
  their presence says nothing about the extension's own wiring; the declared
  services in the API manifest are what the runtime reads.
- Moving implementations into an impl subpackage without a provider file breaks
  the naming convention and fails at injection with "No implementation
  available for service (interface returned)" after the extension has built,
  installed and loaded cleanly. This is the failure a migrator is most likely
  to cause while tidying up.
- Permission grants live in permissions.properties; extensions.conf only
  enables and disables.
- Injection throws by default, so opting into shim mode or optional injection
  is what makes an unfinished migration look complete.

Pin the manifest attribute names so the skill fails validation if that
documentation changes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant