Skip to content

Commit 567e54e

Browse files
breedx-splkotelbot[bot]renovate[bot]trasklaurit
authored
Add ibm-mq-metrics (#1960)
Co-authored-by: otelbot <[email protected]> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: Trask Stalnaker <[email protected]> Co-authored-by: Lauri Tulmin <[email protected]>
1 parent 40ca061 commit 567e54e

File tree

80 files changed

+8542
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

80 files changed

+8542
-0
lines changed

‎.github/component_owners.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,3 +90,6 @@ components:
9090
opamp-client:
9191
- LikeTheSalad
9292
- jackshirazi
93+
ibm-mq-metrics:
94+
- breedx-splk
95+
- atoulme

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ feature or via instrumentation, this project is hopefully for you.
2626
| alpha | [GCP Authentication Extension](./gcp-auth-extension/README.md) |
2727
| beta | [GCP Resources](./gcp-resources/README.md) |
2828
| beta | [Inferred Spans](./inferred-spans/README.md) |
29+
| alpha | [IBM MQ Metrics](./ibm-mq-metrics/README.md) |
2930
| alpha | [JFR Connection](./jfr-connection/README.md) |
3031
| alpha | [JFR Events](./jfr-events/README.md) |
3132
| alpha | [JMX Metric Gatherer](./jmx-metrics/README.md) |

‎ibm-mq-metrics/Makefile

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# From where to resolve the containers (e.g. "otel/weaver").
2+
WEAVER_CONTAINER_REPOSITORY=docker.io
3+
# Versioned, non-qualified references to containers used in this Makefile.
4+
# These are parsed from dependencies.Dockerfile so dependabot will autoupdate
5+
# the versions of docker files we use.
6+
VERSIONED_WEAVER_CONTAINER_NO_REPO=$(shell cat weaver.Dockerfile | awk '$$4=="weaver" {print $$2}')
7+
# Versioned, non-qualified references to containers used in this Makefile.
8+
WEAVER_CONTAINER=$(WEAVER_CONTAINER_REPOSITORY)/$(VERSIONED_WEAVER_CONTAINER_NO_REPO)
9+
10+
# Next - we want to run docker as our local file user, so generated code is not
11+
# owned by root, and we don't give unnecessary access.
12+
#
13+
# Determine if "docker" is actually podman
14+
DOCKER_VERSION_OUTPUT := $(shell docker --version 2>&1)
15+
DOCKER_IS_PODMAN := $(shell echo $(DOCKER_VERSION_OUTPUT) | grep -c podman)
16+
ifeq ($(DOCKER_IS_PODMAN),0)
17+
DOCKER_COMMAND := docker
18+
else
19+
DOCKER_COMMAND := podman
20+
endif
21+
DOCKER_RUN=$(DOCKER_COMMAND) run
22+
DOCKER_USER=$(shell id -u):$(shell id -g)
23+
DOCKER_USER_IS_HOST_USER_ARG=-u $(DOCKER_USER)
24+
ifeq ($(DOCKER_COMMAND),podman)
25+
# On podman, additional arguments are needed to make "-u" work
26+
# correctly with the host user ID and host group ID.
27+
#
28+
# Error: OCI runtime error: crun: setgroups: Invalid argument
29+
DOCKER_USER_IS_HOST_USER_ARG=--userns=keep-id -u $(DOCKER_USER)
30+
endif
31+
32+
.PHONY: generate-docs
33+
generate-docs:
34+
mkdir -p docs
35+
$(DOCKER_RUN) --rm \
36+
$(DOCKER_USER_IS_HOST_USER_ARG) \
37+
--mount 'type=bind,source=$(PWD)/model,target=/home/weaver/model,readonly' \
38+
--mount 'type=bind,source=$(PWD)/templates,target=/home/weaver/templates,readonly' \
39+
--mount 'type=bind,source=$(PWD)/docs,target=/home/weaver/target' \
40+
${WEAVER_CONTAINER} registry generate \
41+
--registry=/home/weaver/model \
42+
markdown \
43+
--future \
44+
/home/weaver/target
45+
46+
.PHONY: check
47+
check:
48+
$(DOCKER_RUN) --rm \
49+
$(DOCKER_USER_IS_HOST_USER_ARG) \
50+
--mount 'type=bind,source=$(PWD)/model,target=/home/weaver/model,readonly' \
51+
--mount 'type=bind,source=$(PWD)/templates,target=/home/weaver/templates,readonly' \
52+
--mount 'type=bind,source=$(PWD)/docs,target=/home/weaver/target' \
53+
${WEAVER_CONTAINER} registry check \
54+
--registry=/home/weaver/model
55+
56+
.PHONY: generate-java
57+
generate-java:
58+
mkdir -p src/main/java/io/opentelemetry/ibm/mq/metrics
59+
$(DOCKER_RUN) --rm \
60+
$(DOCKER_USER_IS_HOST_USER_ARG) \
61+
--mount 'type=bind,source=$(PWD)/model,target=/home/weaver/model,readonly' \
62+
--mount 'type=bind,source=$(PWD)/templates,target=/home/weaver/templates,readonly' \
63+
--mount 'type=bind,source=$(PWD)/src/main/java/io/opentelemetry/ibm/mq/metrics,target=/home/weaver/target' \
64+
${WEAVER_CONTAINER} registry generate \
65+
--registry=/home/weaver/model \
66+
java \
67+
--future \
68+
/home/weaver/target
69+
70+
.PHONY: generate-yaml
71+
generate-yaml:
72+
$(DOCKER_RUN) --rm \
73+
$(DOCKER_USER_IS_HOST_USER_ARG) \
74+
--mount 'type=bind,source=$(PWD)/model,target=/home/weaver/model,readonly' \
75+
--mount 'type=bind,source=$(PWD)/templates,target=/home/weaver/templates,readonly' \
76+
--mount 'type=bind,source=$(PWD)/,target=/home/weaver/target' \
77+
${WEAVER_CONTAINER} registry generate \
78+
--registry=/home/weaver/model \
79+
yaml \
80+
--future \
81+
/home/weaver/target
82+
83+
.PHONY: generate
84+
generate: generate-docs generate-yaml generate-java

‎ibm-mq-metrics/README.md

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
# IBM MQ Metrics
2+
3+
:warning: This software is under development.
4+
5+
## Use case
6+
7+
IBM MQ, formerly known as WebSphere MQ (message queue) series, is an IBM software for
8+
program-to-program messaging across multiple platforms.
9+
10+
The IBM MQ metrics utility here can monitor multiple queues managers and their resources,
11+
namely queues, topics, channels and listeners The metrics are extracted out using the
12+
[PCF command messages](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_8.0.0/com.ibm.mq.adm.doc/q020010_.htm).
13+
14+
The metrics for queue manager, queue, topic, channel and listener can be configured.
15+
16+
The MQ Monitor is compatible with IBM MQ version 7.x, 8.x and 9.x.
17+
18+
## Prerequisites
19+
20+
This software requires compilation with Java 11.
21+
It targets language level 8 and outputs java 8 class files.
22+
23+
The extension has a dependency on the following jar's depending on IBM MQ version:
24+
25+
* v8.0.0 and above
26+
27+
```
28+
com.ibm.mq.allclient.jar
29+
```
30+
31+
* For other versions
32+
33+
```
34+
com.ibm.mq.commonservices.jar
35+
com.ibm.mq.jar
36+
com.ibm.mq.jmqi.jar
37+
com.ibm.mq.headers.jar
38+
com.ibm.mq.pcf.jar
39+
dhbcore.jar
40+
connector.jar
41+
```
42+
43+
These jar files are typically found in ```/opt/mqm/java/lib``` on a UNIX server but may be
44+
found in an alternate location depending upon your environment.
45+
46+
In case of **CLIENT** transport type, IBM MQ Client must be installed to get the MQ jars.
47+
[The IBM MQ Client jars can be downloaded here](https://developer.ibm.com/messaging/mq-downloads/).
48+
49+
### MQ monitoring configuration
50+
51+
This software reads events from event queues associated with the queue manager:
52+
53+
* `SYSTEM.ADMIN.PERFM.EVENT`: Performance events, such as low, high, and full queue depth events.
54+
* `SYSTEM.ADMIN.QMGR.EVENT`: Authority events
55+
* `SYSTEM.ADMIN.CONFIG.EVENT`: Configuration events
56+
57+
Please turn on those events to take advantage of this monitoring.
58+
59+
## Build
60+
61+
Build the package with:
62+
63+
```shell
64+
cd ibm-mq-metrics
65+
../gradlew shadowJar
66+
```
67+
68+
Note: Due to restrictive licensing, this uber-jar (fat-jar) does not include the IBM client jar.
69+
70+
## Run
71+
72+
Run the standalone jar alongside the IBM jar:
73+
74+
```shell
75+
cd ibm-mq-metrics
76+
java \
77+
-Djavax.net.ssl.keyStore=key.jks \
78+
-Djavax.net.ssl.keyStorePassword=<password> \
79+
-Djavax.net.ssl.trustStore=key.jks \
80+
-Djavax.net.ssl.trustStorePassword=<password> \
81+
-cp build/libs/opentelemetry-ibm-mq-monitoring-<version>-all.jar:lib/com.ibm.mq.allclient.jar \
82+
io.opentelemetry.ibm.mq.opentelemetry.Main \
83+
./my-config.yml
84+
```
85+
86+
## Connection
87+
88+
There are two transport modes in which this extension can be run:
89+
90+
* **Binding** : Requires WMQ Extension to be deployed in machine agent on the same machine where
91+
WMQ server is installed.
92+
* **Client** : In this mode, the WMQ extension is installed on a different host than the IBM MQ
93+
server. Please install the [IBM MQ Client](https://developer.ibm.com/messaging/mq-downloads/)
94+
for this mode to get the necessary jars as mentioned previously.
95+
96+
If this extension is configured for **CLIENT** transport type
97+
98+
1. Please make sure the MQ's host and port is accessible.
99+
2. Credentials of user with correct access rights would be needed in config.yml.
100+
3. If the hosting OS for IBM MQ is Windows, Windows user credentials will be needed.
101+
102+
If you are in **Bindings** mode, please make sure to start the MA process under a user which has
103+
the following permissions on the broker. Similarly, for **Client** mode, please provide the user
104+
credentials in config.yml which have permissions listed below.
105+
106+
The user connecting to the queueManager should have the inquire, get, put (since PCF responses
107+
cause dynamic queues to be created) permissions. For metrics that execute MQCMD_RESET_Q_STATS
108+
command, chg permission is needed.
109+
110+
### SSL Support
111+
112+
_Note: The following is only needed for versions of Java 8 before 8u161._
113+
114+
1. Configure the IBM SSL Cipher Suite in the config.yml.
115+
Note that, to use some CipherSuites the unrestricted policy needs to be configured in JRE.
116+
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)
117+
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).
118+
The download includes a readme file with instructions on how to apply these files to JRE.
119+
120+
2. Please add the following JVM arguments to the MA start up command or script.
121+
122+
```-Dcom.ibm.mq.cfg.useIBMCipherMappings=false``` (If you are using IBM Cipher Suites, set the
123+
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.
124+
)
125+
3. To configure SSL, the MA's trust store and keystore needs to be setup with the JKS filepath.
126+
They can be passed either as Machine Agent JVM arguments or configured in config.yml (sslConnection) <br />
127+
128+
a. Machine Agent JVM arguments as follows:
129+
130+
```-Djavax.net.ssl.trustStore=<PATH_TO_JKS_FILE>```<br />
131+
```-Djavax.net.ssl.trustStorePassword=<PASS>```<br />
132+
```-Djavax.net.ssl.keyStore=<PATH_TO_JKS_FILE>```<br />
133+
```-Djavax.net.ssl.keyStorePassword=<PASS>```<br />
134+
135+
b. sslConnection in config.yml, configure the trustStorePassword. Same holds for keyStore configuration as well.
136+
137+
```
138+
sslConnection:
139+
trustStorePath: ""
140+
trustStorePassword: ""
141+
142+
keyStorePath: ""
143+
keyStorePassword: ""
144+
```
145+
146+
## Configuration
147+
148+
**Note** : Please make sure to not use tab (\t) while editing yaml files. You may want to validate
149+
the yaml file using a [yaml validator](https://jsonformatter.org/yaml-validator). Configure the monitor by copying and editing the
150+
config.yml file in <code>src/main/resources/config.yml</code>.
151+
152+
1. Configure the queueManagers with appropriate fields and filters. You can configure multiple
153+
queue managers in one configuration file.
154+
2. To run the extension at a frequency > 1 minute, please configure the taskSchedule section.
155+
Refer to the [Task Schedule](https://community.appdynamics.com/t5/Knowledge-Base/Task-Schedule-for-Extensions/ta-p/35414) doc for details.
156+
157+
### Monitoring Workings - Internals
158+
159+
This software extracts metrics through [PCF framework](https://www.ibm.com/support/knowledgecenter/SSFKSJ_8.0.0/com.ibm.mq.adm.doc/q019990_.htm).
160+
[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).
161+
Each queue manager has an administration queue with a standard queue name and
162+
the extension sends PCF command messages to that queue. On Windows and Unix platforms, the PCF
163+
commands are sent is always sent to the SYSTEM.ADMIN.COMMAND.QUEUE queue.
164+
[More details mentioned here](https://www.ibm.com/support/knowledgecenter/SSFKSJ_8.0.0/com.ibm.mq.adm.doc/q020010_.htm)
165+
166+
By default, the PCF responses are sent to the SYSTEM.DEFAULT.MODEL.QUEUE. Using this queue causes
167+
a temporary dynamic queue to be created. You can override the default here by using the
168+
`modelQueueName` and `replyQueuePrefix` fields in the config.yml.
169+
[More details mentioned here](https://www.ibm.com/support/knowledgecenter/SSFKSJ_7.5.0/com.ibm.mq.ref.adm.doc/q083240_.htm)
170+
171+
## Metrics
172+
173+
See [docs/metrics.md](docs/metrics.md).
174+
175+
## Troubleshooting
176+
177+
1. Error `Completion Code '2', Reason '2495'`
178+
Normally this error occurs if the environment variables are not set up correctly for this extension to work MQ in Bindings Mode.
179+
180+
If you are seeing `Failed to load the WebSphere MQ native JNI library: 'mqjbnd'`, please add the following jvm argument when starting the MA.
181+
182+
-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
183+
184+
Sometimes you also have run the setmqenv script before using the above jvm argument to start the machine agent.
185+
186+
. /opt/mqm/bin/setmqenv -s
187+
188+
For more details, please check this [doc](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_7.1.0/com.ibm.mq.doc/zr00610_.htm)
189+
190+
This might occur due to various reasons ranging from incorrect installation to applying
191+
IBM Fix Packs, but most of the time it happens when you are trying to connect in `Bindings`
192+
mode and machine agent is not on the same machine on which WMQ server is running. If you want
193+
to connect to WMQ server from a remote machine then connect using `Client` mode.
194+
195+
Another way to get around this issue is to avoid using the Bindings mode. Connect using CLIENT
196+
transport type from a remote box.
197+
198+
2. Error `Completion Code '2', Reason '2035'`
199+
This could happen for various reasons but for most of the cases, for **Client** mode the
200+
user specified in config.yml is not authorized to access the queue manager. Also sometimes
201+
even if userid and password are correct, channel auth (CHLAUTH) for that queue manager blocks
202+
traffics from other ips, you need to contact admin to provide you access to the queue manager.
203+
For Bindings mode, please make sure that the MA is owned by a mqm user.
204+
205+
3. `MQJE001: Completion Code '2', Reason '2195'`
206+
This could happen in **Client** mode. Please make sure that the IBM MQ dependency jars are correctly referenced in classpath of monitor.xml
207+
208+
4. `MQJE001: Completion Code '2', Reason '2400'`
209+
This could happen if unsupported cipherSuite is provided or JRE not having/enabled unlimited jurisdiction policy files. Please check SSL Support section.
210+
211+
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
212+
213+
```
214+
<classpath>opentelemetry-ibm-mq-monitoring-<version>-all.jar;com.ibm.mq.allclient.jar</classpath>
215+
```
216+
217+
OR
218+
219+
```
220+
<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>
221+
```
222+
223+
## Component Owners
224+
225+
- [Antoine Toulme Sharma](https://github.com/atoulme), Splunk
226+
- [Jason Plumb](https://github.com/breedx-splk), Splunk
227+
228+
Learn more about component owners in [component_owners.yml](../.github/component_owners.yml).

0 commit comments

Comments
 (0)