{"owner":"btraceio","repo":"btrace","hasSkills":true,"totalSkillsCount":5,"totalTokensCount":3513,"categories":["root-instruction","claude-rule","copilot-instructions","plugin-manifest"],"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md",".github/copilot-instructions.md","btrace-extensions/examples/btrace-spark/README.md","btrace-extensions/examples/btrace-hadoop/README.md"],"skills":{"AGENTS.md":"# Repository Guide for Coding Agents\n\n## Start here\n\nBTrace is a Java tracing tool: the client compiles and sends a script, the agent instruments the target JVM, and the runtime emits results. The root project is a multi-module Gradle build.\n\n- `btrace-agent` — attachable agent, script lifecycle, and bytecode instrumentation/weaving\n- `btrace-compiler` — script verification and compilation\n- `btrace-runtime` / `btrace-core` — script APIs, runtime support, and protocol\n- `btrace-client` — CLI and attachment client\n- `btrace-dist` — distribution assembly; `integration-tests` — end-to-end tests\n- `btrace-extensions/*` — extension API and implementations\n\nFor the developer command reference and code-navigation pointers, see [CLAUDE.md](CLAUDE.md). For user and contributor documentation, start at [docs/README.md](docs/README.md).\n\n## Non-negotiable rules\n\n- Do not commit unless the changes are fully tested or the user explicitly requests a commit.\n- Preserve unrelated working-tree changes.\n- In Java code, import types and use simple names; do not introduce fully qualified type names in source.\n- Main code targets Java 8 and uses the Java 11 toolchain. Follow Spotless/Google Java Format.\n- Unit tests live in `src/test/java` and use `*Test`; integration tests live in `integration-tests/src/test/java`.\n- Changes to user-visible behavior that crosses modules or process boundaries must include end-to-end functional coverage in `integration-tests`; unit and component tests are required where useful but are not a substitute for exercising the real client, agent, target JVM, and protocol interaction.\n- Confirm that a new test or build gate **fails when it should**, not only that it passes. Run it against the unfixed code, or against input it must reject, and check the failure is the expected one. A check that cannot fail reports success regardless of what the code does, and reads as coverage while providing none. Where a revert is used to produce the failure, revert only the code under test: reverting too much fails for an unrelated reason and proves nothing about the behavior being asserted.\n\n## Build and verification\n\nRun Gradle with a workspace-local cache in restricted environments:\n\n```bash\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :module:test\n```\n\nDo not consume Gradle output directly. Redirect it to a file, filter it to relevant lines, then read that file. Use `spotlessCheck` for validation and `spotlessApply` only when formatting changes are intended. Build `:btrace-dist:build` before integration tests.\n\nIf a restricted network environment causes address-selection failures, add:\n\n```bash\nJAVA_TOOL_OPTIONS=\"-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv6Addresses=false\"\n```\n\n## Distribution changes\n\n`btrace.jar` is a masked single-JAR distribution. Classes must be assigned to bootstrap, agent, client, or shared sections deliberately. Any masked-JAR structure change requires:\n\n```bash\n./gradlew clean :btrace-dist:btraceJar\n```\n\nRead [Masked JAR Architecture](docs/architecture/MaskedJarArchitecture.md) before modifying its class layout or loader behavior.\n\n## Documentation placement\n\n- User-facing and contributor documentation belongs in `docs/`; keep [docs/README.md](docs/README.md) current when adding a guide.\n- Plans and session notes belong in `internal/plans/` (or `internal/superpowers/plans/`).\n- Design/requirement specs belong in `internal/specs/` (or `internal/superpowers/specs/`); libretto/muse files belong in `internal/libretti/`.\n- Never create or write to a singular `doc/` directory, or add plans, agent notes, or internal material below `docs/`.\n\n## Reference map\n\n- [Contribution workflow](CONTRIBUTING.md)\n- [Instrumentation backend selection](docs/architecture/InstrumentationBackends.md)\n- [v2 wire protocol](docs/architecture/Version2ProtocolArchitecture.md)\n- [Extension development](docs/BTraceExtensionDevelopmentGuide.md) and [interface rules](docs/ExtensionInterfaceRules.md)\n- [Troubleshooting](docs/Troubleshooting.md)\n","CLAUDE.md":"# Claude Code Guide\n\nFollow the repository-wide rules in [AGENTS.md](AGENTS.md). This file intentionally contains only Claude-specific orientation; `AGENTS.md` is the canonical operational contract.\n\n## Common commands\n\nUse a workspace-local Gradle cache when appropriate, and redirect Gradle output to a log before filtering and reading it (see [AGENTS.md](AGENTS.md#build-and-verification)).\n\n```bash\n# Distribution and all unit tests (:btrace-dist:build alone skips most module tests)\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew build\n\n# Module, test class, or formatting check\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :btrace-agent:test\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :btrace-agent:test --tests '*InstrStackTest'\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew spotlessCheck\n\n# Integration tests: build the distribution first\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew -Pintegration :integration-tests:test\n\n# Intentional instrumentation-bytecode changes only\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew test -PupdateTestData\n```\n\n## Where to look\n\n- Script compiler and verifier: `btrace-compiler`\n- Agent lifecycle and bytecode weaving: `btrace-agent` (instrumentation engine lives in its `io.btrace.instr` package)\n- Script API, runtime, and protocol: `btrace-core`, `btrace-runtime`\n- CLI: `btrace-client`; packaging: `btrace-dist`\n- Golden instrumentation data: `btrace-agent/src/test/resources/instrumentorTestData/`\n\n## Detailed references\n\n- [Documentation index](docs/README.md)\n- [Masked JAR architecture](docs/architecture/MaskedJarArchitecture.md) — required reading for distribution/class-loading changes\n- [Instrumentation backends](docs/architecture/InstrumentationBackends.md)\n- [Protocol architecture](docs/architecture/Version2ProtocolArchitecture.md)\n- [Extension development](docs/BTraceExtensionDevelopmentGuide.md)\n- [Troubleshooting](docs/Troubleshooting.md)\n",".github/copilot-instructions.md":"# GitHub Copilot Instructions for BTrace\n\n## About BTrace\nBTrace is a safe, dynamic tracing tool for the Java platform. It dynamically instruments running Java applications to inject tracing code at runtime using bytecode instrumentation.\n\n## Project Structure\n- **Gradle multi-module project** with modules named `btrace-*`\n- **Core modules**: `btrace-core`, `btrace-agent`, `btrace-runtime`, `btrace-client`, `btrace-instr`\n- **Build artifacts**: `btrace-dist` for distributions\n- **Tests**: `integration-tests/` for integration tests, `src/test/java` in modules for unit tests\n- **Documentation**: `docs/` directory\n\n## Architecture Overview\n- **btrace-agent**: Attachable Java agent with class transformer, manages script lifecycle\n- **btrace-compiler**: Verifies and compiles BTrace scripts to bytecode\n- **btrace-instr**: ASM-based instrumentation and weaving utilities\n- **btrace-runtime**: APIs for scripts (printing, timers, data collection)\n- **btrace-client**: CLI/attach tooling for sending scripts to target JVM\n- **services**: SPI for pluggable exporters (e.g., statsd)\n\n## Development Guidelines\n\n### Language & Versions\n- **Language**: Java\n- **Source/Target**: Java 8\n- **Build toolchain**: JDK 11\n- **Test framework**: JUnit Jupiter (JUnit 5)\n\n### Code Style\n- **Format**: Google Java Format enforced via Spotless\n- **Packages**: All under `io.btrace.*`\n- **Naming**: Module names follow `btrace-<component>` pattern\n- **Imports**: Order enforced; remove unused imports\n- **Comments**: Only add if they match existing style or explain complex logic\n\n### Building & Testing\n```bash\n# Full build with unit tests\n./gradlew build\n\n# Build distribution only\n./gradlew :btrace-dist:build\n\n# Run unit tests\n./gradlew test\n\n# Run integration tests (requires dist build first)\n./gradlew -Pintegration test\n\n# Format code\n./gradlew spotlessApply\n\n# Check formatting\n./gradlew spotlessCheck\n```\n\n### Important Environment Variables\n- `JAVA_HOME`: Required for builds\n- `TEST_JAVA_HOME`: Required for integration tests (typically JDK 11)\n- `BTRACE_TEST_DEBUG=true`: Enable verbose integration test output\n- `BTRACE_HOME`: Optional, points to exploded dist\n\n### Testing Best Practices\n- Unit tests: `src/test/java` with `*Test` suffix\n- Integration tests: `integration-tests/src/test/java`\n- BTrace scripts: `integration-tests/src/test/btrace`\n- Always run relevant tests after making changes\n- Update golden files when changing instrumentor: `./gradlew test -PupdateTestData`\n\n### Commit & PR Guidelines\n- **Commit style**: Conventional Commits (e.g., `feat(core): add probe`, `fix(instr): handle null arg`)\n- **Clear descriptions**: Link related issues\n- **Tests required**: Update/add tests; ensure CI passes\n- **Formatting**: Must pass `spotlessCheck`\n- **No unrelated changes**: Keep changes focused and minimal\n\n## Troubleshooting\n\n### Build Issues\n- **Attach disabled**: Remove `-XX:+DisableAttachMechanism` from target JVM\n- **Permission errors**: Attach requires same OS user as target JVM\n- **Toolchain issues**: Verify `JAVA_HOME` and `TEST_JAVA_HOME` point to valid JDKs\n\n### Restricted Environments\n```bash\n# Use workspace-local Gradle cache\nGRADLE_USER_HOME=$(pwd)/.gradle-user\n\n# Force IPv4 to avoid network interface issues\nJAVA_TOOL_OPTIONS=\"-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv6Addresses=false\"\n```\n\n## Code Generation Tips\n- **Prefer simplicity**: Simple, performant solutions over complex designs\n- **Use existing patterns**: Follow patterns from similar code in the repository\n- **Minimal changes**: Make the smallest possible changes to achieve the goal\n- **Reuse libraries**: Use ASM for bytecode, JCTools for concurrency, existing BTrace APIs\n- **No temporary files in repo**: Use `/tmp` for scratch work\n- **Security**: Never commit secrets; avoid introducing vulnerabilities\n\n## Example BTrace Script Pattern\n```java\npackage example;\nimport static io.btrace.core.BTraceUtils.*;\nimport io.btrace.core.annotations.*;\n\n@BTrace\npublic class ExampleTrace {\n  @OnMethod(clazz=\"com.example.Target\", method=\"methodName\")\n  public static void onMethod(@ProbeMethodName String method) {\n    println(\"Called: \" + method);\n  }\n}\n```\n\n## Key Dependencies\n- **ASM**: Bytecode manipulation\n- **JCTools**: High-performance concurrent data structures\n- **hppcrt**: Optimized collections\n- **JUnit Jupiter**: Testing framework\n\n## Additional Resources\n- Full guidelines: See `AGENTS.md` in repository root\n- Tutorial: `docs/BTraceTutorial.md`\n- Binary releases: https://github.com/btraceio/btrace/releases\n","btrace-extensions/examples/btrace-spark/README.md":"# BTrace Spark Example (Provided-Style Extension)\n\nThis example demonstrates a provided-style BTrace extension for Apache Spark that:\n- Exposes a minimal API on bootstrap (`org.example.btrace.spark.api.SparkApi`).\n- Loads implementation in an isolated classloader (no system/boot CL injection).\n- Resolves Spark classes at runtime using object hand-off and the application’s defining class loader.\n- Caches reflective MethodHandles for performance.\n\n## Build\n\n```\n./gradlew :btrace-extensions:examples:btrace-spark:build\n```\n\nThe BTrace extension plugin will produce API/impl artifacts. Use with a BTrace distribution that supports extensions.\n\n## Configuration (`extensions.conf`)\n\n```\n# Enable the example\nbtrace-spark-example.enabled=true\n\n# Role detection: auto|driver|executor (example only; implement as needed)\nbtrace-spark-example.role=auto\n\n# Optional: if your application does not ship Spark libs and you must point\n# the extension at an external classpath for reflective linking. Prefer not needed.\n# btrace-spark-example.classpath=/opt/spark/jars\n```\n\n## Permissions\n\nThis example uses reflection. Ensure your policy grants the permission:\n\n```\n# permissions.properties (see PermissionPolicy docs)\ngrant=REFLECTION,SYSTEM_PROPS\n```\n\nAvoid `CLASSLOADER` unless you explicitly create child loaders from configured paths.\n\n## Usage Notes\n\n- Provided-style: no bootstrap/system classpath mutation; probe code imports only the API.\n- Object hand-off: pass Spark event objects (`Object`) to API methods; the impl resolves types at runtime.\n- Class loading: the impl runs resolution under the defining loader of the handed-off object.\n- MethodHandle cache: repeated reflective calls are cached for speed.\n\nIf you absolutely must expose a jar on the system classpath temporarily:\n- Use the escape hatch (discouraged): `-Dbtrace.system.appendJar=/abs/path/lib.jar -Dbtrace.trusted=true`.\n- Prefer fixing packaging or using an extension-local child loader instead.\n\n## Probe Integration (Conceptual)\n\n- Probes can call the API directly (API is on bootstrap). Keep probe signatures generic (`Object` argument types).\n- Example (pseudo):\n\n```java\nimport org.example.btrace.spark.api.SparkApi;\nimport io.btrace.core.annotations.*;\n\n@BTrace\nclass SparkProbe {\n  // Using SparkApi statically via extension linkage (no manual wiring needed)\n  @OnMethod(clazz=\"org.apache.spark.scheduler.DAGScheduler\", method=\"handleJobStart\")\n  public static void onJobStart(@Self Object self, Object jobStart) {\n    // SparkApi.onJobStart(jobStart); // conceptual example\n  }\n}\n```\n\nNote: The example is not maintained as part of core BTrace; adapt for your environment.\n\n","btrace-extensions/examples/btrace-hadoop/README.md":"# BTrace Hadoop Example (Provided-Style Extension)\n\nThis example demonstrates a provided-style BTrace extension for Apache Hadoop that:\n- Exposes a minimal API on bootstrap (`org.example.btrace.hadoop.api.HadoopApi`).\n- Loads implementation in an isolated classloader (no system/boot CL injection).\n- Resolves Hadoop classes at runtime using object hand-off and the application’s defining class loader.\n- Caches reflective MethodHandles for performance.\n\n## Build\n\n```\n./gradlew :btrace-extensions:examples:btrace-hadoop:build\n```\n\nThe BTrace extension plugin will produce API/impl artifacts. Use with a BTrace distribution that supports extensions.\n\n## Configuration (`extensions.conf`)\n\n```\n# Enable the example\nbtrace-hadoop-example.enabled=true\n\n# Optional: if your application does not ship Hadoop libs\n# btrace-hadoop-example.classpath=/opt/hadoop/share/hadoop/common\n```\n\n## Permissions\n\nThis example uses reflection. Ensure your policy grants the permission:\n\n```\n# permissions.properties (see PermissionPolicy docs)\ngrant=REFLECTION,SYSTEM_PROPS\n```\n\nAvoid `CLASSLOADER` unless you explicitly create child loaders from configured paths.\n\n## Usage Notes\n\n- Provided-style: no bootstrap/system classpath mutation; probe code imports only the API.\n- Object hand-off: pass Hadoop objects (`Object`) to API methods; the impl resolves types at runtime.\n- Class loading: the impl runs resolution under the defining loader of the handed-off object.\n- MethodHandle cache: repeated reflective calls are cached for speed.\n\nIf you absolutely must expose a jar on the system classpath temporarily:\n- Use the escape hatch (discouraged): `-Dbtrace.system.appendJar=/abs/path/lib.jar -Dbtrace.trusted=true`.\n- Prefer fixing packaging or using an extension-local child loader instead.\n\n## Probe Integration (Conceptual)\n\n- Probes can call the API directly (API is on bootstrap). Keep probe signatures generic (`Object` argument types).\n- Example (pseudo):\n\n```java\nimport org.example.btrace.hadoop.api.HadoopApi;\nimport io.btrace.core.annotations.*;\n\n@BTrace\nclass HadoopProbe {\n  // Using HadoopApi statically via extension linkage (no manual wiring needed)\n  @OnMethod(clazz=\"org.apache.hadoop.fs.FileSystem\", method=\"open\")\n  public static void onOpen(@Self Object fs, Object path) {\n    // HadoopApi.onOpen(fs, path); // conceptual example\n  }\n}\n```\n\nNote: The example is not maintained as part of core BTrace; adapt for your environment.\n\n"},"files":{"AGENTS.md":"# Repository Guide for Coding Agents\n\n## Start here\n\nBTrace is a Java tracing tool: the client compiles and sends a script, the agent instruments the target JVM, and the runtime emits results. The root project is a multi-module Gradle build.\n\n- `btrace-agent` — attachable agent, script lifecycle, and bytecode instrumentation/weaving\n- `btrace-compiler` — script verification and compilation\n- `btrace-runtime` / `btrace-core` — script APIs, runtime support, and protocol\n- `btrace-client` — CLI and attachment client\n- `btrace-dist` — distribution assembly; `integration-tests` — end-to-end tests\n- `btrace-extensions/*` — extension API and implementations\n\nFor the developer command reference and code-navigation pointers, see [CLAUDE.md](CLAUDE.md). For user and contributor documentation, start at [docs/README.md](docs/README.md).\n\n## Non-negotiable rules\n\n- Do not commit unless the changes are fully tested or the user explicitly requests a commit.\n- Preserve unrelated working-tree changes.\n- In Java code, import types and use simple names; do not introduce fully qualified type names in source.\n- Main code targets Java 8 and uses the Java 11 toolchain. Follow Spotless/Google Java Format.\n- Unit tests live in `src/test/java` and use `*Test`; integration tests live in `integration-tests/src/test/java`.\n- Changes to user-visible behavior that crosses modules or process boundaries must include end-to-end functional coverage in `integration-tests`; unit and component tests are required where useful but are not a substitute for exercising the real client, agent, target JVM, and protocol interaction.\n- Confirm that a new test or build gate **fails when it should**, not only that it passes. Run it against the unfixed code, or against input it must reject, and check the failure is the expected one. A check that cannot fail reports success regardless of what the code does, and reads as coverage while providing none. Where a revert is used to produce the failure, revert only the code under test: reverting too much fails for an unrelated reason and proves nothing about the behavior being asserted.\n\n## Build and verification\n\nRun Gradle with a workspace-local cache in restricted environments:\n\n```bash\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :module:test\n```\n\nDo not consume Gradle output directly. Redirect it to a file, filter it to relevant lines, then read that file. Use `spotlessCheck` for validation and `spotlessApply` only when formatting changes are intended. Build `:btrace-dist:build` before integration tests.\n\nIf a restricted network environment causes address-selection failures, add:\n\n```bash\nJAVA_TOOL_OPTIONS=\"-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv6Addresses=false\"\n```\n\n## Distribution changes\n\n`btrace.jar` is a masked single-JAR distribution. Classes must be assigned to bootstrap, agent, client, or shared sections deliberately. Any masked-JAR structure change requires:\n\n```bash\n./gradlew clean :btrace-dist:btraceJar\n```\n\nRead [Masked JAR Architecture](docs/architecture/MaskedJarArchitecture.md) before modifying its class layout or loader behavior.\n\n## Documentation placement\n\n- User-facing and contributor documentation belongs in `docs/`; keep [docs/README.md](docs/README.md) current when adding a guide.\n- Plans and session notes belong in `internal/plans/` (or `internal/superpowers/plans/`).\n- Design/requirement specs belong in `internal/specs/` (or `internal/superpowers/specs/`); libretto/muse files belong in `internal/libretti/`.\n- Never create or write to a singular `doc/` directory, or add plans, agent notes, or internal material below `docs/`.\n\n## Reference map\n\n- [Contribution workflow](CONTRIBUTING.md)\n- [Instrumentation backend selection](docs/architecture/InstrumentationBackends.md)\n- [v2 wire protocol](docs/architecture/Version2ProtocolArchitecture.md)\n- [Extension development](docs/BTraceExtensionDevelopmentGuide.md) and [interface rules](docs/ExtensionInterfaceRules.md)\n- [Troubleshooting](docs/Troubleshooting.md)\n","CLAUDE.md":"# Claude Code Guide\n\nFollow the repository-wide rules in [AGENTS.md](AGENTS.md). This file intentionally contains only Claude-specific orientation; `AGENTS.md` is the canonical operational contract.\n\n## Common commands\n\nUse a workspace-local Gradle cache when appropriate, and redirect Gradle output to a log before filtering and reading it (see [AGENTS.md](AGENTS.md#build-and-verification)).\n\n```bash\n# Distribution and all unit tests (:btrace-dist:build alone skips most module tests)\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew build\n\n# Module, test class, or formatting check\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :btrace-agent:test\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :btrace-agent:test --tests '*InstrStackTest'\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew spotlessCheck\n\n# Integration tests: build the distribution first\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew -Pintegration :integration-tests:test\n\n# Intentional instrumentation-bytecode changes only\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew test -PupdateTestData\n```\n\n## Where to look\n\n- Script compiler and verifier: `btrace-compiler`\n- Agent lifecycle and bytecode weaving: `btrace-agent` (instrumentation engine lives in its `io.btrace.instr` package)\n- Script API, runtime, and protocol: `btrace-core`, `btrace-runtime`\n- CLI: `btrace-client`; packaging: `btrace-dist`\n- Golden instrumentation data: `btrace-agent/src/test/resources/instrumentorTestData/`\n\n## Detailed references\n\n- [Documentation index](docs/README.md)\n- [Masked JAR architecture](docs/architecture/MaskedJarArchitecture.md) — required reading for distribution/class-loading changes\n- [Instrumentation backends](docs/architecture/InstrumentationBackends.md)\n- [Protocol architecture](docs/architecture/Version2ProtocolArchitecture.md)\n- [Extension development](docs/BTraceExtensionDevelopmentGuide.md)\n- [Troubleshooting](docs/Troubleshooting.md)\n",".github/copilot-instructions.md":"# GitHub Copilot Instructions for BTrace\n\n## About BTrace\nBTrace is a safe, dynamic tracing tool for the Java platform. It dynamically instruments running Java applications to inject tracing code at runtime using bytecode instrumentation.\n\n## Project Structure\n- **Gradle multi-module project** with modules named `btrace-*`\n- **Core modules**: `btrace-core`, `btrace-agent`, `btrace-runtime`, `btrace-client`, `btrace-instr`\n- **Build artifacts**: `btrace-dist` for distributions\n- **Tests**: `integration-tests/` for integration tests, `src/test/java` in modules for unit tests\n- **Documentation**: `docs/` directory\n\n## Architecture Overview\n- **btrace-agent**: Attachable Java agent with class transformer, manages script lifecycle\n- **btrace-compiler**: Verifies and compiles BTrace scripts to bytecode\n- **btrace-instr**: ASM-based instrumentation and weaving utilities\n- **btrace-runtime**: APIs for scripts (printing, timers, data collection)\n- **btrace-client**: CLI/attach tooling for sending scripts to target JVM\n- **services**: SPI for pluggable exporters (e.g., statsd)\n\n## Development Guidelines\n\n### Language & Versions\n- **Language**: Java\n- **Source/Target**: Java 8\n- **Build toolchain**: JDK 11\n- **Test framework**: JUnit Jupiter (JUnit 5)\n\n### Code Style\n- **Format**: Google Java Format enforced via Spotless\n- **Packages**: All under `io.btrace.*`\n- **Naming**: Module names follow `btrace-<component>` pattern\n- **Imports**: Order enforced; remove unused imports\n- **Comments**: Only add if they match existing style or explain complex logic\n\n### Building & Testing\n```bash\n# Full build with unit tests\n./gradlew build\n\n# Build distribution only\n./gradlew :btrace-dist:build\n\n# Run unit tests\n./gradlew test\n\n# Run integration tests (requires dist build first)\n./gradlew -Pintegration test\n\n# Format code\n./gradlew spotlessApply\n\n# Check formatting\n./gradlew spotlessCheck\n```\n\n### Important Environment Variables\n- `JAVA_HOME`: Required for builds\n- `TEST_JAVA_HOME`: Required for integration tests (typically JDK 11)\n- `BTRACE_TEST_DEBUG=true`: Enable verbose integration test output\n- `BTRACE_HOME`: Optional, points to exploded dist\n\n### Testing Best Practices\n- Unit tests: `src/test/java` with `*Test` suffix\n- Integration tests: `integration-tests/src/test/java`\n- BTrace scripts: `integration-tests/src/test/btrace`\n- Always run relevant tests after making changes\n- Update golden files when changing instrumentor: `./gradlew test -PupdateTestData`\n\n### Commit & PR Guidelines\n- **Commit style**: Conventional Commits (e.g., `feat(core): add probe`, `fix(instr): handle null arg`)\n- **Clear descriptions**: Link related issues\n- **Tests required**: Update/add tests; ensure CI passes\n- **Formatting**: Must pass `spotlessCheck`\n- **No unrelated changes**: Keep changes focused and minimal\n\n## Troubleshooting\n\n### Build Issues\n- **Attach disabled**: Remove `-XX:+DisableAttachMechanism` from target JVM\n- **Permission errors**: Attach requires same OS user as target JVM\n- **Toolchain issues**: Verify `JAVA_HOME` and `TEST_JAVA_HOME` point to valid JDKs\n\n### Restricted Environments\n```bash\n# Use workspace-local Gradle cache\nGRADLE_USER_HOME=$(pwd)/.gradle-user\n\n# Force IPv4 to avoid network interface issues\nJAVA_TOOL_OPTIONS=\"-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv6Addresses=false\"\n```\n\n## Code Generation Tips\n- **Prefer simplicity**: Simple, performant solutions over complex designs\n- **Use existing patterns**: Follow patterns from similar code in the repository\n- **Minimal changes**: Make the smallest possible changes to achieve the goal\n- **Reuse libraries**: Use ASM for bytecode, JCTools for concurrency, existing BTrace APIs\n- **No temporary files in repo**: Use `/tmp` for scratch work\n- **Security**: Never commit secrets; avoid introducing vulnerabilities\n\n## Example BTrace Script Pattern\n```java\npackage example;\nimport static io.btrace.core.BTraceUtils.*;\nimport io.btrace.core.annotations.*;\n\n@BTrace\npublic class ExampleTrace {\n  @OnMethod(clazz=\"com.example.Target\", method=\"methodName\")\n  public static void onMethod(@ProbeMethodName String method) {\n    println(\"Called: \" + method);\n  }\n}\n```\n\n## Key Dependencies\n- **ASM**: Bytecode manipulation\n- **JCTools**: High-performance concurrent data structures\n- **hppcrt**: Optimized collections\n- **JUnit Jupiter**: Testing framework\n\n## Additional Resources\n- Full guidelines: See `AGENTS.md` in repository root\n- Tutorial: `docs/BTraceTutorial.md`\n- Binary releases: https://github.com/btraceio/btrace/releases\n","btrace-extensions/examples/btrace-spark/README.md":"# BTrace Spark Example (Provided-Style Extension)\n\nThis example demonstrates a provided-style BTrace extension for Apache Spark that:\n- Exposes a minimal API on bootstrap (`org.example.btrace.spark.api.SparkApi`).\n- Loads implementation in an isolated classloader (no system/boot CL injection).\n- Resolves Spark classes at runtime using object hand-off and the application’s defining class loader.\n- Caches reflective MethodHandles for performance.\n\n## Build\n\n```\n./gradlew :btrace-extensions:examples:btrace-spark:build\n```\n\nThe BTrace extension plugin will produce API/impl artifacts. Use with a BTrace distribution that supports extensions.\n\n## Configuration (`extensions.conf`)\n\n```\n# Enable the example\nbtrace-spark-example.enabled=true\n\n# Role detection: auto|driver|executor (example only; implement as needed)\nbtrace-spark-example.role=auto\n\n# Optional: if your application does not ship Spark libs and you must point\n# the extension at an external classpath for reflective linking. Prefer not needed.\n# btrace-spark-example.classpath=/opt/spark/jars\n```\n\n## Permissions\n\nThis example uses reflection. Ensure your policy grants the permission:\n\n```\n# permissions.properties (see PermissionPolicy docs)\ngrant=REFLECTION,SYSTEM_PROPS\n```\n\nAvoid `CLASSLOADER` unless you explicitly create child loaders from configured paths.\n\n## Usage Notes\n\n- Provided-style: no bootstrap/system classpath mutation; probe code imports only the API.\n- Object hand-off: pass Spark event objects (`Object`) to API methods; the impl resolves types at runtime.\n- Class loading: the impl runs resolution under the defining loader of the handed-off object.\n- MethodHandle cache: repeated reflective calls are cached for speed.\n\nIf you absolutely must expose a jar on the system classpath temporarily:\n- Use the escape hatch (discouraged): `-Dbtrace.system.appendJar=/abs/path/lib.jar -Dbtrace.trusted=true`.\n- Prefer fixing packaging or using an extension-local child loader instead.\n\n## Probe Integration (Conceptual)\n\n- Probes can call the API directly (API is on bootstrap). Keep probe signatures generic (`Object` argument types).\n- Example (pseudo):\n\n```java\nimport org.example.btrace.spark.api.SparkApi;\nimport io.btrace.core.annotations.*;\n\n@BTrace\nclass SparkProbe {\n  // Using SparkApi statically via extension linkage (no manual wiring needed)\n  @OnMethod(clazz=\"org.apache.spark.scheduler.DAGScheduler\", method=\"handleJobStart\")\n  public static void onJobStart(@Self Object self, Object jobStart) {\n    // SparkApi.onJobStart(jobStart); // conceptual example\n  }\n}\n```\n\nNote: The example is not maintained as part of core BTrace; adapt for your environment.\n\n","btrace-extensions/examples/btrace-hadoop/README.md":"# BTrace Hadoop Example (Provided-Style Extension)\n\nThis example demonstrates a provided-style BTrace extension for Apache Hadoop that:\n- Exposes a minimal API on bootstrap (`org.example.btrace.hadoop.api.HadoopApi`).\n- Loads implementation in an isolated classloader (no system/boot CL injection).\n- Resolves Hadoop classes at runtime using object hand-off and the application’s defining class loader.\n- Caches reflective MethodHandles for performance.\n\n## Build\n\n```\n./gradlew :btrace-extensions:examples:btrace-hadoop:build\n```\n\nThe BTrace extension plugin will produce API/impl artifacts. Use with a BTrace distribution that supports extensions.\n\n## Configuration (`extensions.conf`)\n\n```\n# Enable the example\nbtrace-hadoop-example.enabled=true\n\n# Optional: if your application does not ship Hadoop libs\n# btrace-hadoop-example.classpath=/opt/hadoop/share/hadoop/common\n```\n\n## Permissions\n\nThis example uses reflection. Ensure your policy grants the permission:\n\n```\n# permissions.properties (see PermissionPolicy docs)\ngrant=REFLECTION,SYSTEM_PROPS\n```\n\nAvoid `CLASSLOADER` unless you explicitly create child loaders from configured paths.\n\n## Usage Notes\n\n- Provided-style: no bootstrap/system classpath mutation; probe code imports only the API.\n- Object hand-off: pass Hadoop objects (`Object`) to API methods; the impl resolves types at runtime.\n- Class loading: the impl runs resolution under the defining loader of the handed-off object.\n- MethodHandle cache: repeated reflective calls are cached for speed.\n\nIf you absolutely must expose a jar on the system classpath temporarily:\n- Use the escape hatch (discouraged): `-Dbtrace.system.appendJar=/abs/path/lib.jar -Dbtrace.trusted=true`.\n- Prefer fixing packaging or using an extension-local child loader instead.\n\n## Probe Integration (Conceptual)\n\n- Probes can call the API directly (API is on bootstrap). Keep probe signatures generic (`Object` argument types).\n- Example (pseudo):\n\n```java\nimport org.example.btrace.hadoop.api.HadoopApi;\nimport io.btrace.core.annotations.*;\n\n@BTrace\nclass HadoopProbe {\n  // Using HadoopApi statically via extension linkage (no manual wiring needed)\n  @OnMethod(clazz=\"org.apache.hadoop.fs.FileSystem\", method=\"open\")\n  public static void onOpen(@Self Object fs, Object path) {\n    // HadoopApi.onOpen(fs, path); // conceptual example\n  }\n}\n```\n\nNote: The example is not maintained as part of core BTrace; adapt for your environment.\n\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/btraceio/btrace/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Repository Guide for Coding Agents\n\n## Start here\n\nBTrace is a Java tracing tool: the client compiles and sends a script, the agent instruments the target JVM, and the runtime emits results. The root project is a multi-module Gradle build.\n\n- `btrace-agent` — attachable agent, script lifecycle, and bytecode instrumentation/weaving\n- `btrace-compiler` — script verification and compilation\n- `btrace-runtime` / `btrace-core` — script APIs, runtime support, and protocol\n- `btrace-client` — CLI and attachment client\n- `btrace-dist` — distribution assembly; `integration-tests` — end-to-end tests\n- `btrace-extensions/*` — extension API and implementations\n\nFor the developer command reference and code-navigation pointers, see [CLAUDE.md](CLAUDE.md). For user and contributor documentation, start at [docs/README.md](docs/README.md).\n\n## Non-negotiable rules\n\n- Do not commit unless the changes are fully tested or the user explicitly requests a commit.\n- Preserve unrelated working-tree changes.\n- In Java code, import types and use simple names; do not introduce fully qualified type names in source.\n- Main code targets Java 8 and uses the Java 11 toolchain. Follow Spotless/Google Java Format.\n- Unit tests live in `src/test/java` and use `*Test`; integration tests live in `integration-tests/src/test/java`.\n- Changes to user-visible behavior that crosses modules or process boundaries must include end-to-end functional coverage in `integration-tests`; unit and component tests are required where useful but are not a substitute for exercising the real client, agent, target JVM, and protocol interaction.\n- Confirm that a new test or build gate **fails when it should**, not only that it passes. Run it against the unfixed code, or against input it must reject, and check the failure is the expected one. A check that cannot fail reports success regardless of what the code does, and reads as coverage while providing none. Where a revert is used to produce the failure, revert only the code under test: reverting too much fails for an unrelated reason and proves nothing about the behavior being asserted.\n\n## Build and verification\n\nRun Gradle with a workspace-local cache in restricted environments:\n\n```bash\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :module:test\n```\n\nDo not consume Gradle output directly. Redirect it to a file, filter it to relevant lines, then read that file. Use `spotlessCheck` for validation and `spotlessApply` only when formatting changes are intended. Build `:btrace-dist:build` before integration tests.\n\nIf a restricted network environment causes address-selection failures, add:\n\n```bash\nJAVA_TOOL_OPTIONS=\"-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv6Addresses=false\"\n```\n\n## Distribution changes\n\n`btrace.jar` is a masked single-JAR distribution. Classes must be assigned to bootstrap, agent, client, or shared sections deliberately. Any masked-JAR structure change requires:\n\n```bash\n./gradlew clean :btrace-dist:btraceJar\n```\n\nRead [Masked JAR Architecture](docs/architecture/MaskedJarArchitecture.md) before modifying its class layout or loader behavior.\n\n## Documentation placement\n\n- User-facing and contributor documentation belongs in `docs/`; keep [docs/README.md](docs/README.md) current when adding a guide.\n- Plans and session notes belong in `internal/plans/` (or `internal/superpowers/plans/`).\n- Design/requirement specs belong in `internal/specs/` (or `internal/superpowers/specs/`); libretto/muse files belong in `internal/libretti/`.\n- Never create or write to a singular `doc/` directory, or add plans, agent notes, or internal material below `docs/`.\n\n## Reference map\n\n- [Contribution workflow](CONTRIBUTING.md)\n- [Instrumentation backend selection](docs/architecture/InstrumentationBackends.md)\n- [v2 wire protocol](docs/architecture/Version2ProtocolArchitecture.md)\n- [Extension development](docs/BTraceExtensionDevelopmentGuide.md) and [interface rules](docs/ExtensionInterfaceRules.md)\n- [Troubleshooting](docs/Troubleshooting.md)\n","isInternal":false,"tokens":896,"sizeBytes":4027},{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/btraceio/btrace/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# Claude Code Guide\n\nFollow the repository-wide rules in [AGENTS.md](AGENTS.md). This file intentionally contains only Claude-specific orientation; `AGENTS.md` is the canonical operational contract.\n\n## Common commands\n\nUse a workspace-local Gradle cache when appropriate, and redirect Gradle output to a log before filtering and reading it (see [AGENTS.md](AGENTS.md#build-and-verification)).\n\n```bash\n# Distribution and all unit tests (:btrace-dist:build alone skips most module tests)\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew build\n\n# Module, test class, or formatting check\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :btrace-agent:test\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :btrace-agent:test --tests '*InstrStackTest'\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew spotlessCheck\n\n# Integration tests: build the distribution first\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew -Pintegration :integration-tests:test\n\n# Intentional instrumentation-bytecode changes only\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew test -PupdateTestData\n```\n\n## Where to look\n\n- Script compiler and verifier: `btrace-compiler`\n- Agent lifecycle and bytecode weaving: `btrace-agent` (instrumentation engine lives in its `io.btrace.instr` package)\n- Script API, runtime, and protocol: `btrace-core`, `btrace-runtime`\n- CLI: `btrace-client`; packaging: `btrace-dist`\n- Golden instrumentation data: `btrace-agent/src/test/resources/instrumentorTestData/`\n\n## Detailed references\n\n- [Documentation index](docs/README.md)\n- [Masked JAR architecture](docs/architecture/MaskedJarArchitecture.md) — required reading for distribution/class-loading changes\n- [Instrumentation backends](docs/architecture/InstrumentationBackends.md)\n- [Protocol architecture](docs/architecture/Version2ProtocolArchitecture.md)\n- [Extension development](docs/BTraceExtensionDevelopmentGuide.md)\n- [Troubleshooting](docs/Troubleshooting.md)\n","isInternal":false,"tokens":460,"sizeBytes":1919},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","rawUrl":"https://raw.githubusercontent.com/btraceio/btrace/HEAD/.github/copilot-instructions.md","title":"GitHub Copilot Instructions","category":"copilot-instructions","format":"markdown","content":"# GitHub Copilot Instructions for BTrace\n\n## About BTrace\nBTrace is a safe, dynamic tracing tool for the Java platform. It dynamically instruments running Java applications to inject tracing code at runtime using bytecode instrumentation.\n\n## Project Structure\n- **Gradle multi-module project** with modules named `btrace-*`\n- **Core modules**: `btrace-core`, `btrace-agent`, `btrace-runtime`, `btrace-client`, `btrace-instr`\n- **Build artifacts**: `btrace-dist` for distributions\n- **Tests**: `integration-tests/` for integration tests, `src/test/java` in modules for unit tests\n- **Documentation**: `docs/` directory\n\n## Architecture Overview\n- **btrace-agent**: Attachable Java agent with class transformer, manages script lifecycle\n- **btrace-compiler**: Verifies and compiles BTrace scripts to bytecode\n- **btrace-instr**: ASM-based instrumentation and weaving utilities\n- **btrace-runtime**: APIs for scripts (printing, timers, data collection)\n- **btrace-client**: CLI/attach tooling for sending scripts to target JVM\n- **services**: SPI for pluggable exporters (e.g., statsd)\n\n## Development Guidelines\n\n### Language & Versions\n- **Language**: Java\n- **Source/Target**: Java 8\n- **Build toolchain**: JDK 11\n- **Test framework**: JUnit Jupiter (JUnit 5)\n\n### Code Style\n- **Format**: Google Java Format enforced via Spotless\n- **Packages**: All under `io.btrace.*`\n- **Naming**: Module names follow `btrace-<component>` pattern\n- **Imports**: Order enforced; remove unused imports\n- **Comments**: Only add if they match existing style or explain complex logic\n\n### Building & Testing\n```bash\n# Full build with unit tests\n./gradlew build\n\n# Build distribution only\n./gradlew :btrace-dist:build\n\n# Run unit tests\n./gradlew test\n\n# Run integration tests (requires dist build first)\n./gradlew -Pintegration test\n\n# Format code\n./gradlew spotlessApply\n\n# Check formatting\n./gradlew spotlessCheck\n```\n\n### Important Environment Variables\n- `JAVA_HOME`: Required for builds\n- `TEST_JAVA_HOME`: Required for integration tests (typically JDK 11)\n- `BTRACE_TEST_DEBUG=true`: Enable verbose integration test output\n- `BTRACE_HOME`: Optional, points to exploded dist\n\n### Testing Best Practices\n- Unit tests: `src/test/java` with `*Test` suffix\n- Integration tests: `integration-tests/src/test/java`\n- BTrace scripts: `integration-tests/src/test/btrace`\n- Always run relevant tests after making changes\n- Update golden files when changing instrumentor: `./gradlew test -PupdateTestData`\n\n### Commit & PR Guidelines\n- **Commit style**: Conventional Commits (e.g., `feat(core): add probe`, `fix(instr): handle null arg`)\n- **Clear descriptions**: Link related issues\n- **Tests required**: Update/add tests; ensure CI passes\n- **Formatting**: Must pass `spotlessCheck`\n- **No unrelated changes**: Keep changes focused and minimal\n\n## Troubleshooting\n\n### Build Issues\n- **Attach disabled**: Remove `-XX:+DisableAttachMechanism` from target JVM\n- **Permission errors**: Attach requires same OS user as target JVM\n- **Toolchain issues**: Verify `JAVA_HOME` and `TEST_JAVA_HOME` point to valid JDKs\n\n### Restricted Environments\n```bash\n# Use workspace-local Gradle cache\nGRADLE_USER_HOME=$(pwd)/.gradle-user\n\n# Force IPv4 to avoid network interface issues\nJAVA_TOOL_OPTIONS=\"-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv6Addresses=false\"\n```\n\n## Code Generation Tips\n- **Prefer simplicity**: Simple, performant solutions over complex designs\n- **Use existing patterns**: Follow patterns from similar code in the repository\n- **Minimal changes**: Make the smallest possible changes to achieve the goal\n- **Reuse libraries**: Use ASM for bytecode, JCTools for concurrency, existing BTrace APIs\n- **No temporary files in repo**: Use `/tmp` for scratch work\n- **Security**: Never commit secrets; avoid introducing vulnerabilities\n\n## Example BTrace Script Pattern\n```java\npackage example;\nimport static io.btrace.core.BTraceUtils.*;\nimport io.btrace.core.annotations.*;\n\n@BTrace\npublic class ExampleTrace {\n  @OnMethod(clazz=\"com.example.Target\", method=\"methodName\")\n  public static void onMethod(@ProbeMethodName String method) {\n    println(\"Called: \" + method);\n  }\n}\n```\n\n## Key Dependencies\n- **ASM**: Bytecode manipulation\n- **JCTools**: High-performance concurrent data structures\n- **hppcrt**: Optimized collections\n- **JUnit Jupiter**: Testing framework\n\n## Additional Resources\n- Full guidelines: See `AGENTS.md` in repository root\n- Tutorial: `docs/BTraceTutorial.md`\n- Binary releases: https://github.com/btraceio/btrace/releases\n","isInternal":false,"tokens":1058,"sizeBytes":4535},{"name":"README.md","path":"btrace-extensions/examples/btrace-hadoop/README.md","rawUrl":"https://raw.githubusercontent.com/btraceio/btrace/HEAD/btrace-extensions/examples/btrace-hadoop/README.md","title":"btrace-hadoop Documentation","category":"plugin-manifest","format":"markdown","content":"# BTrace Hadoop Example (Provided-Style Extension)\n\nThis example demonstrates a provided-style BTrace extension for Apache Hadoop that:\n- Exposes a minimal API on bootstrap (`org.example.btrace.hadoop.api.HadoopApi`).\n- Loads implementation in an isolated classloader (no system/boot CL injection).\n- Resolves Hadoop classes at runtime using object hand-off and the application’s defining class loader.\n- Caches reflective MethodHandles for performance.\n\n## Build\n\n```\n./gradlew :btrace-extensions:examples:btrace-hadoop:build\n```\n\nThe BTrace extension plugin will produce API/impl artifacts. Use with a BTrace distribution that supports extensions.\n\n## Configuration (`extensions.conf`)\n\n```\n# Enable the example\nbtrace-hadoop-example.enabled=true\n\n# Optional: if your application does not ship Hadoop libs\n# btrace-hadoop-example.classpath=/opt/hadoop/share/hadoop/common\n```\n\n## Permissions\n\nThis example uses reflection. Ensure your policy grants the permission:\n\n```\n# permissions.properties (see PermissionPolicy docs)\ngrant=REFLECTION,SYSTEM_PROPS\n```\n\nAvoid `CLASSLOADER` unless you explicitly create child loaders from configured paths.\n\n## Usage Notes\n\n- Provided-style: no bootstrap/system classpath mutation; probe code imports only the API.\n- Object hand-off: pass Hadoop objects (`Object`) to API methods; the impl resolves types at runtime.\n- Class loading: the impl runs resolution under the defining loader of the handed-off object.\n- MethodHandle cache: repeated reflective calls are cached for speed.\n\nIf you absolutely must expose a jar on the system classpath temporarily:\n- Use the escape hatch (discouraged): `-Dbtrace.system.appendJar=/abs/path/lib.jar -Dbtrace.trusted=true`.\n- Prefer fixing packaging or using an extension-local child loader instead.\n\n## Probe Integration (Conceptual)\n\n- Probes can call the API directly (API is on bootstrap). Keep probe signatures generic (`Object` argument types).\n- Example (pseudo):\n\n```java\nimport org.example.btrace.hadoop.api.HadoopApi;\nimport io.btrace.core.annotations.*;\n\n@BTrace\nclass HadoopProbe {\n  // Using HadoopApi statically via extension linkage (no manual wiring needed)\n  @OnMethod(clazz=\"org.apache.hadoop.fs.FileSystem\", method=\"open\")\n  public static void onOpen(@Self Object fs, Object path) {\n    // HadoopApi.onOpen(fs, path); // conceptual example\n  }\n}\n```\n\nNote: The example is not maintained as part of core BTrace; adapt for your environment.\n\n","isInternal":false,"tokens":528,"sizeBytes":2438},{"name":"README.md","path":"btrace-extensions/examples/btrace-spark/README.md","rawUrl":"https://raw.githubusercontent.com/btraceio/btrace/HEAD/btrace-extensions/examples/btrace-spark/README.md","title":"btrace-spark Documentation","category":"plugin-manifest","format":"markdown","content":"# BTrace Spark Example (Provided-Style Extension)\n\nThis example demonstrates a provided-style BTrace extension for Apache Spark that:\n- Exposes a minimal API on bootstrap (`org.example.btrace.spark.api.SparkApi`).\n- Loads implementation in an isolated classloader (no system/boot CL injection).\n- Resolves Spark classes at runtime using object hand-off and the application’s defining class loader.\n- Caches reflective MethodHandles for performance.\n\n## Build\n\n```\n./gradlew :btrace-extensions:examples:btrace-spark:build\n```\n\nThe BTrace extension plugin will produce API/impl artifacts. Use with a BTrace distribution that supports extensions.\n\n## Configuration (`extensions.conf`)\n\n```\n# Enable the example\nbtrace-spark-example.enabled=true\n\n# Role detection: auto|driver|executor (example only; implement as needed)\nbtrace-spark-example.role=auto\n\n# Optional: if your application does not ship Spark libs and you must point\n# the extension at an external classpath for reflective linking. Prefer not needed.\n# btrace-spark-example.classpath=/opt/spark/jars\n```\n\n## Permissions\n\nThis example uses reflection. Ensure your policy grants the permission:\n\n```\n# permissions.properties (see PermissionPolicy docs)\ngrant=REFLECTION,SYSTEM_PROPS\n```\n\nAvoid `CLASSLOADER` unless you explicitly create child loaders from configured paths.\n\n## Usage Notes\n\n- Provided-style: no bootstrap/system classpath mutation; probe code imports only the API.\n- Object hand-off: pass Spark event objects (`Object`) to API methods; the impl resolves types at runtime.\n- Class loading: the impl runs resolution under the defining loader of the handed-off object.\n- MethodHandle cache: repeated reflective calls are cached for speed.\n\nIf you absolutely must expose a jar on the system classpath temporarily:\n- Use the escape hatch (discouraged): `-Dbtrace.system.appendJar=/abs/path/lib.jar -Dbtrace.trusted=true`.\n- Prefer fixing packaging or using an extension-local child loader instead.\n\n## Probe Integration (Conceptual)\n\n- Probes can call the API directly (API is on bootstrap). Keep probe signatures generic (`Object` argument types).\n- Example (pseudo):\n\n```java\nimport org.example.btrace.spark.api.SparkApi;\nimport io.btrace.core.annotations.*;\n\n@BTrace\nclass SparkProbe {\n  // Using SparkApi statically via extension linkage (no manual wiring needed)\n  @OnMethod(clazz=\"org.apache.spark.scheduler.DAGScheduler\", method=\"handleJobStart\")\n  public static void onJobStart(@Self Object self, Object jobStart) {\n    // SparkApi.onJobStart(jobStart); // conceptual example\n  }\n}\n```\n\nNote: The example is not maintained as part of core BTrace; adapt for your environment.\n\n","isInternal":false,"tokens":571,"sizeBytes":2655}],"systemPromptSnippet":"<yakaai_skills repo=\"btraceio/btrace\">\n<!-- File: AGENTS.md (Tokens: ~896 | Category: root-instruction) -->\n# Repository Guide for Coding Agents\n\n## Start here\n\nBTrace is a Java tracing tool: the client compiles and sends a script, the agent instruments the target JVM, and the runtime emits results. The root project is a multi-module Gradle build.\n\n- `btrace-agent` — attachable agent, script lifecycle, and bytecode instrumentation/weaving\n- `btrace-compiler` — script verification and compilation\n- `btrace-runtime` / `btrace-core` — script APIs, runtime support, and protocol\n- `btrace-client` — CLI and attachment client\n- `btrace-dist` — distribution assembly; `integration-tests` — end-to-end tests\n- `btrace-extensions/*` — extension API and implementations\n\nFor the developer command reference and code-navigation pointers, see [CLAUDE.md](CLAUDE.md). For user and contributor documentation, start at [docs/README.md](docs/README.md).\n\n## Non-negotiable rules\n\n- Do not commit unless the changes are fully tested or the user explicitly requests a commit.\n- Preserve unrelated working-tree changes.\n- In Java code, import types and use simple names; do not introduce fully qualified type names in source.\n- Main code targets Java 8 and uses the Java 11 toolchain. Follow Spotless/Google Java Format.\n- Unit tests live in `src/test/java` and use `*Test`; integration tests live in `integration-tests/src/test/java`.\n- Changes to user-visible behavior that crosses modules or process boundaries must include end-to-end functional coverage in `integration-tests`; unit and component tests are required where useful but are not a substitute for exercising the real client, agent, target JVM, and protocol interaction.\n- Confirm that a new test or build gate **fails when it should**, not only that it passes. Run it against the unfixed code, or against input it must reject, and check the failure is the expected one. A check that cannot fail reports success regardless of what the code does, and reads as coverage while providing none. Where a revert is used to produce the failure, revert only the code under test: reverting too much fails for an unrelated reason and proves nothing about the behavior being asserted.\n\n## Build and verification\n\nRun Gradle with a workspace-local cache in restricted environments:\n\n```bash\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :module:test\n```\n\nDo not consume Gradle output directly. Redirect it to a file, filter it to relevant lines, then read that file. Use `spotlessCheck` for validation and `spotlessApply` only when formatting changes are intended. Build `:btrace-dist:build` before integration tests.\n\nIf a restricted network environment causes address-selection failures, add:\n\n```bash\nJAVA_TOOL_OPTIONS=\"-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv6Addresses=false\"\n```\n\n## Distribution changes\n\n`btrace.jar` is a masked single-JAR distribution. Classes must be assigned to bootstrap, agent, client, or shared sections deliberately. Any masked-JAR structure change requires:\n\n```bash\n./gradlew clean :btrace-dist:btraceJar\n```\n\nRead [Masked JAR Architecture](docs/architecture/MaskedJarArchitecture.md) before modifying its class layout or loader behavior.\n\n## Documentation placement\n\n- User-facing and contributor documentation belongs in `docs/`; keep [docs/README.md](docs/README.md) current when adding a guide.\n- Plans and session notes belong in `internal/plans/` (or `internal/superpowers/plans/`).\n- Design/requirement specs belong in `internal/specs/` (or `internal/superpowers/specs/`); libretto/muse files belong in `internal/libretti/`.\n- Never create or write to a singular `doc/` directory, or add plans, agent notes, or internal material below `docs/`.\n\n## Reference map\n\n- [Contribution workflow](CONTRIBUTING.md)\n- [Instrumentation backend selection](docs/architecture/InstrumentationBackends.md)\n- [v2 wire protocol](docs/architecture/Version2ProtocolArchitecture.md)\n- [Extension development](docs/BTraceExtensionDevelopmentGuide.md) and [interface rules](docs/ExtensionInterfaceRules.md)\n- [Troubleshooting](docs/Troubleshooting.md)\n\n<!-- File: CLAUDE.md (Tokens: ~460 | Category: claude-rule) -->\n# Claude Code Guide\n\nFollow the repository-wide rules in [AGENTS.md](AGENTS.md). This file intentionally contains only Claude-specific orientation; `AGENTS.md` is the canonical operational contract.\n\n## Common commands\n\nUse a workspace-local Gradle cache when appropriate, and redirect Gradle output to a log before filtering and reading it (see [AGENTS.md](AGENTS.md#build-and-verification)).\n\n```bash\n# Distribution and all unit tests (:btrace-dist:build alone skips most module tests)\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew build\n\n# Module, test class, or formatting check\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :btrace-agent:test\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :btrace-agent:test --tests '*InstrStackTest'\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew spotlessCheck\n\n# Integration tests: build the distribution first\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew -Pintegration :integration-tests:test\n\n# Intentional instrumentation-bytecode changes only\nGRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew test -PupdateTestData\n```\n\n## Where to look\n\n- Script compiler and verifier: `btrace-compiler`\n- Agent lifecycle and bytecode weaving: `btrace-agent` (instrumentation engine lives in its `io.btrace.instr` package)\n- Script API, runtime, and protocol: `btrace-core`, `btrace-runtime`\n- CLI: `btrace-client`; packaging: `btrace-dist`\n- Golden instrumentation data: `btrace-agent/src/test/resources/instrumentorTestData/`\n\n## Detailed references\n\n- [Documentation index](docs/README.md)\n- [Masked JAR architecture](docs/architecture/MaskedJarArchitecture.md) — required reading for distribution/class-loading changes\n- [Instrumentation backends](docs/architecture/InstrumentationBackends.md)\n- [Protocol architecture](docs/architecture/Version2ProtocolArchitecture.md)\n- [Extension development](docs/BTraceExtensionDevelopmentGuide.md)\n- [Troubleshooting](docs/Troubleshooting.md)\n\n<!-- File: .github/copilot-instructions.md (Tokens: ~1058 | Category: copilot-instructions) -->\n# GitHub Copilot Instructions for BTrace\n\n## About BTrace\nBTrace is a safe, dynamic tracing tool for the Java platform. It dynamically instruments running Java applications to inject tracing code at runtime using bytecode instrumentation.\n\n## Project Structure\n- **Gradle multi-module project** with modules named `btrace-*`\n- **Core modules**: `btrace-core`, `btrace-agent`, `btrace-runtime`, `btrace-client`, `btrace-instr`\n- **Build artifacts**: `btrace-dist` for distributions\n- **Tests**: `integration-tests/` for integration tests, `src/test/java` in modules for unit tests\n- **Documentation**: `docs/` directory\n\n## Architecture Overview\n- **btrace-agent**: Attachable Java agent with class transformer, manages script lifecycle\n- **btrace-compiler**: Verifies and compiles BTrace scripts to bytecode\n- **btrace-instr**: ASM-based instrumentation and weaving utilities\n- **btrace-runtime**: APIs for scripts (printing, timers, data collection)\n- **btrace-client**: CLI/attach tooling for sending scripts to target JVM\n- **services**: SPI for pluggable exporters (e.g., statsd)\n\n## Development Guidelines\n\n### Language & Versions\n- **Language**: Java\n- **Source/Target**: Java 8\n- **Build toolchain**: JDK 11\n- **Test framework**: JUnit Jupiter (JUnit 5)\n\n### Code Style\n- **Format**: Google Java Format enforced via Spotless\n- **Packages**: All under `io.btrace.*`\n- **Naming**: Module names follow `btrace-<component>` pattern\n- **Imports**: Order enforced; remove unused imports\n- **Comments**: Only add if they match existing style or explain complex logic\n\n### Building & Testing\n```bash\n# Full build with unit tests\n./gradlew build\n\n# Build distribution only\n./gradlew :btrace-dist:build\n\n# Run unit tests\n./gradlew test\n\n# Run integration tests (requires dist build first)\n./gradlew -Pintegration test\n\n# Format code\n./gradlew spotlessApply\n\n# Check formatting\n./gradlew spotlessCheck\n```\n\n### Important Environment Variables\n- `JAVA_HOME`: Required for builds\n- `TEST_JAVA_HOME`: Required for integration tests (typically JDK 11)\n- `BTRACE_TEST_DEBUG=true`: Enable verbose integration test output\n- `BTRACE_HOME`: Optional, points to exploded dist\n\n### Testing Best Practices\n- Unit tests: `src/test/java` with `*Test` suffix\n- Integration tests: `integration-tests/src/test/java`\n- BTrace scripts: `integration-tests/src/test/btrace`\n- Always run relevant tests after making changes\n- Update golden files when changing instrumentor: `./gradlew test -PupdateTestData`\n\n### Commit & PR Guidelines\n- **Commit style**: Conventional Commits (e.g., `feat(core): add probe`, `fix(instr): handle null arg`)\n- **Clear descriptions**: Link related issues\n- **Tests required**: Update/add tests; ensure CI passes\n- **Formatting**: Must pass `spotlessCheck`\n- **No unrelated changes**: Keep changes focused and minimal\n\n## Troubleshooting\n\n### Build Issues\n- **Attach disabled**: Remove `-XX:+DisableAttachMechanism` from target JVM\n- **Permission errors**: Attach requires same OS user as target JVM\n- **Toolchain issues**: Verify `JAVA_HOME` and `TEST_JAVA_HOME` point to valid JDKs\n\n### Restricted Environments\n```bash\n# Use workspace-local Gradle cache\nGRADLE_USER_HOME=$(pwd)/.gradle-user\n\n# Force IPv4 to avoid network interface issues\nJAVA_TOOL_OPTIONS=\"-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv6Addresses=false\"\n```\n\n## Code Generation Tips\n- **Prefer simplicity**: Simple, performant solutions over complex designs\n- **Use existing patterns**: Follow patterns from similar code in the repository\n- **Minimal changes**: Make the smallest possible changes to achieve the goal\n- **Reuse libraries**: Use ASM for bytecode, JCTools for concurrency, existing BTrace APIs\n- **No temporary files in repo**: Use `/tmp` for scratch work\n- **Security**: Never commit secrets; avoid introducing vulnerabilities\n\n## Example BTrace Script Pattern\n```java\npackage example;\nimport static io.btrace.core.BTraceUtils.*;\nimport io.btrace.core.annotations.*;\n\n@BTrace\npublic class ExampleTrace {\n  @OnMethod(clazz=\"com.example.Target\", method=\"methodName\")\n  public static void onMethod(@ProbeMethodName String method) {\n    println(\"Called: \" + method);\n  }\n}\n```\n\n## Key Dependencies\n- **ASM**: Bytecode manipulation\n- **JCTools**: High-performance concurrent data structures\n- **hppcrt**: Optimized collections\n- **JUnit Jupiter**: Testing framework\n\n## Additional Resources\n- Full guidelines: See `AGENTS.md` in repository root\n- Tutorial: `docs/BTraceTutorial.md`\n- Binary releases: https://github.com/btraceio/btrace/releases\n\n<!-- File: btrace-extensions/examples/btrace-hadoop/README.md (Tokens: ~528 | Category: plugin-manifest) -->\n# BTrace Hadoop Example (Provided-Style Extension)\n\nThis example demonstrates a provided-style BTrace extension for Apache Hadoop that:\n- Exposes a minimal API on bootstrap (`org.example.btrace.hadoop.api.HadoopApi`).\n- Loads implementation in an isolated classloader (no system/boot CL injection).\n- Resolves Hadoop classes at runtime using object hand-off and the application’s defining class loader.\n- Caches reflective MethodHandles for performance.\n\n## Build\n\n```\n./gradlew :btrace-extensions:examples:btrace-hadoop:build\n```\n\nThe BTrace extension plugin will produce API/impl artifacts. Use with a BTrace distribution that supports extensions.\n\n## Configuration (`extensions.conf`)\n\n```\n# Enable the example\nbtrace-hadoop-example.enabled=true\n\n# Optional: if your application does not ship Hadoop libs\n# btrace-hadoop-example.classpath=/opt/hadoop/share/hadoop/common\n```\n\n## Permissions\n\nThis example uses reflection. Ensure your policy grants the permission:\n\n```\n# permissions.properties (see PermissionPolicy docs)\ngrant=REFLECTION,SYSTEM_PROPS\n```\n\nAvoid `CLASSLOADER` unless you explicitly create child loaders from configured paths.\n\n## Usage Notes\n\n- Provided-style: no bootstrap/system classpath mutation; probe code imports only the API.\n- Object hand-off: pass Hadoop objects (`Object`) to API methods; the impl resolves types at runtime.\n- Class loading: the impl runs resolution under the defining loader of the handed-off object.\n- MethodHandle cache: repeated reflective calls are cached for speed.\n\nIf you absolutely must expose a jar on the system classpath temporarily:\n- Use the escape hatch (discouraged): `-Dbtrace.system.appendJar=/abs/path/lib.jar -Dbtrace.trusted=true`.\n- Prefer fixing packaging or using an extension-local child loader instead.\n\n## Probe Integration (Conceptual)\n\n- Probes can call the API directly (API is on bootstrap). Keep probe signatures generic (`Object` argument types).\n- Example (pseudo):\n\n```java\nimport org.example.btrace.hadoop.api.HadoopApi;\nimport io.btrace.core.annotations.*;\n\n@BTrace\nclass HadoopProbe {\n  // Using HadoopApi statically via extension linkage (no manual wiring needed)\n  @OnMethod(clazz=\"org.apache.hadoop.fs.FileSystem\", method=\"open\")\n  public static void onOpen(@Self Object fs, Object path) {\n    // HadoopApi.onOpen(fs, path); // conceptual example\n  }\n}\n```\n\nNote: The example is not maintained as part of core BTrace; adapt for your environment.\n\n<!-- File: btrace-extensions/examples/btrace-spark/README.md (Tokens: ~571 | Category: plugin-manifest) -->\n# BTrace Spark Example (Provided-Style Extension)\n\nThis example demonstrates a provided-style BTrace extension for Apache Spark that:\n- Exposes a minimal API on bootstrap (`org.example.btrace.spark.api.SparkApi`).\n- Loads implementation in an isolated classloader (no system/boot CL injection).\n- Resolves Spark classes at runtime using object hand-off and the application’s defining class loader.\n- Caches reflective MethodHandles for performance.\n\n## Build\n\n```\n./gradlew :btrace-extensions:examples:btrace-spark:build\n```\n\nThe BTrace extension plugin will produce API/impl artifacts. Use with a BTrace distribution that supports extensions.\n\n## Configuration (`extensions.conf`)\n\n```\n# Enable the example\nbtrace-spark-example.enabled=true\n\n# Role detection: auto|driver|executor (example only; implement as needed)\nbtrace-spark-example.role=auto\n\n# Optional: if your application does not ship Spark libs and you must point\n# the extension at an external classpath for reflective linking. Prefer not needed.\n# btrace-spark-example.classpath=/opt/spark/jars\n```\n\n## Permissions\n\nThis example uses reflection. Ensure your policy grants the permission:\n\n```\n# permissions.properties (see PermissionPolicy docs)\ngrant=REFLECTION,SYSTEM_PROPS\n```\n\nAvoid `CLASSLOADER` unless you explicitly create child loaders from configured paths.\n\n## Usage Notes\n\n- Provided-style: no bootstrap/system classpath mutation; probe code imports only the API.\n- Object hand-off: pass Spark event objects (`Object`) to API methods; the impl resolves types at runtime.\n- Class loading: the impl runs resolution under the defining loader of the handed-off object.\n- MethodHandle cache: repeated reflective calls are cached for speed.\n\nIf you absolutely must expose a jar on the system classpath temporarily:\n- Use the escape hatch (discouraged): `-Dbtrace.system.appendJar=/abs/path/lib.jar -Dbtrace.trusted=true`.\n- Prefer fixing packaging or using an extension-local child loader instead.\n\n## Probe Integration (Conceptual)\n\n- Probes can call the API directly (API is on bootstrap). Keep probe signatures generic (`Object` argument types).\n- Example (pseudo):\n\n```java\nimport org.example.btrace.spark.api.SparkApi;\nimport io.btrace.core.annotations.*;\n\n@BTrace\nclass SparkProbe {\n  // Using SparkApi statically via extension linkage (no manual wiring needed)\n  @OnMethod(clazz=\"org.apache.spark.scheduler.DAGScheduler\", method=\"handleJobStart\")\n  public static void onJobStart(@Self Object self, Object jobStart) {\n    // SparkApi.onJobStart(jobStart); // conceptual example\n  }\n}\n```\n\nNote: The example is not maintained as part of core BTrace; adapt for your environment.\n</yakaai_skills>"}