EMQ exporter for Prometheus

A simple server that scrapes EMQ metrics and exports them via HTTP for Prometheus consumption.

Getting Started

To run it:

./emq_exporter [flags]

Help on flags:

./emq_exporter --help

Usage

EMQ URI

Specify EMQ's node uri and api port using the --emq.uri flag. For example,

./emq_exporter --emq.uri "http://localhost:8080"

Or to scrape a remote host:

./emq_exporter --emq.uri "https://emq.example.com:8080"

Passing Credentials

EMQ requires that calls made to the API endpoints be authenticated. The exporter supports two ways to pass credentials:

1. Setting environment variables:

• EMQ_USERNAME for username
• EMQ_PASSWORD for the password

No need to pass anything to emq_exporter when using these vars, they will be searched for automatically on startup.

2. Using a file

The file should be json formatted and contain the following fields:

{
  "username": "admin",
  "password": "public"
}

When staring emq_exporter, point it to the credentials file using --emq.creds-file flag:

./emq_exporter --emq.uri http://localhost:8080 --emq.creds-file /etc/emq_exporter/auth.json

The default path for credentials file is $(CWD)/auth.json. Note that env vars take precedence over using a file.

API Version

EMQ add a v3 api version in EMQX. To specify the api version, use the emq.api-version flag:

./emq_exporter --emq.uri http://localhost:8080 --emq.api-version v3

The emq_exporter supports v2, v3 and v4 API versions seamlessly (mutually exclusive, pick either on start up), default is v3. However, from v4 the default port is 8081. Please note the v2 api is deprecated and will be removed in future versions

Authentication

The authentication method changed a bit in version v3 of emqx. If you're pulling the metrics through the dashboard port (default 18083), you can use regular username and password. However, if you're using the API port (default 8080), you'll need to set up application credentials:

1. From the emq dashboard side bar -> applications
2. Select New App from the top
3. Fill in the popup window with the relevant details and confirm
4. View the app details and use AppID as username and AppSecret as password (as creds-file entries or env vars, see above)

The default port emq_exporter uses is 18083

See the docs for v2 REST API here and for v3 here

Troubleshooting

If things aren't working as expected, try to start the exporter with --log.level debug flag. This will log additional details to the console and might help track down the problem. Fell free to raise an issue should you require additional help.

Docker

To run EMQ exporter as a Docker container, run:

docker run \
  -d \
  -p 9540:9540 \
  --name emq_exporter \
  -v /path/to/auth.json:/etc/emq/auth.json \
  nuvo/emq_exporter:v0.4.1 \
  --emq.uri "http://<emq-ip>:8080" \
  --emq.node "emqx@<emq-ip>" \
  --emq.api-version "v3" \
  --emq.creds-file "/etc/emq/auth.json"

Alternatively, One can also supply the credentials using env vars, replace the volume mount (-v flag) with -e EMQ_USERNAME=<my-username> -e EMQ_PASSWORD=<super-secret>

Kubernetes

EMQ exporter was designed to run as a sidecar in the same pod as EMQ itself. See the examples folder for a kubernetes manifest that can serve as reference for implementation.

Contributing

We welcome contributions!

Please see CONTRIBUTING for guidelines on how to get involved.

License

Apache License 2.0, see LICENSE.