Aeron Insights Example

The Aeron Insights example allows you to experiment with Aeron Insights using a test cluster you can run locally using Docker. It includes the following components:

  • A sample Aeron cluster application.

  • The Docker Compose files necessary to start this cluster.

  • Mechanisms for exporting metrics from this cluster to a Prometheus instance using Aeron Insights.

  • A sample Grafana dashboard that shows some of the metrics it exports, and how these can be interpreted.

  • A command-line tool you can run in the cluster containers for getting additional insight into the application.

These are packaged into a zip file that can be downloaded from the Adaptive Artifactory.

Aeron Insights gives you two mechanisms for exporting metrics to Prometheus. One is an HTTP server that can run alongside each of your cluster nodes that Prometheus can scrape directly. The other is a push client that can send the metrics for each node to a Prometheus Push Gateway. These examples show you how to use either approach.

How to run the examples using the HTTP Exporter

To use the HTTP server approach for exporting to Prometheus, run the following command:

docker compose -f aeron-insights-example/docker/docker-compose.yml -f aeron-insights-example/docker/docker-compose-httpd-exporter.yml up

This will start the cluster, a Prometheus instance, an exporter HTTP server for each cluster node, and a Grafana instance with the sample dashboard.

How to run the examples using the Push Gateway

To use the Push Gateway approach to exporting to Prometheus, run the following command:

docker compose -f aeron-insights-example/docker/docker-compose.yml -f aeron-insights-example/docker/docker-compose-push-exporter.yml up

This will start the cluster, a Prometheus instance, a Prometheus Push Gateway, a push-client exporter for each cluster node, and a Grafana instance with the sample dashboard.

How to view the Grafana dashboard

The sample dashboard is an example Grafana dashboard that showcases the data exposed by the Prometheus Exporter. You can use the sample dashboard to see what kinds of metrics are available, and to see how to interpret these metrics.

Once you have started the examples using either of the approaches described above, you will be able to access the Cluster Overview Grafana dashboard at http://localhost:3000/dashboards.

How to run the Insights CLI on one of the nodes

The following will run the cluster-status command of the Insights CLI on node0.

docker compose -f aeron-insights-example/docker/docker-compose.yml exec node0 insights.sh cluster-status

To see usage information and what other commands the CLI supports, you can run it with --help.

docker compose -f aeron-insights-example/docker/docker-compose.yml exec node0 insights.sh --help

How to stop the examples

To shut down the docker containers and remove the volumes they created, run the following command:

docker compose -f aeron-insights-example/docker/docker-compose.yml -f aeron-insights-example/docker/docker-compose-httpd-exporter.yml -f aeron-insights-example/docker/docker-compose-push-exporter.yml down -v