{"id":18772737,"url":"https://github.com/jvm-profiling-tools/ap-loader","last_synced_at":"2025-04-13T08:32:03.959Z","repository":{"id":64110295,"uuid":"561333026","full_name":"jvm-profiling-tools/ap-loader","owner":"jvm-profiling-tools","description":"Packages async-profiler with binaries for all platforms in a single JAR","archived":false,"fork":false,"pushed_at":"2024-03-12T11:09:30.000Z","size":83,"stargazers_count":121,"open_issues_count":1,"forks_count":10,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-04-16T10:59:06.125Z","etag":null,"topics":["async-profiler","java"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jvm-profiling-tools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-11-03T13:18:40.000Z","updated_at":"2024-03-31T14:26:10.000Z","dependencies_parsed_at":"2024-01-07T13:29:00.946Z","dependency_job_id":"cdab9171-a804-43db-a3ee-a1cf1faf5e4c","html_url":"https://github.com/jvm-profiling-tools/ap-loader","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvm-profiling-tools%2Fap-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvm-profiling-tools%2Fap-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvm-profiling-tools%2Fap-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvm-profiling-tools%2Fap-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jvm-profiling-tools","download_url":"https://codeload.github.com/jvm-profiling-tools/ap-loader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223576678,"owners_count":17167906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async-profiler","java"],"created_at":"2024-11-07T19:30:02.274Z","updated_at":"2024-11-07T19:30:02.901Z","avatar_url":"https://github.com/jvm-profiling-tools.png","language":"Java","readme":"Loader for AsyncProfiler\n========================\n\n[![Maven Central](https://img.shields.io/maven-central/v/me.bechberger/ap-loader-all)](https://search.maven.org/search?q=ap-loader) [![GitHub](https://img.shields.io/github/license/jvm-profiling-tools/ap-loader)](https://github.com/jvm-profiling-tools/ap-loader/blob/main/LICENSE)\n\nPackages [async-profiler](https://github.com/jvm-profiling-tools/async-profiler) releases in a JAR\nwith an `AsyncProfilerLoader` (version 3.*, 2.* and 1.8.*)\nthat loads the suitable native library for the current platform.\n\n*In 3.* it also includes the latest [jattach](https://github.com/apangin/jattach) binary. This was previously\npart of async-profiler.*\n\nThis is usable as a Java agent (same arguments as the async-profiler agent) and as the basis for other libraries.\nThe real rationale behind this library is that the async-profiler is a nice tool, but it cannot be easily integrated\ninto other Java-based tools.\n\nThe `AsyncProfilerLoader` API integrates async-profiler and jattach with a user-friendly interface (see below).\n\nThe wrapper is tested against all relevant tests of the async-profiler tool, ensuring that it has the same behavior.\n\nTake the [`all` build](https://github.com/jvm-profiling-tools/ap-loader/releases/latest/download/ap-loader-all.jar) and you have a JAR that provides the important features of async-profiler on all supported\nplatforms.\n\nA changelog can be found in the async-profiler repository, as this library should rarely change itself.\n\n_This project assumes that you used async-profiler before, if not, don't worry, you can still use this project,\nbut be aware that its documentation refers you to the async-profiler documentation a lot._\n\n_fdtransfer is currently not supported, feel free to create an issue if you need it._\n\nI wrote two blog posts about this project:\n\n1. [AP-Loader: A new way to use and embed async-profiler](https://mostlynerdless.de/blog/2022/11/21/ap-loader-a-new-way-to-use-and-embed-async-profiler/)\n2. [Using Async-Profiler and Jattach Programmatically with AP-Loader](https://mostlynerdless.de/blog/2023/05/02/using-async-profiler-and-jattach-programmatically-with-ap-loader/)\n\nDownload\n--------\n\nYou can download the latest release from the \n[latest release page](https://github.com/jvm-profiling-tools/ap-loader/releases/latest/).\nAs a shortcut, the wrapper for all platforms can be found \n[here](https://github.com/jvm-profiling-tools/ap-loader/releases/latest/download/ap-loader-all.jar).\n\nIt should be up-to-date with the latest async-profiler release, but if not, feel free to create an issue.\n\nTo use the library as a dependency, you can depend on `me.bechberger.ap-loader-\u003cvariant\u003e:\u003cversion\u003e-\u003cap-loader-version\u003e`\nfrom maven central, e.g:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eme.bechberger\u003c/groupId\u003e\n    \u003cartifactId\u003eap-loader-all\u003c/artifactId\u003e\n    \u003cversion\u003e3.0-8\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nOthers are of course available, see [maven central](https://central.sonatype.com/artifact/me.bechberger/ap-loader-all/3.0-8).\n\nYou can also use [JBang](https://jbang.dev) to simplify the usage of ap-loader. There are examples in documentation below.\n\nSupported Platforms\n-------------------\n\n- Required Java version: 8 or higher\n- Supported OS: Linux and macOS (on all platforms the async-profiler has binaries for)\n\nVariants\n--------\nThe JAR can be obtained in the following variants:\n\n- `macos`, `linux-x64`, ...: `jattach`, `profiler.sh`/`asprof` and `libasyncProfiler.so` for the given platform\n- `all`: all of the above\n\nRegarding file sizes: The `all` variant are` `typically around 800KB and the individual variants around 200 to 400KB.\n\nCommands\n--------\n\nThe following is a more in-depth description of the commands of `java -jar ap-loader.jar`.\n\nTo run with JBang you can do `jbang ap-loader@jvm-profiling-tools/ap-loader` or install it as an application:\n\n```sh\njbang app install ap-loader@jvm-profiling-tools/ap-loader\n```\n\nand run it directly with `ap-loader` instead of `java -jar ap-loader.jar`.\n\nIf you want to install a specific `ap-loader` rather than latest you can use `jbang app install me.bechberger:ap-loader-all:\u003cversion\u003e`.\n\nBe aware that it is recommended to run the JVM with the\n`-XX:+UnlockDiagnosticVMOptions -XX:+DebugNonSafepoints` flags.\nThis improves the accuracy of the profiler.\n\nOverview of the commands:\n\n```sh\nUsage: java -jar ap-loader.jar \u003ccommand\u003e [args]\nCommands:\n  help         show this help\n  jattach      run the included jattach binary\n  profiler     run the included profiler.sh/asprof script\n  agentpath    prints the path of the extracted async-profiler agent\n  jattachpath  prints the path of the extracted jattach binary\n  supported    fails if this JAR does not include a profiler for the current OS and architecture\n  converter    run the included converter\n  version      version of the included async-profiler\n  clear        clear the directory used for storing extracted files\n```\n\n### jattach\n\n`java -jar ap-loader.jar jattach` is equivalent to calling the suitable `jattach` binary\nfrom [GitHub](https://github.com/apangin/jattach)\u003e:\n\n```sh\n# Load a native agent\njava -jar ap-loader.jar jattach \u003cpid\u003e load \u003c.so-path\u003e { true | false, is path absolute? } [ options ]\n\n# Load a java agent\njava -jar ap-loader.jar jattach \u003cpid\u003e load instrument false \"javaagent.jar=arguments\"\n\n# Running the help command for jcmd\njava -jar ap-loader.jar jattach \u003cpid\u003e jcmd \"help -all\"\n```\n\nSee the [GitHub page of jattach](https://github.com/apangin/jattach) for more details.\n\n### profiler\n\n`java -jar ap-loader.jar profiler` is equivalent to calling the suitable `profiler.sh`/`asprof`:\n\n```sh\n# Profile a process for `n` seconds\njava -jar ap-loader.jar profiler -d \u003cn\u003e \u003cpid\u003e\n\n# Profile a process for allocation, CPU and lock events and save the results to a JFR file\njava -jar ap-loader.jar profiler -e alloc,cpu,lock -f \u003cfile.jfr\u003e \u003cpid\u003e\n```\n\nSee the [GitHub page of async-profiler](https://github.com/jvm-profiling-tools/async-profiler) for more details.\n\n### supported\n\nAllows you to check whether your JAR includes a `jattact`, `profile.sh` and `libasyncProfiler.so` for\nyour current OS and architecture.\n\n### converter\n\n`java -jar ap-loader.jar converter` is equivalent to calling the included converters:\n\n```sh\njava -jar ap-loader.jar converter \u003cConverter\u003e [options] \u003cinput\u003e \u003coutput\u003e\n\n# Convert a JFR file to flame graph\njava -jar ap-loader.jar converter jfr2flame \u003cinput.jfr\u003e \u003coutput.html\u003e\n```\n\nThe available converters depend on the included async-profiler version.\nCall `java -jar ap-loader.jar converter` to a list of available converters, see\n[the source code on GitHub](https://github.com/jvm-profiling-tools/async-profiler/blob/master/src/converter/Main.java)\nfor more details.\n\n### clear\n\nClear the application directory used for storing extracted files,\nlike `/Users/\u003cuser\u003e/Library/Application Support/me.bechberger.ap-loader-\u003cversion\u003e/`\nto redo the extraction on the next run.\n\n\nRunning as an agent\n-------------------\n\n`java -javaagent:ap-loader.jar=\u003coptions\u003e` is equivalent to `java -agentpath:libasyncProfiler.so=\u003coptions\u003e`\nwith a suitable library.\nThis can be used to profile a Java process from the start.\n\n```sh\n# Profile the application and output a flame graph\njava -javaagent:ap-loader.jar=start,event=cpu,file=profile.html \u003cjava arguments\u003e\n```\n\nWith JBang you can do:\n\n```sh\njbang --javaagent:ap-loader@jvm-profiling-tools/ap-loader=start,event=cpu,file=profile.html \u003cjava arguments\u003e\n```\n\nSee the [GitHub page of async-profiler](https://github.com/jvm-profiling-tools/async-profiler) for more details.\n\nUsage in Java Code\n------------------\n\nThen you can use the `AsyncProfilerLoader` class to load the native library:\n\n```java\nAsyncProfiler profiler = one.profiler.AsyncProfilerLoader.load();\n```\n\n`AsyncProfiler` is\nthe [main API class](https://github.com/jvm-profiling-tools/async-profiler/blob/master/src/api/one/profiler/AsyncProfiler.java)\nfrom the async-profiler.jar.\n\nThe API of the `AsyncProfilerLoader` can be used to execute all commands of the CLI programmatically.\n\nThe converters reside in the `one.converter` package.\n\nAttaching a Custom Agent Programmatically\n---------------------------------\nA notable part of the API are the jattach related methods that allow you to call `jattach` to attach\nyour own native library to the currently running JVM:\n\n```java\n// extract the agent first from the resources\nPath p = one.profiler.AsyncProfilerLoader.extractCustomLibraryFromResources(....getClassLoader(), \"library name\");\n// attach the agent to the current JVM\none.profiler.AsyncProfilerLoader.jattach(p, \"optional arguments\")\n// -\u003e returns true if jattach succeeded\n```\n\n### Releases\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eme.bechberger\u003c/groupId\u003e\n  \u003cartifactId\u003eap-loader-variant\u003c/artifactId\u003e\n  \u003cversion\u003eversion\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nThe latest `all` version can be added via:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eme.bechberger\u003c/groupId\u003e\n  \u003cartifactId\u003eap-loader-all\u003c/artifactId\u003e\n  \u003cversion\u003e3.0-8\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nBuild and test\n--------------\n\nThe following describes how to build the different JARs and how to test them.\nIt requires a platform supported by async-profiler and Python 3.6+.\n\n### Build the JARs using maven\n\n```sh\n# download the release sources and binaries\npython3 ./bin/releaser.py download 3.0\n\n# build the JAR for the release\n# maven might throw warnings, related to the project version setting,\n# but the alternative solutions don't work, so we ignore the warning for now\nmvn -Dproject.vversion=3.0 -Dproject.subrelease=7 -Dproject.platform=macos package assembly:single\n# use it\njava -jar target/ap-loader-macos-3.0-8-full.jar ...\n# build the all JAR\nmvn -Dproject.vversion=3.0 -Dproject.subrelease=7 -Dproject.platform=all package assembly:single\n```\n\nDevelopment\n-----------\nThis project is written in Java 8, to support all relevant platforms.\nThe feature set should not increase beyond what is currently:\nJust build your library on top of it. But I'm of course happy for bug reports and fixes.\n\nThe code is formatted using [google-java-format](https://github.com/google/google-java-format).\n\n### bin/releaser.py\n\n```sh\nUsage:\n    python3 ./bin/releaser.py \u003ccommand\u003e ... \u003ccommand\u003e [release or current if not present]\n\nCommands:\n current_version   print the youngest released version of async-profiler\n    versions          print all released versions of async-profiler (supported by this project)\n    download          download and prepare the folders for the given release\n    build             build the wrappers for the given release\n    test              test the given release\n    deploy_mvn        deploy the wrappers for the given release as a snapshot to maven\n    deploy_gh         deploy the wrappers for the given release as a snapshot to GitHub\n    deploy            deploy the wrappers for the given release as a snapshot\n    deploy_release    deploy the wrappers for the given release\n    clear             clear the ap-releases and target folders for a fresh start\n```\n\nDeploy the latest version via ` bin/releaser.py download build test deploy` as a snapshot.\n\nFor a release use `bin/releaser.py download build test deploy_release`,\nbut before make sure to do the following for a new sub release:\n\n- update the version number in the README\n- update the changelog in the README and `bin/releaser.py`\n- and increment the `SUB_VERSION` variable in `bin/releaser.py` afterwards\n\nAnd the following for a new async-profiler release:\n- update the version in the README\n\nChangelog\n---------\n\n### Unreleased\n\n- Fix FlameGraph converter [#22](https://github.com/jvm-profiling-tools/ap-loader/issues/22)\n\n### v8\n\n- Support for [async-profiler 3.0](https://github.com/async-profiler/async-profiler/releases/tag/v3.0)\n- Breaking changes with async-profiler 3.0:\n  - async-profiler 3.0 changed the meaning of the `--lib` option from `--lib path        full path to libasyncProfiler.so in the container`\n    to `-l, --lib         prepend library names`, so the `AsyncProfilerLoader` will throw an UnsupportedOperation exception\n    when using the `--lib` option with a path argument and async-profiler 3.0 or higher\n\n### v7\n\n- Drop dev.dirs:directories dependency #13 (thanks to @jsjant for spotting the potential licensing issue and fixing it in #14)\n\n### v6\n\n- Fix Linux Arm64 release #12 (thanks to @dkrawiec-c for fixing this issue)\n\n### v5\n\n- Add new jattach methods (`AsyncProfilerLoader.jattach(Path agent, String args)`) to make using it programmatically easier\n- Add new `AsyncProfilerLoader.extractCustomLibraryFromResources(ClassLoader, String)`\n  method to extract a custom library from the resources\n  - this also has a variant that looks in an alternative resource directory if the resource does not exist\n\n### v4\n\n- `AsyncProfiler.isSupported()` now returns `false` if the OS is not supported by any async-profiler binary, fixes #5\n\n### v3\n\n- Create specific artifacts for each platform fixing previous issues with maven version updates (issue #4, thanks @ginkel for reporting it)\n\n\n### v2\n- Fixed the library version in the pom #3 again\n  (thanks to @gavlyukovskiy, @dpsoft and @krzysztofslusarski for spotting the bug)\n\n### v1\n- Fixed the library version in the pom #3 (thanks to @gavlyukovskiy for spotting the bug)\n\n### v0\n- 11.11.2022: Improve Converter\n\n## License\nApache 2.0, Copyright 2023 SAP SE or an SAP affiliate company, Johannes Bechberger\nand ap-loader contributors\n\n\n*This project is maintained by the [SapMachine](https://sapmachine.io) team\nat [SAP SE](https://sap.com)*","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjvm-profiling-tools%2Fap-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjvm-profiling-tools%2Fap-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjvm-profiling-tools%2Fap-loader/lists"}