{"id":16800506,"url":"https://github.com/undera/perfmon-agent","last_synced_at":"2025-04-14T20:53:43.470Z","repository":{"id":6986548,"uuid":"8249130","full_name":"undera/perfmon-agent","owner":"undera","description":"Server metrics fetching agent, based on SIGAR","archived":false,"fork":false,"pushed_at":"2023-06-20T08:00:50.000Z","size":182,"stargazers_count":401,"open_issues_count":17,"forks_count":138,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-04-07T14:09:28.626Z","etag":null,"topics":["agent","java","jmeter","monitoring"],"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/undera.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,"publiccode":null,"codemeta":null}},"created_at":"2013-02-17T10:21:55.000Z","updated_at":"2025-03-31T08:41:24.000Z","dependencies_parsed_at":"2024-11-13T16:41:08.495Z","dependency_job_id":"b557fdf0-6f06-4a15-992a-2be0ff8e6f66","html_url":"https://github.com/undera/perfmon-agent","commit_stats":{"total_commits":53,"total_committers":7,"mean_commits":7.571428571428571,"dds":0.6981132075471699,"last_synced_commit":"e6e73892b81b79a92628c7d2b7144c3918bcb152"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/undera%2Fperfmon-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/undera%2Fperfmon-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/undera%2Fperfmon-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/undera%2Fperfmon-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/undera","download_url":"https://codeload.github.com/undera/perfmon-agent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248961079,"owners_count":21189990,"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":["agent","java","jmeter","monitoring"],"created_at":"2024-10-13T09:33:37.588Z","updated_at":"2025-04-14T20:53:43.443Z","avatar_url":"https://github.com/undera.png","language":"Java","readme":"[![Build Status](https://travis-ci.org/undera/perfmon-agent.png?branch=master)](https://travis-ci.org/undera/perfmon-agent)\n# PerfMon Server Agent\n\nAgent application to access system metrics on remote machines.\n\n\u003e :warning: **It's very out-of-date for modern technology**\n\u003e \n\u003e Since it relies on [SIGAR](https://github.com/hyperic/sigar) library to gather metrics, with that library last updated in 2010, ServerAgent won't work on many modern systems.\n\n## Download\n\n[ServerAgent-2.2.3.zip](https://github.com/undera/perfmon-agent/releases/download/2.2.3/ServerAgent-2.2.3.zip)\n\n(previous [ServerAgent-2.2.1.zip](https://github.com/undera/perfmon-agent/releases/download/2.2.1/ServerAgent-2.2.1.zip))\n\n## Installation\n\n_You do not need any root/admin privilege_. You can just unzip the the ServerAgent-X.X.X.zip somewhere on the server. Then launch the agent using `startAgent.sh` script on Unix, or `startAgent.bat` script on Windows.\n\nThe agent is written in Java, you will need JRE 1.5 or later to run it. \nNote you can create yourself the agent package which includes its own JRE \nso you don't have to install java on the server (We tested it on windows platform).\nTo do this, just create a JRE folder in the agent folder and copy one installed \nJRE inside. Change the java command inside the .bat file to the path to the \njava executable and it will work.\n\n## Usage\nTo start the agent, simply run `startAgent.bat/sh` file. It will open UDP/TCP\nserver ports where clients can connect and query the metrics. Some information \nwill be printed to standard output, informing you on problems gathering metrics \n(logging verbosity regulated with `--loglevel parameter`).\n\nYou can specify the listening ports as arguments (0 disables listening), default is 4444:\n\n```\n$ ./startAgent.sh --udp-port 0 --tcp-port 3450\nINFO    2011-11-25 19:02:14.315 [kg.apc.p] (): Binding TCP to 3450\n```\n\nYou can use the `--auto-shutdown` option when starting the agent to automatically \nstop it once the last client is disconnected. It is recommended to use this feature only with \nTCP connections:\n\n```\n$ undera@undera-HP:/tmp/serverAgent$ ./startAgent.sh --udp-port 0 --auto-shutdown\nINFO    2011-11-25 19:48:59.321 [kg.apc.p] (): Agent will shutdown when all clients disconnected\nINFO    2011-11-25 19:48:59.424 [kg.apc.p] (): Binding TCP to 4444\n```\n\nYou can use the `--sysinfo` option to view available system objects:\n\n```\n$ ./startAgent.sh --sysinfo\nINFO    2011-11-25 19:51:25.517 [kg.apc.p] (): *** Logging available processes ***\nINFO    2011-11-25 19:51:25.542 [kg.apc.p] (): Process: pid=24244 name=bash args=-bash\nINFO    2011-11-25 19:51:25.543 [kg.apc.p] (): Process: pid=25086 name=dash args=/bin/sh ./startAgent.sh --sysinfo\nINFO    2011-11-25 19:51:25.543 [kg.apc.p] (): Process: pid=25088 name=java args=java -jar ./CMDRunner.jar --tool PerfMonAgent --sysinfo\nINFO    2011-11-25 19:51:25.549 [kg.apc.p] (): *** Logging available filesystems ***\nINFO    2011-11-25 19:51:25.551 [kg.apc.p] (): Filesystem: fs=/dev type=devtmpfs\nINFO    2011-11-25 19:51:25.551 [kg.apc.p] (): Filesystem: fs=/ type=ext4\nINFO    2011-11-25 19:51:25.551 [kg.apc.p] (): Filesystem: fs=/var/run type=tmpfs\nINFO    2011-11-25 19:51:25.551 [kg.apc.p] (): Filesystem: fs=/home type=ext4\nINFO    2011-11-25 19:51:25.552 [kg.apc.p] (): Filesystem: fs=/var/lock type=tmpfs\nINFO    2011-11-25 19:51:25.552 [kg.apc.p] (): Filesystem: fs=/proc type=proc\nINFO    2011-11-25 19:51:25.553 [kg.apc.p] (): *** Logging available network interfaces ***\nINFO    2011-11-25 19:51:25.554 [kg.apc.p] (): Network interface: iface=lo addr=127.0.0.1 type=Local Loopback\nINFO    2011-11-25 19:51:25.554 [kg.apc.p] (): Network interface: iface=eth0 addr=192.168.0.1 type=Ethernet\nINFO    2011-11-25 19:51:25.555 [kg.apc.p] (): *** Done logging sysinfo ***\nINFO    2011-11-25 19:51:25.555 [kg.apc.p] (): Binding UDP to 4444\nINFO    2011-11-25 19:51:26.560 [kg.apc.p] (): Binding TCP to 4444\n```\n\nThe `--interval \u003cseconds\u003e` argument can be used to change metrics collection frequency.\n\n## Using Server Agent With Other Applications\n\nServer Agent uses simple plain-text protocol, anyone can use agent's \ncapabilities implementing client, based on `kg.apc.perfmon.client.Transport`\ninterface. If anyone's interested, start the topic on the support forums and I'll describe how to\nconnect third-party client app to agent.\n\nServerAgent has simple text protocol and can work on UDP and TCP transports. Most of cases will use TCP.\n\nTo have your first talk with the agent, start it locally. Then use telnet utility to connect to it:\n\n```\nuser@ubuntu:~$ telnet localhost 4444\nTrying 127.0.0.1...\nConnected to localhost.\nEscape character is '^]'.\n```\n\nIf connection has succeeded, you should see \"Accepting new TCP connection\" message in ServerAgent console log. Type \"test\" and press Enter in telnet chat, server should answer with short \"Yep\":\n\n```\ntest\nYep\n```\n\nType \"exit\":\n\n```\nexit\nConnection closed by foreign host.\n```\n\nThat's it. You sending a command line, server answering. Command line consists of command, sometimes with parameters. Parameters are separated from command with a colon sign.\n\nPossible commands are: \n  * exit - terminates current client session and closes connection to agent, no parameters\n  * test - test if server is alive, no parameters\n  * shutdown - terminate all client connections and shutdown agent process, no parameters\n  * interval - change metrics reporting interval used in 'metrics' command, single parameter is integer value in seconds. Interval can be changed in the middle of metrics reporting. Example: `interval:5`\n  * metrics - starts automatic metrics collection, parameters are metrics list to collect, described below. Example: `metrics:cpu`\n  * metrics-single - calls single metric collection iteration. Example: `metrics-single:memory`\n\n### Specifying Metrics\nMetrics list consists of metric specifications, separated by TAB character. Metric collection output consists of float values, TAB separated. Example:\n\n```\nmetrics-single:cpu\u003cTAB\u003ememory\n22.05736894164194\u003cTAB\u003e57.52359562205553\n```\nEach metric specification consists of several fields, colon-separated. Short example:\n\n```\nmetrics-single:cpu:idle    memory:free\n80.02238388360381    57.52359562205553\n```\n\nFields number is metric-type specific. Possible metric types are:\n  * cpu\n  * memory\n  * swap\n  * disks\n  * network\n  * tcp\n  * tail\n  * exec\n  * jmx\n\nFields corresponding to each metric type are described below. \nLast example (Yep, ServerAgent can be shell exec vulnerability. If you have issue with this, ask me and I'll introduce 'secure' mode, disabling insecure metric types):\n\n```\nmetrics-single:exec:/bin/sh:-c:free | grep Mem | awk '{print $7}'\n1152488\n```\n\n## Viewing Available System Objects\nServer Agent has special command-line option `--sysinfo` \nfor printing available processes, filesystems and network interfaces together \nwith their selectors.\n\n# Supported Metrics\n\n## CPU Metrics \n### Total \nPrimary\n  * *combined* \n  * idle \n  * system \n  * user \n  * iowait\n\nAdditional \n  * irq \n  * nice \n  * softirq \n  * stolen \n\n### Per Process \n  * *percent*\n  * total \n  * system \n  * user\n\n## Memory Metrics \n### Total \nPrimary\n  * *usedperc* - relative memory usage in percents\n  * freeperc\n  * used \n  * free\n\nAdditional\n  * actualfree \n  * actualused  \n  * ram \n  * total \n\n### Per Process \nPrimary \n  * *resident*\n  * virtual\n  * shared\n\nAdditional\n  * pagefaults\n  * majorfaults\n  * minorfaults \n\n## Disk I/O Metrics  \nPrimary\n  * *queue*\n  * reads \n  * writes \n  * readbytes\n  * writebytes \n\nAdditional\n  * available\n  * service\n  * files\n  * free\n  * freefiles\n  * total\n  * useperc\n  * used\n\n## Network I/O Metrics  \nPrimary\n  * *bytesrecv*\n  * bytessent \n  * rx \n  * tx\n\nAdditional\n  * used\n  * speed \n  * rxdrops\n  * rxerr\n  * rxframe\n  * rxoverruns\n  * txcarrier\n  * txcollisions\n  * txdrops\n  * txerr\n  * txoverruns\n\n## JMX Metrics \n\nSince version 0.5.2 Server Agent has ability to monitor some [JMX](http://docs.oracle.com/javase/6/docs/api/javax/management/package-summary.html#package_description)\nvalues inside Java Virtual Machine. To enable JMX monitoring you must start Java \nwith some special properties enabled, like described [here](http://docs.oracle.com/javase/6/docs/technotes/guides/management/agent.html).\nHere's simplest (and not so secure) options to start Java with JMX enabled:\n\n```\njava -Dcom.sun.management.jmxremote.port=4711 -Dcom.sun.management.jmxremote.authenticate=false \\\n  -Dcom.sun.management.jmxremote.local.only=false -Dcom.sun.management.jmxremote.ssl=false \u003cother options\u003e\n```\n\nBy default the Server Agent will try to connect to JMX server at localhost with port 4711. \nIf you started JMX server at different host/port or using authentication with username/password,\nplease, use following additional parameters:\n  * `url=\u003chostname\u003e\\:\u003cport\u003e`\n  * `user=\u003cusername\u003e`\n  * `password=\u003cpassword\u003e`\n\nAvailable JMX metric types:\n  * gc-time - time spent in garbage collection, milliseconds ([used method](http://docs.oracle.com/javase/6/docs/api/java/lang/management/GarbageCollectorMXBean.html#getCollectionTime()))\n  * memory-usage - heap memory used by VM, bytes ([method used](http://docs.oracle.com/javase/6/docs/api/java/lang/management/MemoryMXBean.html#getHeapMemoryUsage()))\n  * memory-committed - heap memory committed by VM, bytes ([method used](http://docs.oracle.com/javase/6/docs/api/java/lang/management/MemoryMXBean.html#getHeapMemoryUsage()))\n  * memorypool-usage - heap memory pool usage, bytes ([method used](http://docs.oracle.com/javase/6/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage())) \n  * memorypool-committed - heap memory pool committed size, bytes ([method used](http://docs.oracle.com/javase/6/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage())) \n  * class-count - loaded class count in VM ([used method](http://docs.oracle.com/javase/6/docs/api/java/lang/management/ClassLoadingMXBean.html#getLoadedClassCount()))\n  * compile-time - time spent in compilation, milliseconds ([used method](http://docs.oracle.com/javase/6/docs/api/java/lang/management/CompilationMXBean.html#getTotalCompilationTime()))\n\nExamples:\n\n```\ngc-time - monitor GC time at localhost:4711\nmemory-usage:url=somehost.com\\:4715 - use alternative hostname/password\nclass-count:url=somehost.com\\:4715:user=apc:password=SecurityPlease123 - some secure setup access\n```\n\n## TCP Metrics \nTCP metrics represents TCP socket state statistics (like open ports).\nPrimary\n  * *estab* - established connections\n  * time_wait\n  * close_wait\n\nAdditional\n  * bound\n  * close\n  * closing\n  * fin_wait1\n  * fin_wait2\n  * idle\n  * inbound\n  * last_ack\n  * listen\n  * outbound\n  * syn_recv \n\n## Swap Metrics \n  * *used*\n  * pagein\n  * pageout\n  * free\n  * total \n\n## Custom Metrics \nIf you haven't found appropriate metric in above lists,\nyou can set up collecting any value with custom metrics. \n\nSecurity note: Both `exec` and `tail` metric types can be turned off by providing `--no-exec` flag to\nserver agent. This enables more secure service with only strict KPI fetching.\n\n### EXEC \nThis metric type interprets parameter string as path to process to start and\narguments to pass to the process. Parameters separated with colon (not space), \nsee examples below. The process must print out to standard output single line\ncontaining single numeric metric value.\n\nIn most cases you'll need to start system interpreter (cmd.exe, /bin/sh)\nto run complex sequences of parameterized calls.\n\nExample1: Monitoring Linux _cached_ memory size (unavailable via SIGAR lib in default metrics), \nused _free_ utility output:\n\n```\n/bin/sh:-c:free | grep Mem | awk '{print $7}'\n```\n\nExample2: Monitoring MySQL _select_ query count:\n\n```\n/bin/sh:-c:echo \"show global status like 'Com_select'\" | mysql -u root | awk ' $1 ==\"Com_select\" {print $2}'\n```\n\n### TAIL \nAnother way to collect cutom metrics is to read lines off the end of the file.\nMetric parameter for tail type is path to file to read. Lines added to file must \ncontain single numeric metric. Example: \n\n```\n123\n342\n333\n297\n```\n","funding_links":[],"categories":["指标库"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fundera%2Fperfmon-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fundera%2Fperfmon-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fundera%2Fperfmon-agent/lists"}