Add ibm-mq-metrics

.github/component_owners.yml

@@ -90,3 +90,6 @@ components:
   opamp-client:
     - LikeTheSalad
     - jackshirazi
+  ibm-mq-metrics:
+    - breedx-splk
+    - atoulme

README.md

@@ -26,6 +26,7 @@ feature or via instrumentation, this project is hopefully for you.
 | alpha   | [GCP Authentication Extension](./gcp-auth-extension/README.md)    |
 | beta    | [GCP Resources](./gcp-resources/README.md)                        |
 | beta    | [Inferred Spans](./inferred-spans/README.md)                      |
+| alpha   | [IBM MQ Metrics](./ibm-mq-metrics/README.md)                      |
 | alpha   | [JFR Connection](./jfr-connection/README.md)                      |
 | alpha   | [JFR Events](./jfr-events/README.md)                              |
 | alpha   | [JMX Metric Gatherer](./jmx-metrics/README.md)                    |

ibm-mq-metrics/Makefile

@@ -0,0 +1,84 @@
+# From where to resolve the containers (e.g. "otel/weaver").
+WEAVER_CONTAINER_REPOSITORY=docker.io
+# Versioned, non-qualified references to containers used in this Makefile.
+# These are parsed from dependencies.Dockerfile so dependabot will autoupdate
+# the versions of docker files we use.
+VERSIONED_WEAVER_CONTAINER_NO_REPO=$(shell cat weaver.Dockerfile | awk '$$4=="weaver" {print $$2}')
+# Versioned, non-qualified references to containers used in this Makefile.
+WEAVER_CONTAINER=$(WEAVER_CONTAINER_REPOSITORY)/$(VERSIONED_WEAVER_CONTAINER_NO_REPO)
+
+# Next - we want to run docker as our local file user, so generated code is not
+# owned by root, and we don't give unnecessary access.
+#
+# Determine if "docker" is actually podman
+DOCKER_VERSION_OUTPUT := $(shell docker --version 2>&1)
+DOCKER_IS_PODMAN := $(shell echo $(DOCKER_VERSION_OUTPUT) | grep -c podman)
+ifeq ($(DOCKER_IS_PODMAN),0)
+    DOCKER_COMMAND := docker
+else
+    DOCKER_COMMAND := podman
+endif
+DOCKER_RUN=$(DOCKER_COMMAND) run
+DOCKER_USER=$(shell id -u):$(shell id -g)
+DOCKER_USER_IS_HOST_USER_ARG=-u $(DOCKER_USER)
+ifeq ($(DOCKER_COMMAND),podman)
+ # On podman, additional arguments are needed to make "-u" work
+ # correctly with the host user ID and host group ID.
+ #
+ #      Error: OCI runtime error: crun: setgroups: Invalid argument
+ DOCKER_USER_IS_HOST_USER_ARG=--userns=keep-id -u $(DOCKER_USER)
+endif
+
+.PHONY: generate-docs
+generate-docs:
+	mkdir -p docs
+	$(DOCKER_RUN) --rm \
+		$(DOCKER_USER_IS_HOST_USER_ARG) \
+		--mount 'type=bind,source=$(PWD)/model,target=/home/weaver/model,readonly' \
+		--mount 'type=bind,source=$(PWD)/templates,target=/home/weaver/templates,readonly' \
+		--mount 'type=bind,source=$(PWD)/docs,target=/home/weaver/target' \
+		${WEAVER_CONTAINER} registry generate \
+		--registry=/home/weaver/model \
+		markdown \
+		--future \
+		/home/weaver/target
+
+.PHONY: check
+check:
+	$(DOCKER_RUN) --rm \
+		$(DOCKER_USER_IS_HOST_USER_ARG) \
+		--mount 'type=bind,source=$(PWD)/model,target=/home/weaver/model,readonly' \
+		--mount 'type=bind,source=$(PWD)/templates,target=/home/weaver/templates,readonly' \
+		--mount 'type=bind,source=$(PWD)/docs,target=/home/weaver/target' \
+		${WEAVER_CONTAINER} registry check \
+		--registry=/home/weaver/model
+
+.PHONY: generate-java
+generate-java:
+	mkdir -p src/main/java/io/opentelemetry/ibm/mq/metrics
+	$(DOCKER_RUN) --rm \
+		$(DOCKER_USER_IS_HOST_USER_ARG) \
+		--mount 'type=bind,source=$(PWD)/model,target=/home/weaver/model,readonly' \
+		--mount 'type=bind,source=$(PWD)/templates,target=/home/weaver/templates,readonly' \
+		--mount 'type=bind,source=$(PWD)/src/main/java/io/opentelemetry/ibm/mq/metrics,target=/home/weaver/target' \
+		${WEAVER_CONTAINER} registry generate \
+		--registry=/home/weaver/model \
+		java \
+		--future \
+		/home/weaver/target
+
+.PHONY: generate-yaml
+generate-yaml:
+	$(DOCKER_RUN) --rm \
+		$(DOCKER_USER_IS_HOST_USER_ARG) \
+		--mount 'type=bind,source=$(PWD)/model,target=/home/weaver/model,readonly' \
+		--mount 'type=bind,source=$(PWD)/templates,target=/home/weaver/templates,readonly' \
+		--mount 'type=bind,source=$(PWD)/,target=/home/weaver/target' \
+		${WEAVER_CONTAINER} registry generate \
+		--registry=/home/weaver/model \
+		yaml \
+		--future \
+		/home/weaver/target
+
+.PHONY: generate
+generate: generate-docs generate-yaml generate-java

ibm-mq-metrics/README.md

@@ -0,0 +1,228 @@
+# IBM MQ Metrics
+
+:warning: This software is under development.
+
+## Use case
+
+IBM MQ, formerly known as WebSphere MQ (message queue) series, is an IBM software for
+program-to-program messaging across multiple platforms.
+
+The IBM MQ metrics utility here can monitor multiple queues managers and their resources,
+namely queues, topics, channels and listeners The metrics are extracted out using the
+[PCF command messages](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_8.0.0/com.ibm.mq.adm.doc/q020010_.htm).
+
+The metrics for queue manager, queue, topic, channel and listener can be configured.
+
+The MQ Monitor is compatible with IBM MQ version 7.x, 8.x and 9.x.
+
+## Prerequisites
+
+This software requires compilation with Java 11.
+It targets language level 8 and outputs java 8 class files.
+
+The extension has a dependency on the following jar's depending on IBM MQ version:
+
+* v8.0.0 and above
+
+```
+com.ibm.mq.allclient.jar
+```
+
+* For other versions
+
+```
+com.ibm.mq.commonservices.jar
+com.ibm.mq.jar
+com.ibm.mq.jmqi.jar
+com.ibm.mq.headers.jar
+com.ibm.mq.pcf.jar
+dhbcore.jar
+connector.jar
+```
+
+These jar files are typically found in ```/opt/mqm/java/lib``` on a UNIX server but may be
+found in an alternate location depending upon your environment.
+
+In case of **CLIENT** transport type, IBM MQ Client must be installed to get the MQ jars.
+[The IBM MQ Client jars can be downloaded here](https://developer.ibm.com/messaging/mq-downloads/).
+
+### MQ monitoring configuration
+
+This software reads events from event queues associated with the queue manager:
+
+* `SYSTEM.ADMIN.PERFM.EVENT`: Performance events, such as low, high, and full queue depth events.
+* `SYSTEM.ADMIN.QMGR.EVENT`: Authority events
+* `SYSTEM.ADMIN.CONFIG.EVENT`: Configuration events
+
+Please turn on those events to take advantage of this monitoring.
+
+## Build
+
+Build the package with:
+
+```shell
+cd ibm-mq-metrics
+../gradlew shadowJar
+```
+
+Note: Due to restrictive licensing, this uber-jar (fat-jar) does not include the IBM client jar.
+
+## Run
+
+Run the standalone jar alongside the IBM jar:
+
+```shell
+cd ibm-mq-metrics
+java \
+   -Djavax.net.ssl.keyStore=key.jks \
+   -Djavax.net.ssl.keyStorePassword=<password> \
+   -Djavax.net.ssl.trustStore=key.jks \
+   -Djavax.net.ssl.trustStorePassword=<password> \
+   -cp build/libs/opentelemetry-ibm-mq-monitoring-<version>-all.jar:lib/com.ibm.mq.allclient.jar \
+   io.opentelemetry.ibm.mq.opentelemetry.Main \
+   ./my-config.yml
+```
+
+## Connection
+
+There are two transport modes in which this extension can be run:
+
+* **Binding** : Requires WMQ Extension to be deployed in machine agent on the same machine where
+  WMQ server is installed.
+* **Client** : In this mode, the WMQ extension is installed on a different host than the IBM MQ
+  server. Please install the [IBM MQ Client](https://developer.ibm.com/messaging/mq-downloads/)
+  for this mode to get the necessary jars as mentioned previously.
+
+If this extension is configured for **CLIENT** transport type
+
+1. Please make sure the MQ's host and port is accessible.
+2. Credentials of user with correct access rights would be needed in config.yml.
+3. If the hosting OS for IBM MQ is Windows, Windows user credentials will be needed.
+
+If you are in **Bindings** mode, please make sure to start the MA process under a user which has
+the following permissions on the broker. Similarly, for **Client** mode, please provide the user
+credentials in config.yml which have permissions listed below.
+
+The user connecting to the queueManager should have the inquire, get, put (since PCF responses
+cause dynamic queues to be created) permissions. For metrics that execute MQCMD_RESET_Q_STATS
+command, chg permission is needed.
+
+### SSL Support
+
+_Note: The following is only needed for versions of Java 8 before 8u161._
+
+1. Configure the IBM SSL Cipher Suite in the config.yml.
+   Note that, to use some CipherSuites the unrestricted policy needs to be configured in JRE.
+   Please visit [this link](http://www.ibm.com/support/knowledgecenter/SSYKE2_8.0.0/com.ibm.java.security.component.80.doc/security-component/sdkpolicyfiles.html)
+   for more details. For Oracle JRE, please update with [JCE Unlimited Strength Jurisdiction Policy](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html).
+   The download includes a readme file with instructions on how to apply these files to JRE.
+
+2. Please add the following JVM arguments to the MA start up command or script.
+
+   ```-Dcom.ibm.mq.cfg.useIBMCipherMappings=false```  (If you are using IBM Cipher Suites, set the
+   flag to true. Please visit [this link](http://www.ibm.com/support/knowledgecenter/SSFKSJ_8.0.0/com.ibm.mq.dev.doc/q113210_.htm) for more details.
+   )
+3. To configure SSL, the MA's trust store and keystore needs to be setup with the JKS filepath.
+   They can be passed either as Machine Agent JVM arguments or configured in config.yml (sslConnection) <br />
+
+   a. Machine Agent JVM arguments as follows:
+
+   ```-Djavax.net.ssl.trustStore=<PATH_TO_JKS_FILE>```<br />
+   ```-Djavax.net.ssl.trustStorePassword=<PASS>```<br />
+   ```-Djavax.net.ssl.keyStore=<PATH_TO_JKS_FILE>```<br />
+   ```-Djavax.net.ssl.keyStorePassword=<PASS>```<br />
+
+   b. sslConnection in config.yml, configure the trustStorePassword. Same holds for keyStore configuration as well.
+
+    ```
+    sslConnection:
+      trustStorePath: ""
+      trustStorePassword: ""
+
+      keyStorePath: ""
+      keyStorePassword: ""
+    ```
+
+## Configuration
+
+**Note** : Please make sure to not use tab (\t) while editing yaml files. You may want to validate
+the yaml file using a [yaml validator](https://jsonformatter.org/yaml-validator). Configure the monitor by copying and editing the
+config.yml file in <code>src/main/resources/config.yml</code>.
+
+1. Configure the queueManagers with appropriate fields and filters. You can configure multiple
+   queue managers in one configuration file.
+2. To run the extension at a frequency > 1 minute, please configure the taskSchedule section.
+   Refer to the [Task Schedule](https://community.appdynamics.com/t5/Knowledge-Base/Task-Schedule-for-Extensions/ta-p/35414) doc for details.
+
+### Monitoring Workings - Internals
+
+This software extracts metrics through [PCF framework](https://www.ibm.com/support/knowledgecenter/SSFKSJ_8.0.0/com.ibm.mq.adm.doc/q019990_.htm).
+[A complete list of PCF commands are listed here](https://www.ibm.com/support/knowledgecenter/SSFKSJ_7.5.0/com.ibm.mq.ref.adm.doc/q086870_.htm).
+Each queue manager has an administration queue with a standard queue name and
+the extension sends PCF command messages to that queue. On Windows and Unix platforms, the PCF
+commands are sent is always sent to the SYSTEM.ADMIN.COMMAND.QUEUE queue.
+[More details mentioned here](https://www.ibm.com/support/knowledgecenter/SSFKSJ_8.0.0/com.ibm.mq.adm.doc/q020010_.htm)
+
+By default, the PCF responses are sent to the SYSTEM.DEFAULT.MODEL.QUEUE. Using this queue causes
+a temporary dynamic queue to be created. You can override the default here by using the
+`modelQueueName` and `replyQueuePrefix` fields in the config.yml.
+[More details mentioned here](https://www.ibm.com/support/knowledgecenter/SSFKSJ_7.5.0/com.ibm.mq.ref.adm.doc/q083240_.htm)
+
+## Metrics
+
+See [docs/metrics.md](docs/metrics.md).
+
+## Troubleshooting
+
+1. Error `Completion Code '2', Reason '2495'`
+   Normally this error occurs if the environment variables are not set up correctly for this extension to work MQ in Bindings Mode.
+
+   If you are seeing `Failed to load the WebSphere MQ native JNI library: 'mqjbnd'`, please add the following jvm argument when starting the MA.
+
+   -Djava.library.path=\<path to libmqjbnd.so\> For eg. on Unix it could -Djava.library.path=/opt/mqm/java/lib64 for 64-bit or -Djava.library.path=/opt/mqm/java/lib for 32-bit OS
+
+   Sometimes you also have run the setmqenv script before using the above jvm argument to start the machine agent.
+
+   . /opt/mqm/bin/setmqenv -s
+
+   For more details, please check this [doc](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_7.1.0/com.ibm.mq.doc/zr00610_.htm)
+
+   This might occur due to various reasons ranging from incorrect installation to applying
+   IBM Fix Packs, but most of the time it happens when you are trying to connect in `Bindings`
+   mode and machine agent is not on the same machine on which WMQ server is running. If you want
+   to connect to WMQ server from a remote machine then connect using `Client` mode.
+
+   Another way to get around this issue is to avoid using the Bindings mode. Connect using CLIENT
+   transport type from a remote box.
+
+2. Error `Completion Code '2', Reason '2035'`
+   This could happen for various reasons but for most of the cases, for **Client** mode the
+   user specified in config.yml is not authorized to access the queue manager. Also sometimes
+   even if userid and password are correct, channel auth (CHLAUTH) for that queue manager blocks
+   traffics from other ips, you need to contact admin to provide you access to the queue manager.
+   For Bindings mode, please make sure that the MA is owned by a mqm user.
+
+3. `MQJE001: Completion Code '2', Reason '2195'`
+   This could happen in **Client** mode. Please make sure that the IBM MQ dependency jars are correctly referenced in classpath of monitor.xml
+
+4. `MQJE001: Completion Code '2', Reason '2400'`
+   This could happen if unsupported cipherSuite is provided or JRE not having/enabled unlimited jurisdiction policy files. Please check SSL Support section.
+
+5. If you are seeing `NoClassDefFoundError` or `ClassNotFoundException` error for any of the MQ dependency even after providing correct path in monitor.xml, then you can also try copying all the required jars in WMQMonitor (MAHome/monitors/WMQMonitor) folder and provide classpath in monitor.xml like below
+
+   ```
+    <classpath>opentelemetry-ibm-mq-monitoring-<version>-all.jar;com.ibm.mq.allclient.jar</classpath>
+   ```
+
+   OR
+
+   ```
+    <classpath>opentelemetry-ibm-mq-monitoring-<version>-all.jar;com.ibm.mq.jar;com.ibm.mq.jmqi.jar;com.ibm.mq.commonservices.jar;com.ibm.mq.headers.jar;com.ibm.mq.pcf.jar;connector.jar;dhbcore.jar</classpath>
+   ```
+
+## Component Owners
+
+- [Antoine Toulme Sharma](https://github.com/atoulme), Splunk
+- [Jason Plumb](https://github.com/breedx-splk), Splunk
+
+Learn more about component owners in [component_owners.yml](../.github/component_owners.yml).