The NATS Blackbox Exporter is a tool designed to monitor and track key metrics related to NATS Jetstream. At Snapp!, we use this to detect the status of our NATS clusters from the client perspective.

This project uses the github.com/nats-io/nats.go package to interact with NATS. Specifically, it utilizes the JetStreamContext interface to enable JetStream messaging and stream management.

A blackbox exporter is a type of software that monitors the availability and performance of services by performing remote checks, as opposed to whitebox monitoring which relies on internal metrics and logs. In this case, the blackbox exporter monitors NATS by measuring connection events, message latency, and success rates.

You can deploy and use NATS Blackbox Exporter using Docker images or by building from the source code.

You can use pre-built Docker images from GitHub Container Registry (GHCR):

docker run -d -p 8080:8080 --name nats-blackbox-exporter -v ./setting/config.yaml:/app/setting/config.yaml:ro ghcr.io/snapp-incubator/nats-blackbox-exporter:<release-tag> --configPath ./setting/config.yaml

and then pass environment variables as needed.

You can build the project from the source code:

go build -o nats-blackbox-exporter cmd/nats-blackbox-exporter/main.go

The exporter will generate Prometheus metrics on the port specified in the configuration file, accessible at the /metrics path. The key metrics tracked include:

• Connection: A prometheus.CounterVec that counts disconnections and connections.
• Latency: A prometheus.Histogram that measures the latency between publishing and subscribing.
• SuccessCounter: A prometheus.CounterVec that counts successful publishes and consumes.

You can check the list of parameters with default values in the config.example.yaml file. The NATS Blackbox Exporter can be configured in three ways:

1. Environment Variables: Set the necessary environment variables before running the exporter.

2. Configuration File:

   Use a config.yaml file to specify configuration parameters. You can specify the path to the config file using the --configPath flag.

   Example usage:

   ./nats-blackbox-exporter --configPath /path/to/config.yaml

   Replace /path/to/config.yaml with the actual path to your configuration file.

3. Default Values: If neither environment variables nor a configuration file is provided, the exporter will use default values.