<commit_before># Stream-JMX
A Lightweight framework to stream and monitor JMX metrics.
(Formerly known as PingJMX)

Stream JMX metrics to:
* Central monitoring server
* File, socket, log4j
* User defined destination

These metrics can be used to monitor health, performance and availability of your JVMs and applications.
Use Stream-JMX to embed a monitoring agent within your application and monitor memory, GC activity, CPU as
well as user defined MBeans.

Here is what you can do with Stream-JMX:
* Periodic JVM heartbeat
* Monitor memory utilization, GC activity, memory leaks
* High/Low, normal vs. abnormal CPU usage
* Monitor threading, runtime and other JVM performance metrics
* Monitor standard and custom MBean attributes
* Conditional actions based on MBean attribute values
* Conditional streaming based on custom filters
* Application state dumps on VM shut-down for diagnostics

# Why Stream-JMX
Stream-JMX provides and easy, lightweight and secure way to stream and monitor JMX metrics from within
java runtime containers.

* Stream JMX metrics out of the JVM container (vs. polling from outside/remote)
* Makes it easy to monitor farms of JVMs, application servers
* Reduce cyber security risk: No need to enable remote JMX, SSL, security, ports, firewalls
* Integration with monitoring tools for alerting, pro-active monitoring (AutoPilot M6)
* Integration with cloud analytics tools (https://www.jkoolcloud.com via JESL)
* Integration with log4j, slf4j, jkoolcloud (via TNT4J event sinks)
* Embedded application state dump framework for diagnostics
* Easily build your own extensions, monitors

**NOTE:** JESL provides a way to stream events generated by Stream-JMX to jKool Cloud.
For more information on JESL visit: [JESL project on Github](https://nastel.github.io/JESL).

# Using Stream-JMX
It is simple, do one of the following:
 * run Stream-JMX as a `-javaagent`
 * attach Stream-JMX as agent to running JVM
 * connect Stream-JMX over JMXConnector to locally running JVM or remote JMX service
 * embed Stream-JMX code into your application

**NOTE:** Running Stream-JMX as `-javaagent`, attaching agent to running JVM or connecting over JMXConnector to locally running JVM or 
remote JMX service over RMI connection can be invoked without changing your application code.

**NOTE:** When you want to sample JMX inter-process communication way (providing `-connect` or `-attach` mode `-vm` parameter value as 
PID/process name), then `Stream-JMX` and sampled process **MUST be** running JVM built by same provider (e.g. `IBM`, `Oracle`, `OpenJDK`) 
and same architecture (`x86`, `x64`). If JVM provider or architecture differs, then only way to collect JMX samples is using `-connect` mode 
defining `JMXConnector` (over `RMI`) URL.

## Running Stream-JMX as `-javaagent`

### Command line to run

Executable OS shell run script files `bin/stream-jmx.bat` or `bin/stream-jmx.sh` are dedicated to do the job.

Command line to run `stream-jmx` as JVM agent looks like this:
```cmd
java -javaagent:tnt4j-stream-jmx.jar="*:*!30000" -Dtnt4j.config=tnt4j.properties -classpath "tnt4j-stream-jmx.jar;lib/*" your.class.name your-args
```
The options are `-javaagent:tnt4j-stream-jmx.jar="mbean-filter!sample-time-ms"`, classpath must include tnt4j-stream-jmx jar files as well 
as locations of log4j and tnt4j configuration files.

## Attaching Stream-JMX to running JVM

### Command line to run

Executable OS shell run script files `bin/stream-jmx-attach.bat` or `bin/stream-jmx-attach.sh` are dedicated to do the job.

Command line to attach local JVM process JMX looks like this:
```cmd
java -Dtnt4j.config=.\config\tnt4j.properties -Dcom.jkoolcloud.tnt4j.stream.jmx.agent.trace=true -classpath "tnt4j-stream-jmx.jar;lib/*" com.jkoolcloud.tnt4j.stream.jmx.SamplingAgent -attach -vm:activemq -ap:tnt4j-stream-jmx-0.5.0.jar -ao:*:*!10000
```
System properties `-Dxxxxx` defines Stream-JMX configuration. For details see [Stream-JMX configuration ](#stream-jmx-configuration).

`SamplingAgent` arguments `-attach -vm:activemq -ap:tnt4j-stream-jmx-0.5.0.jar -ao:*:*!10000` states:
* `-attach` - defines that `SamplingAgent` shall be attached to running JVM process
* `-vm:activemq` - is JVM descriptor. In this case it is running JVM name fragment `activemq`. But it also may be JVM process identifier - 
PID. Mandatory argument.
* `-ap:tnt4j-stream-jmx-0.5.0.jar` - is agent library name. If it is class path - then only name should be sufficient. In any other case 
define full or relative path, e.g., `..\build\tnt4j-stream-jmx\tnt4j-stream-jmx-0.5.0\lib\tnt4j-stream-jmx-0.5.0.jar`. Mandatory argument.
* `-ao:*:*!10000` - is JMX sampler options stating to include all MBeans and schedule sampling every 10 seconds. Sampler options are 
optional - default value is `*:*!30000`. Initial sampler delay can be configured by adding numeric parameter `*:*!30000!1000` defining 
initial sampler delay as 1 second. Default sampler delay value is equal to sampling period value.
* `-slp:` - any JMX sampler configuration property. See [Program arguments used](#program-arguments-used) for details.

**NOTE:** arguments and properties defined running `SamplingAgent.main` is forwarded to `SamplingAgent` agent attached to JVM process.

### Coding into API
You can attach `SamplingAgent` to JVM from your custom API by calling [SamplingAgent.attach(String,String,String)](./tnt4j-stream-jmx-core/src/main/java/com/jkoolcloud/tnt4j/stream/jmx/SamplingAgent.java#L520) method. 

Sample `attach` call:
```java
try {
  SamplingAgent.attach("activemq", "tnt4j-stream-jmx-0.5.0.jar", "*:*!10000");
} catch (Exception exc) {
  exc.printStackTrace();
}
```

## Connecting Stream-JMX to local or remote JMX service

### Command line to run

Executable OS shell run script files `bin/stream-jmx-conenct.bat` or `bin/stream-jmx-conenct.sh` are dedicated to do the job:

* Windows
```cmd
rem using URL  
/bin/stream-jmx-connect.bat service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi
rem using URL with connection parameters  
/bin/stream-jmx-connect.bat service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi -ul:admin -up:admin -cp:java.naming.security.authentication=simple -cp:java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
rem using process name part        
/bin/stream-jmx-connect.bat activemq
rem using pid
/bin/stream-jmx-connect.bat 1553 
```

* *nix
```bash
# using URL  
./bin/stream-jmx-connect.sh service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi
# using URL with connection parameters  
/bin/stream-jmx-connect.sh service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi -ul:admin -up:admin -cp:java.naming.security.authentication=simple -cp:java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
# using process name part        
/bin/stream-jmx-connect.sh activemq
# using pid
/bin/stream-jmx-connect.sh 1553
```

#### To connect to local JVM process<commit_msg>README.md update.<commit_after># Stream-JMX
A Lightweight framework to stream and monitor JMX metrics.
(Formerly known as PingJMX)

Stream JMX metrics to:
* Central monitoring server
* File, socket, log4j
* User defined destination

These metrics can be used to monitor health, performance and availability of your JVMs and applications.
Use Stream-JMX to embed a monitoring agent within your application and monitor memory, GC activity, CPU as
well as user defined MBeans.

Here is what you can do with Stream-JMX:
* Periodic JVM heartbeat
* Monitor memory utilization, GC activity, memory leaks
* High/Low, normal vs. abnormal CPU usage
* Monitor threading, runtime and other JVM performance metrics
* Monitor standard and custom MBean attributes
* Conditional actions based on MBean attribute values
* Conditional streaming based on custom filters
* Application state dumps on VM shut-down for diagnostics

# Why Stream-JMX
Stream-JMX provides and easy, lightweight and secure way to stream and monitor JMX metrics from within
java runtime containers.

* Stream JMX metrics out of the JVM container (vs. polling from outside/remote)
* Makes it easy to monitor farms of JVMs, application servers
* Reduce cyber security risk: No need to enable remote JMX, SSL, security, ports, firewalls
* Integration with monitoring tools for alerting, pro-active monitoring (AutoPilot M6)
* Integration with cloud analytics tools (https://www.jkoolcloud.com via JESL)
* Integration with log4j, slf4j, jkoolcloud (via TNT4J event sinks)
* Embedded application state dump framework for diagnostics
* Easily build your own extensions, monitors

**NOTE:** JESL provides a way to stream events generated by Stream-JMX to jKool Cloud.
For more information on JESL visit: [JESL project on Github](https://nastel.github.io/JESL).

# Using Stream-JMX
It is simple, do one of the following:
 * run Stream-JMX as a `-javaagent`
 * attach Stream-JMX as agent to running JVM
 * connect Stream-JMX over JMXConnector to locally running JVM or remote JMX service
 * embed Stream-JMX code into your application

**NOTE:** Running Stream-JMX as `-javaagent`, attaching agent to running JVM or connecting over JMXConnector to locally running JVM or 
remote JMX service over RMI connection can be invoked without changing your application code.

**NOTE:** When you want to sample JMX inter-process communication way (providing `-connect` or `-attach` mode `-vm` parameter value as 
PID/process name), then `Stream-JMX` and sampled process **MUST be** running JVM built by same provider (e.g. `IBM`, `Oracle`, `OpenJDK`) 
and same architecture (`x86`, `x64`). If JVM provider or architecture differs, then only way to collect JMX samples is using `-connect` mode 
defining `JMXConnector` (over `RMI`) URL.

## Running Stream-JMX as `-javaagent`

### Command line to run

Executable OS shell run script files `bin/stream-jmx.bat` or `bin/stream-jmx.sh` are dedicated to do the job.

Command line to run `stream-jmx` as JVM agent looks like this:
```cmd
java -javaagent:tnt4j-stream-jmx.jar="*:*!30000" -Dtnt4j.config=tnt4j.properties -classpath "tnt4j-stream-jmx.jar;lib/*" your.class.name your-args
```
The options are `-javaagent:tnt4j-stream-jmx.jar="mbean-filter!sample-time-ms"`, classpath must include tnt4j-stream-jmx jar files as well 
as locations of log4j and tnt4j configuration files.

## Attaching Stream-JMX to running JVM

### Command line to run

Executable OS shell run script files `bin/stream-jmx-attach.bat` or `bin/stream-jmx-attach.sh` are dedicated to do the job.

Command line to attach local JVM process JMX looks like this:
```cmd
java -Dtnt4j.config=.\config\tnt4j.properties -Dcom.jkoolcloud.tnt4j.stream.jmx.agent.trace=true -classpath "tnt4j-stream-jmx.jar;lib/*" com.jkoolcloud.tnt4j.stream.jmx.SamplingAgent -attach -vm:activemq -ap:tnt4j-stream-jmx-0.5.0.jar -ao:*:*!10000
```
System properties `-Dxxxxx` defines Stream-JMX configuration. For details see [Stream-JMX configuration ](#stream-jmx-configuration).

`SamplingAgent` arguments `-attach -vm:activemq -ap:tnt4j-stream-jmx-0.5.0.jar -ao:*:*!10000` states:
* `-attach` - defines that `SamplingAgent` shall be attached to running JVM process
* `-vm:activemq` - is JVM descriptor. In this case it is running JVM name fragment `activemq`. But it also may be JVM process identifier - 
PID. Mandatory argument.
* `-ap:tnt4j-stream-jmx-0.5.0.jar` - is agent library name. If it is class path - then only name should be sufficient. In any other case 
define full or relative path, e.g., `..\build\tnt4j-stream-jmx\tnt4j-stream-jmx-0.5.0\lib\tnt4j-stream-jmx-0.5.0.jar`. Mandatory argument.
* `-ao:*:*!10000` - is JMX sampler options stating to include all MBeans and schedule sampling every 10 seconds. Sampler options are 
optional - default value is `*:*!30000`. Initial sampler delay can be configured by adding numeric parameter `*:*!30000!1000` defining 
initial sampler delay as 1 second. Default sampler delay value is equal to sampling period value.
* `-slp:` - any JMX sampler configuration property. See [Program arguments used](#program-arguments-used) for details.

**NOTE:** arguments and properties defined running `SamplingAgent.main` is forwarded to `SamplingAgent` agent attached to JVM process.

### Coding into API
You can attach `SamplingAgent` to JVM from your custom API by calling [SamplingAgent.attach(String,String,String)](./tnt4j-stream-jmx-core/src/main/java/com/jkoolcloud/tnt4j/stream/jmx/SamplingAgent.java#L520) method. 

Sample `attach` call:
```java
try {
  SamplingAgent.attach("activemq", "tnt4j-stream-jmx-0.5.0.jar", "*:*!10000");
} catch (Exception exc) {
  exc.printStackTrace();
}
```

## Connecting Stream-JMX to local or remote JMX service

### Command line to run

Executable OS shell run script files `bin/stream-jmx-conenct.bat` or `bin/stream-jmx-conenct.sh` are dedicated to do the job:

* Windows
```cmd
rem using URL  
/bin/stream-jmx-connect.bat service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi
rem using URL with connection parameters  
/bin/stream-jmx-connect.bat service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi -ul:admin -up:admin -cp:java.naming.security.authentication=simple -cp:java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
rem using process name part        
/bin/stream-jmx-connect.bat activemq
rem using pid
/bin/stream-jmx-connect.bat 1553 
```

* *nix
```bash
# using URL  
./bin/stream-jmx-connect.sh service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi
# using URL with connection parameters  
./bin/stream-jmx-connect.sh service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi -ul:admin -up:admin -cp:java.naming.security.authentication=simple -cp:java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
# using process name part        
./bin/stream-jmx-connect.sh activemq
# using pid
./bin/stream-jmx-connect.sh 1553
```

#### To connect to local JVM process
{'fraction_non_alphanumeric': 0.10508376241931974, 'fraction_numerical': 0.017115091739792587, 'mean_word_length': 4.553765606121627, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6086321', 'n_tokens_mistral': 4513, 'n_tokens_neox': 4332, 'n_words': 1552}