Harden error handling, unify logging, add OpenTelemetry extension, and improve docs

[jbachorik]

Summary

Systematic project-wide review of the BTrace codebase resulting in 10 improvements across error handling, logging, CI, code quality, documentation, and observability.

Error handling & reliability

• Fix 30+ swallowed exceptions across 7 modules (compiler, client, ext-cli, extension loader) — silent catch (Exception ignored) {} blocks now log at DEBUG level via SLF4J, making failures diagnosable without impacting production performance
• Fix resource leaks — DOTWriter leaks FileOutputStream if PrintStream construction fails; PCPP #include reader is never closed. Both converted to safe resource management
• Replace 4 production assert statements with IllegalStateException null checks in BTraceRuntimeAccessImpl, InstrumentingMethodVisitor, Indy, and Client — assert is silently disabled by default in production JVMs
• Preserve exception chains — CompilerClassWriter was throwing new RuntimeException(e.toString()), discarding the entire causal stack trace. Now wraps with descriptive message and original cause
• Use specific exception types — IllegalArgumentException for invalid command types (WireIO), IllegalStateException for class loading failures (RemoteClient), replacing bare RuntimeException

Logging

• Replace System.err.println with SLF4J in 7 infrastructure modules: Instrumentor, ClassFilter, BTraceMethodNode, BTraceRuntimeAccessImpl, Printer, MethodInvocationRecorder, CompilerClassWriter. Unifies log output under the standard logging framework and respects log level configuration. Intentional CLI output (usage messages, ProbePrinter) and bootstrap module code (btrace-boot, which has no SLF4J dependency) are left unchanged.

CI/CD

• Add dependency vulnerability scanning — new dependency-review job in continuous.yml using actions/dependency-review-action@v4, runs on PRs, fails on high-severity CVEs, posts summary comment

Code quality

• Implement BTraceMBean array type support — typeToOpenType() had a FIXME: This is highly incomplete for array types. Now handles arrays of simple types via ArrayType
• Clean up PCPP comments — replace !!HACK!! marker and ambiguous FIXME with accurate descriptions of the actual logic

Documentation

• Update version references from 2.x to 3.0.0 in BTraceTutorial.md (header) and GettingStarted.md (JBang example, Docker install paths)
• Add GraalVM Native Image compatibility guide (docs/GraalVMSupport.md) — documents why Native Image is incompatible (no Instrumentation API, no runtime bytecode generation, closed-world assumption), available workarounds (JIT mode, build-time script validation), and deployment recommendations per stage

New feature: OpenTelemetry extension

New btrace-otel extension module following the established extension pattern (api/impl split, @ExtensionDescriptor, @ServiceDescriptor).

• API: span(name, durationNanos), span(name, attrKey, attrValue, durationNanos), counter(name, value), gauge(name, value)
• Transport: OTLP/HTTP+JSON via raw HttpURLConnection — zero external dependencies beyond SLF4J
• Buffering: Lock-free ConcurrentLinkedQueue with configurable async background flush (default 5s interval, 256 batch size)
• Configuration: System properties btrace.otel.endpoint (default http://localhost:4318), btrace.otel.service.name, btrace.otel.flush.interval.ms, btrace.otel.batch.size
• Compatible with: Jaeger, Grafana Tempo, Datadog, any OTLP-compatible collector

Commit breakdown

Commit	Description	Files changed
f80f575	Fix 30+ swallowed exceptions with SLF4J debug logging	7
a8831d9	Fix resource leaks with try-with-resources	2
23e0bde	Replace production assertions with proper null checks	4
fabc809	Replace System.err.println with SLF4J logging	7
e708a8d	Add dependency vulnerability scanning to CI	1
2aa90fe	Improve exception messages and types	5
109e492	Address FIXME/HACK comments in BTraceMBean and PCPP	2
b286ad4	Update documentation version references to 3.0.0	2
6fbada8	Add OpenTelemetry extension module	5
c3c5ea4	Add GraalVM Native Image compatibility documentation	1

Total: 33 files changed, +870 −85

Test plan

• ./gradlew compileJava — verify clean compilation across all modules including btrace-otel
• ./gradlew test — full test suite passes
• btrace-otel produces both -api.jar and shadow impl JAR
• CI dependency-review job triggers on this PR
• Spot-check: run with -Dorg.slf4j.simpleLogger.defaultLogLevel=debug to confirm previously-swallowed exceptions now appear in logs
• GraalVMSupport.md renders correctly on GitHub

https://claude.ai/code/session_01UDRNChW9GhRia9L7sa6yum

---

This change is 

[github-actions]

Dependency Review

The following issues were found:

• ✅ 0 vulnerable package(s)
• ✅ 0 package(s) with incompatible licenses
• ✅ 0 package(s) with invalid SPDX license definitions
• ⚠️ 1 package(s) with unknown licenses.

See the Details below.

Snapshot Warnings

⚠️: No snapshots were found for the head SHA b8683e9.

Ensure that dependencies are being submitted on PR branches and consider enabling retry-on-snapshot-warnings. See the documentation for more information and troubleshooting advice.

License Issues

.github/workflows/continuous.yml

Package	Version	License	Issue Type
actions/dependency-review-action	4.*.*	Null	Unknown License

OpenSSF Scorecard

Package	Version	Score	Details
actions/actions/dependency-review-action	4.*.*	🟢 7.8	Details Check Score Reason Security-Policy 🟢 9 security policy file detected Code-Review 🟢 10 all changesets reviewed Binary-Artifacts 🟢 10 no binaries found in the repo Dangerous-Workflow 🟢 10 no dangerous workflow patterns detected Packaging ⚠️ -1 packaging workflow not detected Token-Permissions 🟢 9 detected GitHub workflow tokens with excessive permissions Maintained 🟢 10 30 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10 CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected Pinned-Dependencies ⚠️ 1 dependency not pinned by hash detected -- score normalized to 1 Fuzzing ⚠️ 0 project is not fuzzed License 🟢 10 license file detected Signed-Releases ⚠️ -1 no releases found Branch-Protection 🟢 6 branch protection is not maximal on development and all release branches SAST 🟢 10 SAST tool is run on all commits

Scanned Files

• .github/workflows/continuous.yml