_____ _____ _____ _____ ___ ___ __ __ _____ _____ _____
| __ | | | | |___| |_ | |_ | | | |___| __ | | | | |
| -| | | | | |___| | |_| |_ _| |_|_ _|___| -| | | | | |
|__|__|_____|_|___| |_____|_____|_____| |_| |__|__|_____|_|___|
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:
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-runDownload 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_ENDPOINTenvironment 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/*.logand./*.logon your local machine. - A Syslog RFC 3164 header format,
syslogreceiver operates onlocalhost:8094
- Tailed from
- 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.8sThe 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
--yoloflag 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 patch command in run-o11y-run provides a convenient way to modify your own docker-compose.yaml file, allowing you to establish a network bridge between the o11y stack and your customer stack. This feature is particularly useful when you have started the o11y stack with the --external-network flag, enabling seamless integration with your existing infrastructure.
See the extended patch documentation for more detailed information.
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 stopThe 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 cleanThe 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 |
+-----------+-------------------+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.