[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-4346":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":16,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":22,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":27,"readmeContent":28,"aiSummary":29,"trendingCount":15,"starSnapshotCount":15,"syncStatus":30,"lastSyncTime":31,"discoverSource":32},4346,"btrace","btraceio\u002Fbtrace","btraceio","BTrace - a safe, dynamic tracing tool for the Java platform",null,"Java",5988,959,314,4,0,1,3,39.95,"Apache License 2.0",false,"develop",true,[5,24,25,26],"java","java-application","java-platform","2026-06-12 02:01:02","# BTrace\n\n**Safe, dynamic tracing for Java applications**\n\n[![CI](https:\u002F\u002Fgithub.com\u002Fbtraceio\u002Fbtrace\u002Fworkflows\u002FBTrace%20CI%2FCD\u002Fbadge.svg?branch=develop)](https:\u002F\u002Fgithub.com\u002Fbtraceio\u002Fbtrace\u002Factions)\n[![Release](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fbtraceio\u002Fbtrace?sort=semver)](https:\u002F\u002Fgithub.com\u002Fbtraceio\u002Fbtrace\u002Freleases\u002Flatest)\n[![codecov](https:\u002F\u002Fcodecov.io\u002Fgithub\u002Fbtraceio\u002Fbtrace\u002Fcoverage.svg?branch=develop)](https:\u002F\u002Fcodecov.io\u002Fgithub\u002Fbtraceio\u002Fbtrace?branch=develop)\n\nBTrace dynamically instruments running Java applications to inject tracing code at runtime. No restarts. No recompilation. Production-safe.\n\n> **Quick links:** [Quick Reference](docs\u002FQuickReference.md) · [Step-by-Step Tutorial](docs\u002FGettingStarted.md)\n\n---\n\n## Why BTrace?\n\n- **Zero downtime** - Attach to running JVMs without restart\n- **Production safe** - Verified scripts can't crash your application\n- **Flexible probes** - Method entry\u002Fexit, timings, field access, allocations\n- **Low overhead** - Bytecode injection with minimal performance impact\n\n---\n\n## Get Started in 30 Seconds\n\n```sh\n# Install via JBang (easiest)\ncurl -Ls https:\u002F\u002Fsh.jbang.dev | bash -s - app setup\n\n# Add the BTrace JBang catalog (one time)\njbang catalog add --name btraceio https:\u002F\u002Fraw.githubusercontent.com\u002Fbtraceio\u002Fjbang-catalog\u002Fmain\u002Fjbang-catalog.json\n\n# Trace slow methods in your running app\njbang btrace@btraceio -n 'com.myapp.*::* @return if duration>100ms { print method, duration }' $(pgrep -f myapp)\n```\n\n---\n\n## Trace Anything\n\n**Method timing:**\n```sh\nbtrace -n 'java.sql.Statement::execute* @return { print method, duration }' \u003CPID>\n```\n\n**Exception tracking:**\n```sh\nbtrace -n 'java.lang.Exception::\u003Cinit> @return { print self, stack(5) }' \u003CPID>\n```\n\n**Custom probes:**\n```java\n@BTrace public class Trace {\n    @OnMethod(clazz = \"com.example.OrderService\", method = \"checkout\")\n    public static void onCheckout(@Self Object self, @Duration long ns) {\n        println(strcat(\"checkout: \", str(ns\u002F1_000_000) + \"ms\"));\n    }\n}\n```\n\nSee the [Oneliner Guide](docs\u002FOnelinerGuide.md) for complete syntax.\n\n---\n\n## Install\n\n```sh\n# JBang (recommended - zero installation)\njbang catalog add --name btraceio https:\u002F\u002Fraw.githubusercontent.com\u002Fbtraceio\u002Fjbang-catalog\u002Fmain\u002Fjbang-catalog.json\njbang btrace@btraceio \u003CPID> script.java\n\n# SDKMan\nsdk install btrace\n\n# Manual download\ncurl -LO https:\u002F\u002Fgithub.com\u002Fbtraceio\u002Fbtrace\u002Freleases\u002Flatest\u002Fdownload\u002Fbtrace-bin.tar.gz\n```\n\nSee [Installation Guide](docs\u002FGettingStarted.md#installation) for Docker, package managers, and more options.\n\n---\n\n## Documentation\n\n| Resource | Description |\n|----------|-------------|\n| [Quick Reference](docs\u002FQuickReference.md) | Cheat sheet for experienced users |\n| [Getting Started](docs\u002FGettingStarted.md) | Step-by-step first trace tutorial |\n| [Full Tutorial](docs\u002FBTraceTutorial.md) | Complete walkthrough of all features |\n| [Oneliners](docs\u002FOnelinerGuide.md) | DTrace-style quick probes |\n| [Extensions](docs\u002FBTraceExtensionDevelopmentGuide.md) | StatsD, custom integrations |\n| [Documentation Hub](docs\u002FREADME.md) | All docs and guides |\n\n---\n\n## Building from Source\n\n```sh\ngit clone https:\u002F\u002Fgithub.com\u002Fbtraceio\u002Fbtrace.git\ncd btrace\n.\u002Fgradlew :btrace-dist:build\n```\n\nSee [CLAUDE.md](CLAUDE.md) for development setup and architecture.\n\n---\n\n## Community & Contributing\n\n**Get help:** [Slack](http:\u002F\u002Fbtrace.slack.com\u002F) · [GitHub Issues](https:\u002F\u002Fgithub.com\u002Fbtraceio\u002Fbtrace\u002Fissues)\n\nTips:\n- Prefer IPv4 if your environment has odd local IPs: set `GRADLE_OPTS=\"-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv6Addresses=false\"`.\n- Run specific modules:\n  - Runtime: `.\u002Fgradlew :btrace-runtime:test`\n  - Extension: `.\u002Fgradlew :btrace-extension:test`\n  - Compiler: `.\u002Fgradlew :btrace-compiler:test`\n  - Instr: `.\u002Fgradlew :btrace-instr:test`\n- Update instrumentor golden files when bytecode output changes: `.\u002Fgradlew test -PupdateTestData`.\n\nIntegration tests (optional):\n```sh\n.\u002Fgradlew --no-daemon integration-tests:test\n```\nThese may exercise privileged extensions. If you run into permission denials, provide a policy file and pass it to the test JVMs via `-Dbtrace.permissions=\u002Fpath\u002Fto\u002Fpermissions.properties`.\n\n\n## Using BTrace\n\n### Installation\n\n#### JBang (Easiest - Recommended)\n\nUse [JBang](https:\u002F\u002Fwww.jbang.dev\u002F) to run BTrace without manual installation:\n\n```sh\n# Install JBang (one time)\ncurl -Ls https:\u002F\u002Fsh.jbang.dev | bash -s - app setup\n\n# Use BTrace immediately (replace \u003Cversion> with desired version, e.g., 2.3.0)\njbang io.btrace:btrace-client:\u003Cversion> \u003CPID> \u003Cscript.java>\n\n# After first run, use shorter alias\njbang btrace \u003CPID> \u003Cscript.java>\n```\n\n**Note:** Replace `\u003Cversion>` with the desired BTrace version (e.g., `2.3.0`). See [releases](https:\u002F\u002Fgithub.com\u002Fbtraceio\u002Fbtrace\u002Freleases) for available versions.\n\n**Benefits:** Zero installation, automatic version management, works everywhere (Windows\u002FmacOS\u002FLinux\u002Fcontainers), perfect for CI\u002FCD.\n\n**Extract agent JARs** (if needed for `--agent-jar`\u002F`--boot-jar` flags):\n```sh\n# Extract embedded JARs\njbang btrace --extract-agent ~\u002F.btrace\n\n# This creates ~\u002F.btrace\u002Fbtrace.jar (single masked JAR)\n# Then use them:\njbang btrace --agent-jar ~\u002F.btrace\u002Fbtrace.jar \u003CPID> \u003Cscript.java>\n\n# Or find in Maven local repository (after first jbang run):\n# ~\u002F.m2\u002Frepository\u002Forg\u002Fopenjdk\u002Fbtrace\u002Fbtrace\u002F\u003Cversion>\u002Fbtrace-\u003Cversion>.jar\n#\n# Legacy jar names (btrace-agent.jar, btrace-boot.jar) are still extracted for backward compatibility.\n```\n\nSee [Getting Started Guide](docs\u002FGettingStarted.md#jbang-installation-recommended-for-quick-start) for complete JBang documentation and examples.\n\n#### Binary Distribution\n\n**Download:** Get the latest release from the [release page](https:\u002F\u002Fgithub.com\u002Fbtraceio\u002Fbtrace\u002Freleases\u002Flatest)\n\n```sh\n# Extract the archive\ntar -xzf btrace-*.tar.gz\n# or\nunzip btrace-*.zip\n\n# Set environment variables (optional but recommended)\nexport BTRACE_HOME=\u002Fpath\u002Fto\u002Fbtrace\nexport PATH=$BTRACE_HOME\u002Fbin:$PATH\n```\n\n#### Package Installation\n\n```sh\n# RPM-based systems\nsudo rpm -i btrace-*.rpm\n\n# Debian-based systems\nsudo dpkg -i btrace-*.deb\n```\n\n**Docker images:**\n```dockerfile\n# Copy BTrace into your application image\nFROM btrace\u002Fbtrace:latest AS btrace\nFROM bellsoft\u002Fliberica-openjdk-debian:11-cds\n\nCOPY --from=btrace \u002Fopt\u002Fbtrace \u002Fopt\u002Fbtrace\nENV BTRACE_HOME=\u002Fopt\u002Fbtrace PATH=\"${PATH}:${BTRACE_HOME}\u002Fbin\"\n\n# Your application...\n```\n\nAvailable variants:\n- `btrace\u002Fbtrace:latest` - Debian-based (~25MB)\n- `btrace\u002Fbtrace:latest-alpine` - Alpine-based (~15MB)\n- `btrace\u002Fbtrace:latest-distroless` - Distroless (~10MB)\n\nSee [docker\u002FREADME.md](docker\u002FREADME.md) for complete Docker documentation.\n\n### Quick Start\n\n**With JBang (no installation required):**\n```sh\n# Attach to running application\njbang btrace \u003CPID> \u003Ctrace_script.java>\n\n# Extract agent JARs\njbang btrace --extract-agent ~\u002F.btrace\n```\n\n**With installed BTrace:**\n```sh\n# Attach to running application\nbtrace \u003CPID> \u003Ctrace_script.java>\n\n# Compile BTrace script\nbtracec \u003Ctrace_script.java>\n\n# Launch application with BTrace agent\nbtracer \u003Ccompiled_script.class> \u003Cjava-application-and-args>\n```\n\n### Extensions and Deprecated libs\u002Fprofiles\n\nExtensions add functionality via a stable API on bootstrap and an isolated implementation. See the extension development guide and examples.\n\nNote: The legacy `libs`\u002Fprofiles mechanism is deprecated and planned for removal after N+2 minor releases. Prefer packaging integrations as extensions and using provided-style class loading patterns (object hand-off + TCCL). For migration guidance and examples, see:\n- `docs\u002Farchitecture\u002Fmigrating-from-libs-profiles.md`\n- `docs\u002Farchitecture\u002Fprovided-style-extensions.md`\n- `docs\u002Fexamples\u002FREADME.md`\n\nAs a last resort (discouraged), you may append a single jar to the system classpath: `-Dbtrace.system.appendJar=\u002Fabs\u002Fpath\u002Flib.jar -Dbtrace.trusted=true`.\n\n### Fat Agent JAR (Single-JAR Deployment)\n\nFor environments where managing multiple JARs is impractical (Spark, Hadoop, Kubernetes), BTrace provides a fat agent JAR with embedded extensions:\n\n```sh\n# Build fat agent with all extensions\n.\u002Fgradlew :btrace-dist:fatAgentJar\n\n# Build with specific extensions only\n.\u002Fgradlew :btrace-dist:fatAgentJar -PembedExtensions=btrace-metrics,btrace-statsd\n\n# Use the fat agent\njava -javaagent:btrace-agent-fat.jar \u003Cyour-app>\n```\n\nThe fat agent JAR includes:\n- All agent and boot classes\n- Embedded extension API classes (bootstrap)\n- Embedded extension impl classes (runtime-loaded)\n- Extension metadata for auto-discovery\n\nFor custom fat agent builds, use the Gradle plugin:\n```groovy\nplugins {\n    id 'io.btrace.fat-agent'\n}\n\nbtraceFatAgent {\n    embedExtensions {\n        maven('io.btrace:btrace-metrics:2.3.0')\n        project(':my-custom-extension')\n    }\n}\n```\n\nSee [Fat Agent Plugin Architecture](docs\u002Farchitecture\u002Ffat-agent-plugin.md) and [Gradle Plugin README](btrace-gradle-plugin\u002FREADME.md) for details.\n\n### Oneliner Quick Examples\n\nBTrace now supports DTrace-style oneliners for quick debugging without writing full Java scripts:\n\n```sh\n# Trace method entry with arguments\nbtrace -n 'javax.swing.*::setText @entry { print method, args }' \u003CPID>\n\n# Find slow database queries (>100ms)\nbtrace -n 'java.sql.Statement::execute* @return if duration>100ms { print method, duration }' \u003CPID>\n\n# Count method invocations\nbtrace -n 'java.util.HashMap::get @entry { count }' \u003CPID>\n\n# Print stack trace on OutOfMemoryError\nbtrace -n 'java.lang.OutOfMemoryError::\u003Cinit> @return { stack(10) }' \u003CPID>\n```\n\n**Supported features:**\n- **Locations**: `@entry`, `@return`, `@error`\n- **Actions**: `print`, `count`, `time`, `stack`\n- **Filters**: `if duration>NUMBERms`, `if args[N]==VALUE`\n- **Patterns**: Wildcards (`*`, `?`) and regex (`\u002Fpattern\u002F`)\n\nSee [Oneliner Guide](docs\u002FOnelinerGuide.md) for complete syntax and examples.\n\n### Documentation\nFor comprehensive documentation, tutorials, and guides:\n* **[BTrace Documentation Hub](docs\u002FREADME.md)** - Complete documentation index with learning paths, quick reference, troubleshooting, and more\n* **[Getting Started Guide](docs\u002FGettingStarted.md)** - Get up and running in 5 minutes\n* **[BTrace Wiki](https:\u002F\u002Fgithub.com\u002Fbtraceio\u002Fbtrace\u002Fwiki\u002FHome)** - External wiki with additional resources\n\n### Extensions and Permissions\nBTrace supports extensions (like StatsdExtension) that provide additional functionality. Extensions require explicit permissions for security:\n\n* **Default permissions** (always granted): MESSAGING, AGGREGATION, JFR_EVENTS, PROFILING\n* **Standard permissions** (granted unless denied): FILE_READ, SYSTEM_PROPS, THREAD_INFO, MEMORY_INFO\n* **Privileged permissions** (require explicit grant): FILE_WRITE, NETWORK, THREADS, NATIVE, EXEC, REFLECTION, CLASSLOADER, UNLIMITED_MEMORY\n\nPermissions are enforced based on extension\u002Fservice descriptors and agent grants specified at attach-time.\n\nGrant permissions at runtime:\n```sh\nbtrace --grant=NETWORK,THREADS \u003CPID> MyProbe.class\n```\n\nIf extensions fail to load, use `-le` to troubleshoot:\n```sh\nbtrace -le \u003CPID>\n```\n\nSee the [Tutorial](docs\u002FBTraceTutorial.md) for detailed documentation.\n\nExtensions CLI: use `btracex` to inspect and manage extensions and the simplified permission policy:\n- `btracex inspect \u003Czip|dir>` prints extension id, version, services, and whether it’s privileged.\n- `btracex policy print|set [--policy-file \u003Cpath>|--home|--classpath \u003CoutDir>]` edits `allowExtensions`, `denyExtensions`, `allowPrivileged`.\n- `btracex list` shows installed extensions; `btracex install` installs from Maven coordinates.\n\nNote: Extension “required permissions” are informational and help operators assess risk. Implementation linking is controlled by per‑extension allow\u002Fdeny lists and the `allowPrivileged` flag; when blocked, APIs remain available and SHIMs are used so probes continue safely.\n\n#### Agent Policy and Allow\u002FDeny Lists\n- Launch-time policy can be set via agent args (operator-controlled):\n  - `-javaagent:btrace.jar=...,grant=NETWORK,THREADS,grantAll=false`\n  - `-javaagent:btrace.jar=...,allowExtensions=btrace-statsd,my-metrics,denyExtensions=legacy-foo`\n- Optional policy file (process-local): `-Dbtrace.permissions=\u002Fpath\u002Fto\u002Fpermissions.properties` or `~\u002F.btrace\u002Fpermissions.properties`.\n- When an extension impl is blocked, the API remains on bootstrap so SHIMs can be generated.\n\nSee docs\u002FPermissionPolicy.md for details and examples.\n\n#### btracex TUI (interactive)\n- Launch: `btracex inspect` (with no args) opens an interactive view of installed extensions.\n- Header: shows current policy file path and the list of scanned repositories.\n- Table: columns State, Id, Version. State uses compact symbols: `?` (default), `+` (allowed), `-` (denied).\n- Details: selection updates automatically; shows the full-word state: `default` \u002F `allowed` \u002F `denied` and the full path.\n- Legend: a short legend under the table maps the state symbols.\n\nScreenshot \u002F demo (optional):\n\n![btracex TUI](docs\u002Fimages\u002Fbtracex-tui.png)\n\n![btracex TUI demo](docs\u002Fimages\u002Fbtracex-tui.gif)\n\nSee also: docs\u002FTUI.md for recording tips and an ASCII preview.\n\nKeys\n- Navigate: Arrow keys, PageUp\u002FPageDown, Home\u002FEnd\n- Toggle state: space (flows `? → + (confirm) → - → +`; only `c` clears to default)\n- Clear: `c` (removes extension id from both allow and deny lists)\n- Explain privileges: `e` (opens a dialog with required permissions and risk descriptions)\n- Filter: `\u002F` (filter by id or path)\n- Sort: `s` (choose column; repeat to toggle asc\u002Fdesc)\n- Adjust split: `m` (enter mode), then Up\u002FDown to resize; press `Esc` or `m` again to exit\n- Help \u002F Quit: `?` \u002F `q`\n\n### Maven Integration\n\n**Fat Agent Plugin** (in this repo): Build fat agent JARs with embedded extensions:\n```xml\n\u003Cplugin>\n    \u003CgroupId>io.btrace\u003C\u002FgroupId>\n    \u003CartifactId>btrace-maven-plugin\u003C\u002FartifactId>\n    \u003Cversion>${btrace.version}\u003C\u002Fversion>\n    \u003Cconfiguration>\n        \u003Cextensions>\n            \u003Cextension>io.btrace:btrace-metrics:${btrace.version}\u003C\u002Fextension>\n        \u003C\u002Fextensions>\n    \u003C\u002Fconfiguration>\n\u003C\u002Fplugin>\n```\n\n**Script Compilation Plugin** ([external repo](https:\u002F\u002Fgithub.com\u002Fbtraceio\u002Fbtrace-maven)):\n- Compilation of BTrace scripts during the build process\n- BTrace Project Archetype for quick project setup\n\n## Contributing\n\n**Important:** Pull requests can only be accepted from signers of the [Oracle Contributor Agreement](https:\u002F\u002Foca.opensource.oracle.com\u002F).\n\n### Development\n\nSee [CLAUDE.md](CLAUDE.md) for detailed development guidelines and project architecture.\n\n## Community\n\n- **Slack:** [btrace.slack.com](http:\u002F\u002Fbtrace.slack.com\u002F)\n- **Gitter:** [gitter.im\u002Fbtraceio\u002Fbtrace](https:\u002F\u002Fgitter.im\u002Fbtraceio\u002Fbtrace)\n- **Issues:** [GitHub Issues](https:\u002F\u002Fgithub.com\u002Fbtraceio\u002Fbtrace\u002Fissues)\n\n## License\n\nGPLv2 with Classpath Exception. See [LICENSE](LICENSE).\n\n---\n\n**Credits:** Built with [ASM](http:\u002F\u002Fasm.ow2.org\u002F), [JCTools](https:\u002F\u002Fgithub.com\u002FJCTools\u002FJCTools), [hppcrt](https:\u002F\u002Fgithub.com\u002Fvsonnier\u002Fhppcrt). Optimized with [JProfiler](http:\u002F\u002Fwww.ej-technologies.com\u002Fproducts\u002Fjprofiler\u002Foverview.html).\n","BTrace 是一个用于Java平台的安全动态追踪工具。它能够在不重启或重新编译的情况下，对正在运行的Java应用程序进行动态插桩以注入追踪代码，确保生产环境中的应用稳定性和安全性。其核心功能包括零停机时间、灵活多样的探测点（如方法调用、异常跟踪等）以及低性能开销的字节码注入技术。BTrace 非常适合需要在不影响服务正常运行的前提下，对Java应用进行性能分析、故障排查或是实时监控的场景。",2,"2026-06-11 02:59:46","top_language"]