run-o11y-run

README

run-o11y-run

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

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

Prerequisites

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

Quick Start

Install

brew

Install brew and then run:

brew install krzko/tap/run-o11y-run

Download Binary

Download the latest version from the Releases page.

Run

• 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 procedd 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
• To exit gracefully, press CTRL+C.

Commands

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

Start Command

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.

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

Stop Command

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

Clean Command

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

Local Service Links

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

Documentation

• LogQL
• PromQL
• TraceQL

Troubleshooting

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.