{"id":13591018,"url":"https://github.com/giltene/jHiccup","last_synced_at":"2025-04-08T14:32:19.151Z","repository":{"id":11171941,"uuid":"13547035","full_name":"giltene/jHiccup","owner":"giltene","description":"jHiccup is a non-intrusive instrumentation tool that logs and records\nplatform \"hiccups\" - including the JVM stalls that often happen when\nJava applications are executed and/or any OS or hardware platform noise\nthat may cause the running application to not be continuously runnable.","archived":false,"fork":false,"pushed_at":"2024-05-27T18:38:26.000Z","size":882,"stargazers_count":686,"open_issues_count":13,"forks_count":92,"subscribers_count":52,"default_branch":"master","last_synced_at":"2025-04-03T18:15:29.530Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/giltene.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING.txt","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,"publiccode":null,"codemeta":null}},"created_at":"2013-10-13T21:31:14.000Z","updated_at":"2025-03-25T15:08:26.000Z","dependencies_parsed_at":"2024-10-13T20:42:12.646Z","dependency_job_id":"0313e1dc-cf51-42d9-a6cf-e51812dd2fc0","html_url":"https://github.com/giltene/jHiccup","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giltene%2FjHiccup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giltene%2FjHiccup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giltene%2FjHiccup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giltene%2FjHiccup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/giltene","download_url":"https://codeload.github.com/giltene/jHiccup/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247860910,"owners_count":21008380,"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":[],"created_at":"2024-08-01T16:00:52.780Z","updated_at":"2025-04-08T14:32:18.747Z","avatar_url":"https://github.com/giltene.png","language":"Java","funding_links":[],"categories":["Java","V. Tools for developing","Projects","项目","Performance analysis","Application Performance Monitoring Tools"],"sub_categories":["3. Perfomance tools","Performance analysis","性能分析","Other"],"readme":"\u003ca href=\"https://foojay.io/works-with-openjdk\"\u003e\u003cimg align=\"right\" src=\"https://github.com/foojayio/badges/raw/main/works_with_openjdk/Works-with-OpenJDK.png\" width=\"100\"\u003e\u003c/a\u003e\n\n# jHiccup\n[![Build Status](https://travis-ci.org/giltene/jHiccup.svg?branch=master)](https://travis-ci.org/giltene/jHiccup)\n[![Java CI](https://github.com/giltene/jhiccup/workflows/Java%20CI/badge.svg)](https://github.com/giltene/jHiccup/actions)\n[![Gitter](https://img.shields.io/gitter/room/gitterHQ/gitter.svg)](https://gitter.im/giltene/jHiccup?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n----------------------------------------------------------------------------\n\nWritten by Gil Tene of Azul Systems, and released to the public domain\nas explained at http://creativecommons.org/publicdomain/zero/1.0\n\n----------------------------------------------------------------------------\n\nVersion: 2.0.10\n----------------------------------------------------------------------------\n\njHiccup is a non-intrusive instrumentation tool that logs and records\nplatform \"hiccups\" - including the JVM stalls that often happen when\nJava applications are executed and/or any OS or hardware platform noise\nthat may cause the running application to not be continuously runnable.\n\njHiccup can be executed in one of three main ways:\n\n1. It can be run as a Java agent (using: `java -javaagent:jHiccup.jar`)\n\n2. It can be injected into a running application (using: `jHiccup -p \u003cpid\u003e`)\n\n3. It can also be run using a convenient wrapper command for your\n   existing Java application (using: `jHiccup java myProg ...`)\n\n----------------------------------------------------------------------------\n\n### Example jHiccup plot \n![example plot]\n \n----------------------------------------------------------------------------\n# Using jHiccup as a Java agent:\n\njHiccup is most often used as a Java agent. This is useful for platforms and\nenvironments where a Java agent is simpler to integrate into launch scripts,\nor in environments where using the bash jHiccup wrapper script is not practical\n(e.g. Windows, and environments where java is not directly launched from\nthe command line).\n\njHiccup.jar can be used as a Java agent using the following launch syntax:\n\n    % java -javaagent:jHiccup.jar MyProgram\n\nor\n\n    % java -javaagent:jHiccup.jar=\"\u003coptions\u003e\" MyProgram.jar -a -b -c\n\nYou can find the available options for the Java agent mode by running:\n\n    % java -javaagent:jHiccup.jar=\"-h\"\n\nHere is a Java agent usage example with explicit parameters:\n\n    % java -javaagent:jHiccup.jar=\"-d 2000 -i 1000 -l hiccuplog -c\" MyProgram.jar -a -b -c\n\nThis example will record hiccups experienced during the running of `MyProgram.jar`\nin log file `hiccuplog`, while at the same time recording the hiccups experienced by\na control process running in a separate JVM in the log file `c.hiccuplog`.\nMeasurement will start 2 seconds after startup (rather than immediately),\nand interval data will be recorded every 1 second (rather than the default 5 seconds).\n\nUseful Java agent related notes:\n\nNote 1: When used as a java agent, jHiccup will treat spaces, commas, and\nsemicolons as delimiting characters (`[ ,;]+`). For example, the option string\n`-d 0 -i 1000` is equivalent to the option string `-d,0,-i,1000`. This is\nuseful for environments where placing space delimiters into quoted strings\nis difficult or confusing.\n\nNote 2: I find that a common way people add jHiccup as a Java agent is by using\nthe `_JAVA_OPTIONS` environment variable. This often allows one to add the jHiccup\nJava agent without significant launch script surgery. For example:\n\n    export _JAVA_OPTIONS='-javaagent:/path/to/jHiccup/target/jHiccup.jar=\"-d 20000 -i 1000\"'\n\n----------------------------------------------------------------------------\n\n# Reading and processing the jHiccup log with jHiccupLogProcessor:\n\njHiccup logs hiccup information in a histogram log (see \n[HdrHistogram.org](http://hdrhistogram.org/)). This histogram log contains a full, high fidelity\nhistogram of all collected results in each interval, in a highly compressed\nform (typically using only ~200-400 bytes per interval). However, other than\nthe timestamp and maximum hiccup magnitude found in the given interval, the\nrest of the log line for each interval is not human readable (it is a base64\nencoding of a compressed HdrHistogram).\n\nTo translate the jHiccup log file to a more human-readable form, the jHiccupLogProcessor\nutility is provided. In it's simplest form, this utility can be used as such\n\n    % jHiccupLogProcessor -i mylog.hlog -o mylog\n\nWhich will produce log files `mylog` and `mylog.hgrm` containing a human readable\ninterval log (with selected percentiles in each interval), as well as a human\nreadable histogram percentile distribution log.\n\njHiccupLogProcessor can also be used to produce log files for an arbitrary\nsection of the jHiccup log, by using the optional `-start` and `-end` parameters.\n\nSee `jHiccupLogProcessor -h` for more details.\n\n----------------------------------------------------------------------------\n\n# Hiccup Charts: Plotting jHiccup results\n\nSince jHiccup uses [HdrHistogram](http://hdrhistogram.org/) and produces\nHdrHistogram logs, various tools that plot and view histogram logs can be\nused to analyze jhiccup data. Some common tools include\n[HistggramLogAnalyzer](https://github.com/HdrHistogram/HistogramLogAnalyzer)\n, [HdrHistogramVisualizer](https://github.com/ennerf/HdrHistogramVisualizer)  \n, and a javascript-based in-browser [histogram log parser](https://hdrhistogram.github.io/HdrHistogramJSDemo/logparser.html)\n\n----------------------------------------------------------------------------\n\n# Launching jHiccup by attaching it to existing, running application:\n\nThe jHiccup agent can be injected into a live, running Java application\nif the environment supports the java attach API (which is typically available\nin java environments running Java SE 6 or later).\n\n$ jHiccup -p \u003cpid\u003e\n\nNOTE: In order to attach to a running java application, the running\napplication needs to have `${JAVA_HOME}/lib/tools.jar` in it's classpath.\nWhile this is commonly the case already for many IDE and desktop environments,\nand for environments that involve or enable other attachable agents (such as\nprofilers), you may find that it is not included in your application's\nclasspath, and that it needs to be added if attaching jHiccup at runtime\nis needed (launching jHiccup as a Java agent per the below may be a good\nalternative).\n\n----------------------------------------------------------------------------\n\n# Running jHiccup using the Wrapper Script form:\n\nIn the wrapper script form, all it takes is adding the word \"jHiccup\" in\nfront of whatever the java invocation command line is.\n\nFor example, if your program were normally executed as:\n\n    java \u003cJava args\u003e MyProgram -a -b -c\n\nThe launch line would become:\n\n    jHiccup java \u003cJava args\u003e MyProgram -a -b -c\n\nor, for a program launched with:\n\n    /usr/bin/java \u003cJava args\u003e -jar MyProgram.jar -a -b -c\n\nThe launch line would become:\n\n    jHiccup /usr/bin/java \u003cJava args\u003e -jar MyProgram.jar -a -b -c\n\nor, to override the defaults by making the recording start delay 60 seconds\nand log to hlog, it would become:\n\n    jHiccup -d 60000 -l hlog /usr/bin/java \u003cJava args\u003e -jar MyProgram.jar -a -b -c\n\nThe jar file also includes a simple \"Idle\" class to facilitate sanity checks\nwithout an external program. Here is a simple sanity test example: jHiccup\nwith a 4 sec delay on recording start, wrapping an Idle run that does nothing\nfor 30 seconds and exits:\n\n    % jHiccup -d 4000 /usr/bin/java org.jhiccup.Idle -t 30000\n\n[Run `jHiccup -h`, or see comment in jHiccup script for more details.]\n\n----------------------------------------------------------------------------\n\n# Supported/Tested platforms:\n\nThe jHiccup command is expected to work and has been tested on the following\nplatforms:\n- Various Linux flavors (Tested on RHEL/CentOS 5.x and 6.x)\n- Mac OS X (tested on Lion, 10.7)\n- Windows with a Cygwin environment installed (tested on Windows 7)\n- Solaris (tested on both SPARC and x86)\n\njHiccup.jar is expected to work as a java agent and has been tested on the\nfollowing platforms:\n- Various Linux flavors (Tested on RHEL/CentOS 5.x and 6.x)\n- Mac OS X (tested on Lion, 10.7)\n- Windows standard command shell (tested on Windows 7)\n- Solaris (tested on both SPARC and x86)\n\nIf you use jHiccup on other operating systems and setups, please report back\non your experience so that we can expand the list.\n\n----------------------------------------------------------------------------\n\n# Using a control process to concurrently record baseline idle load hiccups:\n\nIt is often useful to compare the hiccup behavior experienced by a running\napplication with a \"control\" hiccup level of an idle workload, running on\nthe same system and at the same time as the observed application. To make\nsuch control measurement convenient, jHiccup supports a `-c` option that will\nlaunch a concurrently executing \"control process\" and will separately log\nhiccup information of an idle workload running on a separate jvm for the\nduration of the instrumented application run. When selected, the control\nprocess log file name will match those used for the launching application,\nfollowed with a `.c`.\n\nFor example:\n\n    % jHiccup -l mylog -c /usr/bin/java \u003cJava args\u003e -jar MyProgram.jar -a -b -c\n\nWill produce log file `mylog` detailing the hiccup behavior during the\nexecution of `MyProgram.jar`, as well as a log file `c.mylog` detailing\nthe hiccup behavior of an idle workload running on a separate jvm at\nthe same time.\n\n----------------------------------------------------------------------------\n\n# Log file name recognizes and fills in %pid , %date , and %host terms\n\nWhen a log file name is specified with the `-l` option, the terms `%pid`,\n`%date`,  and `%host` will be filled in with the appropriate information.\nThe default log file name setting is simply `hiccup.%date.%pid`.\n\n----------------------------------------------------------------------------\n\n# Using jHiccup to process latency log files:\n\njHiccup's main HiccupMeter class supports a mode `-f` that will take latency\ninput from a file instead of recording it. This is useful for producing\njHiccup-style text and graphical output for recorded latency data collected\nby some other means.\n\nWhen provided to the `-f` option, an input file is expected to contain two\nwhite-space delimited values per line (in either integer or real number format),\nrepresenting a time stamp and a measured latency, both in millisecond units.\n\nIt's important to note that the default \"expected interval between samples\"\nresolution in jHiccup and HiccupMeter is 1 millisecond. When processing\ninput files, it is imperative that an appropriate value be supplied to\nthe `-r` option, and that this value correctly represent the expected interval\nbetween samples in the provided input file. HiccupMeter will use this\nparameter to determine whether additional, artificial values should be added\nto the histogram recording, between input samples that are farther apart in\ntime than the expected interval specified to the `-r` option. This behavior\ncorrects for \"coordinated omission\" situations (where long response times\nlead to \"skipped\" requests that would have typically correlated with \"bad\"\nresponse times). A \"large\" value (e.g. `-r 100000`) can easily be specified\nto avoid any correction of this situation.\n\nExample:\n\n    % java -jar jHiccup.jar -i 1000 -f inputLatenies -l latencies.hlog\n\n----------------------------------------------------------------------------\n\n# Using jHiccup to process pause logs from e.g. gc log files:\n\nWhen run in the file injection mode (`-f`), jHiccup's main HiccupMeter\nclass supports an optional \"fill zeros\" (`-fz`) mode. This mode is\nuseful for processing input that represent pause events rather than\nlatencies.\n\nA common use case for this feature is producing hiccup logs from GC logs.\nGC logs will generally include pause information, which can be parsed out\nto a \"pauses log\". jHiccup can takes a \"pauses logs\" as input\n\n\nWhen provided to the `-f` option, in conjunction with a `-fz` option, an\ninput file is expected to contain two white-space delimited values per\nline (in either integer or real number format), representing a time stamp\nand a measured length of a pause, both in millisecond units.\n\nExample (parsing gc log with +PrintGCTimeStamps):\n\n    % java ... -XX:+PrintGCApplicationStoppedTime -XX:+PrintGCTimeStamps -Xloggc:gc.log ...\n    \n    % awk -F\": \" '/Total time for which application threads were stopped/ {printf \"%4.0f %4.3f\\n\", $1*1000.0, $3*1000.0;}' gc.log \u003e gcPauses.log\n\n    % java -jar jHiccup.jar -i 1000 -f gcPauses.log -fz -l pauses.hlog\n  \nExample (with both +PrintGCTimeStamps and +PrintGCDateStamps):\n  \n    % java ... -XX:+PrintGCApplicationStoppedTime -XX:+PrintGCTimeStamps -XX:+PrintGCDateStamps -Xloggc:gc.log ...\n     \n    % awk -F\": \" '/Total time for which application threads were stopped/ {printf \"%4.0f %4.3f\\n\", $2*1000.0, $4*1000.0;}' gc.log \u003e gcPauses.log\n \n    % java -jar jHiccup.jar -i 1000 -f gcPauses.log -fz -l pauses.hlog\n    \n\n----------------------------------------------------------------------------\n\n# Example: adding jHiccup to Tomcat runs:\n\nIn Tomcat's `catalina.sh` script, replace the following line:\n\n    exec \"$_RUNJAVA\" \"$LOGGING_CONFIG\" $JAVA_OPTS $CATALINA_OPTS\n\nwith:\n\n    exec \"$JHICCUP_HOME/jHiccup\" \"$_RUNJAVA\" \"$LOGGING_CONFIG\" $JAVA_OPTS $CATALINA_OPTS\n\n----------------------------------------------------------------------------\n\n# Note: Use of HdrHistogram.\n\njHiccup depends on and makes systemic use of HdrHistogram to collected and\nreport on the statistical distribution of hiccups. HdrHistogram sources\nand documentation can be found on GitHub, at\nhttp://hdrhistogram.github.io/HdrHistogram/\n\n----------------------------------------------------------------------------\n\n# Building jHiccup:\n\njHiccup can be (re)built from source files using Maven:\n\n    % mvn package\n\n[example plot]:https://raw.github.com/giltene/jHiccup/master/examplePlot.png \"Example jHiccup plot\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiltene%2FjHiccup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiltene%2FjHiccup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiltene%2FjHiccup/lists"}