feat(observability): add the legacy libs migration skill - #2
Open
jbachorik wants to merge 1 commit into
Open
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Completes the skill half of btraceio/btrace#906.
Summary
Adds
btrace-legacy-libs-migrationto thebtrace-observabilityplugin, for moving custom systemsupport 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-permissionscovers whether an extension iswarranted,
btrace-startup-and-packagingcovers fat agents — and the coordinator's routing tablecan 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:
impl modules. 3.0 extensions are a single Gradle project with one
src/main/javathat theplugin partitions from the declared services. A migrator following the old text builds two
modules and finds nowhere to apply the plugin.
still shipped
META-INF/services/javax.annotation.processing.Processorandorg.slf4j.spi.SLF4JServiceProviderin its implementation artifact. Their presence says nothingabout the extension's wiring; the declared services in the API manifest are what the runtime
reads.
implsubpackageand 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'spackage fixed it and the probe printed through the injected service.
permissions.properties, notextensions.conf, which only enables anddisables.
turns an unfinished migration into something that looks complete.
Also included
mustAvoidnames the wrong answers stale material tends to produce: an"API module" split, and
extensions.conffor permission grants.references/btrace-source-facts.txtpins on the manifest attribute names, so the skill failsvalidation 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.shpasses: 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 produceserror: copy operational guidance into skills; do not link to BTrace source docs. The blob-linkgate 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.