Merge pull request #127 from sdmarshall79/metrics-doc

Doc changes for metrics

README.md

@@ -26,6 +26,7 @@ Note that in order to use the image, it is necessary to accept the terms of the
 - **LANG** - Set this to the language you would like the license to be printed in.
 - **MQ_QMGR_NAME** - Set this to the name you want your Queue Manager to be created with.
 - **LOG_FORMAT** - Set this to change the format of the logs which are printed on the container's stdout.  Set to "json" to use JSON format (JSON object per line); set to "basic" to use a simple human-readable format.  Defaults to "basic".
+- **MQ_ENABLE_METRICS** - Set this to `true` to generate Prometheus metrics for your Queue Manager.
 
 See the [default developer configuration docs](docs/developer-config.md) for the extra environment variables supported by the MQ Advanced for Developers image.
 

docs/internals.md

@@ -24,6 +24,7 @@ The `runmqserver` command has the following responsibilities:
     - Works as PID 1, so is responsible for [reaping zombie processes](https://blog.phusion.nl/2015/01/20/docker-and-the-pid-1-zombie-reaping-problem/)
 * Creating and starting a queue manager
 * Configuring the queue manager, by running any MQSC scripts found under `/etc/mqm`
+* Starting Prometheus metrics generation for the queue manager (if enabled)
 * Indicates to the `chkmqready` command that configuration is complete, and that normal readiness checking can happen.  This is done by writing a file into `/run/runmqserver`
 
 In addition, for MQ Advanced for Developers only, the web server is started.
@@ -35,4 +36,17 @@ The `runmqdevserver` command is added to the MQ Advanced for Developers image on
 2. Generates MQSC files to put in `/etc/mqm`, based on a template, which is updated with values based on supplied environment variables.
 3. If requested, it creates TLS key stores under `/run/runmqdevserver`, and configures MQ and the web server to use them
 
-A special version of `runmqserver` is used in the developer image, which performs extra actions like starting the web server.  This is built using the `mqdev` [build constraint](https://golang.org/pkg/go/build/#hdr-Build_Constraints).
+A special version of `runmqserver` is used in the developer image, which performs extra actions like starting the web server.  This is built using the `mqdev` [build constraint](https://golang.org/pkg/go/build/#hdr-Build_Constraints).
+
+## Prometheus metrics
+[Prometheus](https://prometheus.io) metrics are generated for the queue manager as follows:
+
+1. A connection is established with the queue manager
+2. Metrics are discovered by subscribing to topics that provide meta-data on metric classes, types and elements
+3. Subscriptions are then created for each topic that provides this metric data
+4. Metrics are initialised using Prometheus names mapped from their element descriptions
+5. The metrics are then registered with the Prometheus registry as Prometheus Gauges
+6. Publications are processed on a periodic basis to retrieve the metric data
+7. An HTTP server is setup to listen for requests from Prometheus on `/metrics` port `9157`
+8. Prometheus requests are handled by updating the Prometheus Gauges with the latest metric data
+9. These updated Prometheus Gauges are then collected by the Prometheus registry

docs/usage.md

@@ -37,6 +37,21 @@ docker run \
 
 The Docker image always uses `/mnt/mqm` for MQ data, which is correctly linked for you under `/var/mqm` at runtime.  This is to handle problems with file permissions on some platforms.
 
+## Running with the default configuration and Prometheus metrics enabled
+You can run a queue manager with [Prometheus](https://prometheus.io) metrics enabled.  The following command will generate Prometheus metrics for your queue manager on `/metrics` port `9157`:
+
+```
+docker run \
+  --env LICENSE=accept \
+  --env MQ_QMGR_NAME=QM1 \
+  --env MQ_ENABLE_METRICS=true \
+  --publish 1414:1414 \
+  --publish 9443:9443 \
+  --publish 9157:9157 \
+  --detach \
+  ibmcom/mq
+```
+
 ## Customizing the queue manager configuration
 
 You can customize the configuration in several ways: