_____ _____ _____     _____ ___   ___   __ __     _____ _____ _____
| __  |  |  |   | |___|     |_  | |_  | |  |  |___| __  |  |  |   | |
|    -|  |  | | | |___|  |  |_| |_ _| |_|_   _|___|    -|  |  | | | |
|__|__|_____|_|___|   |_____|_____|_____| |_|     |__|__|_____|_|___|

A single-binary 🌯 wrapper around docker compose with embedded configurations to effortlessly run your local observability stack.

The underlying observability stack is built on Grafana products and OpenTelemetry. It includes the following services:

• Grafana
• Grafana Loki
• Grafana Tempo
• MinIO
• OpenTelemetry Collector
• Prometheus
• Pyroscope

run-o11y-run depends on the latest version of Docker Desktop, which includes the docker compose command.

Install brew and then run:

brew install krzko/tap/run-o11y-run

Download the latest version from the Releases page.

• Run run-o11y-run
• Configure your service to push telemetry data to one of the following endpoints. This can be done by setting the OTEL_EXPORTER_OTLP_ENDPOINT environment variable or updating your config file. Make sure to set the traffic to insecure:
  • OTLP (grpc): http://localhost:4317
  • OTLP (http): http://localhost:4318
  • Jaeger: http://localhost:14268
  • Zipkin: http://localhost:9411
• Logs are processed via two means:
  • Tailed from /var/log/*.log and ./*.log on your local machine.
  • A Syslog RFC 3164 header format, syslog receiver operates on localhost:8094
• Profiling data can be pushed to http://localhost:4040
• To exit gracefully, press CTRL+C.

run-o11y-run is a powerful command-line tool that provides seamless management of your local observability stack. It offers three simple commands: start, stop, and clean.

$ run-o11y-run start

✨ Starting...
[+] Running 56/39
 ✔ tempo 5 layers [⣿⣿⣿⣿⣿]      0B/0B      Pulled                                                                                                           142.9s
 ⠦ minio 9 layers [⣿⣿⣿⣿⣿⣄⣿⣿⣿] 48.23MB/96.92MB Pulling                                                                                                      170.6s
 ⠦ otel-collector 6 layers [⣿⣿⣿⣿⣿⣷] 45.09MB/48.15MB Pulling                                                                                                170.6s
 ⠦ grafana 12 layers [⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿]      0B/0B      Pulling                                                                                                170.6s
 ⠦ prometheus 15 layers [⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿]      0B/0B      Pulling                                                                                          170.6s
 ✔ loki 9 layers [⣿⣿⣿⣿⣿⣿⣿⣿⣿]      0B/0B      Pulled                                                                                                         81.8s

The start command allows you to launch run-o11y-run containers and start your observability stack effortlessly. You can customise the behaviour using various flags.

One such flag is the --registry flag, which enables you to specify a Docker Registry from which to pull the required images. By default, run-o11y-run uses Docker Hub as the registry. Here's an example of using the --registry flag:

run-o11y-run start --registry <registry-url>

Replace <registry-url> with the URL of your desired Docker Registry.

To further enhance your setup, you can also utilise the --external-network flag, which enables integration of your own docker-compose configurations with run-o11y-run. This allows you to combine the services of run-o11y-run with your existing infrastructure seamlessly.

To start run-o11y-run in detached mode, use the --detach flag. This will start the containers in the background.

The --yolo flag can be used with the run-o11y-run command to apply the :latest tag to all images in your stack. This flag allows you to conveniently run the latest versions of the images without specifying the specific tags.

• NOTE: However, please note that using the --yolo flag may introduce potential risks, as it may lead to compatibility issues or unexpected behaviour if the latest images have breaking changes or dependencies

For more details on using the --external-network flag, refer to the External Network guide.

The stop command is used to gracefully stop the run-o11y-run containers. It ensures a clean shutdown of your observability stack. Here's an example of using the stop command:

run-o11y-run stop

The open command allows you to conveniently open various services provided by run-o11y-run in your default web browser. This feature saves you time by quickly launching the relevant service pages.:

run-o11y-run open --service <loki|tempo|prometheus|prometheus-direct|pyroscope-direct>

Ensure that run-o11y-run is already running before using the open command.

Note: Make sure your default web browser is properly configured on your system for this command to work.

The clean command is used to stop and remove run-o11y-run containers, files, and networks. It helps you clean up your environment after using run-o11y-run. Here's an example of using the clean command:

run-o11y-run clean

The ports command allows you to list the available ports used by the application. It provides a convenient way to check which ports are used by various services within the observability stack.

Here's an example output of the ports command:

+-----------+-------------------+
|   PORT    |      SERVICE      |
+-----------+-------------------+
| 3000/tcp  | Grafana           |
| 3100/tcp  | Loki              |
| 4040/tcp  | Pyropscope        |
| 4317/tcp  | OTLP (gRPC)       |
| 4318/tcp  | OTLP (HTTP)       |
| 8094/tcp  | Syslog (RFC3164)  |
| 9090/tcp  | Prometheus Direct |
| 9411/tcp  | Zipkin            |
| 14268/tcp | Jaeger            |
+-----------+-------------------+

• Grafana Loki
• Grafana Tempo
• Grafana Prometheus
• Prometheus Direct
• Pyroscope Direct

• FlameQL
• LogQL
• PromQL
• TraceQL

run-o11y-run is built on top of Docker, and if you encounter any issues or things don't seem to be working as expected, please use the standard Docker debugging techniques.

Make sure you run run-o11y-run -clean to clean up the configurations before attempting any troubleshooting steps.

In case you need further assistance, refer to the Docker documentation and Docker troubleshooting guide.