{"id":15062653,"url":"https://github.com/krzko/run-o11y-run","last_synced_at":"2025-08-08T14:07:48.072Z","repository":{"id":163463103,"uuid":"638738431","full_name":"krzko/run-o11y-run","owner":"krzko","description":"🌯 Run an observability stack from a single binary. Traces, metrics, logs and profiles.","archived":false,"fork":false,"pushed_at":"2025-03-10T06:19:37.000Z","size":222,"stargazers_count":59,"open_issues_count":10,"forks_count":11,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-09T23:38:32.962Z","etag":null,"topics":["distributed-tracing","grafana","metrics","o11y","observability","opentelemetry","otel","profiling","prometheus","pyroscope","tempo","traces"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/krzko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-10T02:12:02.000Z","updated_at":"2025-05-15T02:42:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"399ba910-56c9-42ca-8d19-2872ca506d4e","html_url":"https://github.com/krzko/run-o11y-run","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/krzko/run-o11y-run","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krzko%2Frun-o11y-run","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krzko%2Frun-o11y-run/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krzko%2Frun-o11y-run/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krzko%2Frun-o11y-run/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/krzko","download_url":"https://codeload.github.com/krzko/run-o11y-run/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krzko%2Frun-o11y-run/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260124031,"owners_count":22962198,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["distributed-tracing","grafana","metrics","o11y","observability","opentelemetry","otel","profiling","prometheus","pyroscope","tempo","traces"],"created_at":"2024-09-24T23:44:08.372Z","updated_at":"2025-06-16T08:05:46.835Z","avatar_url":"https://github.com/krzko.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# run-o11y-run\n\n```sh\n_____ _____ _____     _____ ___   ___   __ __     _____ _____ _____\n| __  |  |  |   | |___|     |_  | |_  | |  |  |___| __  |  |  |   | |\n|    -|  |  | | | |___|  |  |_| |_ _| |_|_   _|___|    -|  |  | | | |\n|__|__|_____|_|___|   |_____|_____|_____| |_|     |__|__|_____|_|___|\n\n```\n\nA single-binary 🌯 wrapper around `docker compose` with embedded configurations to effortlessly run your local observability stack.\n\nThe underlying observability stack is built on [Grafana](https://grafana.com/) products and [OpenTelemetry](https://opentelemetry.io/). It includes the following services:\n\n* [Grafana](https://grafana.com/oss/grafana/)\n* [Grafana Loki](https://grafana.com/oss/loki/)\n* [Grafana Tempo](https://grafana.com/oss/tempo/)\n* [MinIO](https://min.io/)\n* [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)\n* [Prometheus](https://grafana.com/oss/prometheus/)\n* [Pyroscope](https://pyroscope.io/)\n\n## Prerequisites\n\n`run-o11y-run` depends on the latest version of [Docker Desktop](https://www.docker.com/products/docker-desktop/), which includes the `docker compose` command.\n\n## Quick Start\n\n### Install\n\n#### brew\n\nInstall [brew](https://brew.sh/) and then run:\n\n```sh\nbrew install krzko/tap/run-o11y-run\n```\n\n#### Download Binary\n\nDownload the latest version from the [Releases](https://github.com/krzko/run-o11y-run/releases) page.\n\n### Run\n\n* Run `run-o11y-run`\n* 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**:\n    * OTLP (grpc): http://localhost:4317\n    * OTLP (http): http://localhost:4318\n    * Jaeger: http://localhost:14268\n    * Zipkin: http://localhost:9411\n* Logs are processed via two means:\n  * Tailed from `/var/log/*.log` and `./*.log` on your local machine.\n  * A Syslog RFC 3164 header format, `syslog` receiver operates on `localhost:8094`\n* Profiling data can be pushed to http://localhost:4040\n* To exit gracefully, press `CTRL+C`.\n\n## Commands\n\n`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`.\n\n```sh\n$ run-o11y-run start\n\n✨ Starting...\n[+] Running 56/39\n ✔ tempo 5 layers [⣿⣿⣿⣿⣿]      0B/0B      Pulled                                                                                                           142.9s\n ⠦ minio 9 layers [⣿⣿⣿⣿⣿⣄⣿⣿⣿] 48.23MB/96.92MB Pulling                                                                                                      170.6s\n ⠦ otel-collector 6 layers [⣿⣿⣿⣿⣿⣷] 45.09MB/48.15MB Pulling                                                                                                170.6s\n ⠦ grafana 12 layers [⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿]      0B/0B      Pulling                                                                                                170.6s\n ⠦ prometheus 15 layers [⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿]      0B/0B      Pulling                                                                                          170.6s\n ✔ loki 9 layers [⣿⣿⣿⣿⣿⣿⣿⣿⣿]      0B/0B      Pulled                                                                                                         81.8s\n```\n\n### `start` Command\n\nThe `start` command allows you to launch run-o11y-run containers and start your observability stack effortlessly. You can customise the behaviour using various flags.\n\nOne 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`:\n\n```sh\nrun-o11y-run start --registry \u003cregistry-url\u003e\n```\n\nReplace `\u003cregistry-url\u003e` with the URL of your desired Docker Registry.\n\nTo 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.\n\nTo start run-o11y-run in `detached` mode, use the `--detach` flag. This will start the containers in the background.\n\nThe `--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.\n\n  * **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\n\nFor more details on using the `--external-network` flag, refer to the [External Network](docs/external-network.md) guide.\n\n### `patch` Command\n\nThe `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.\n\nSee the extended [patch](docs/patch.md) documentation for more detailed information.\n\n### `stop` Command\n\nThe `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:\n\n```sh\nrun-o11y-run stop\n```\n\n### `open` Command\n\nThe `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.:\n\n```sh\nrun-o11y-run open --service \u003cloki|tempo|prometheus|prometheus-direct|pyroscope-direct\u003e\n```\n\nEnsure that run-o11y-run is already running before using the open command.\n\n**Note:** Make sure your default web browser is properly configured on your system for this command to work.\n\n### `clean` Command\n\nThe `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:\n\n```sh\nrun-o11y-run clean\n```\n\n### `ports` Command\n\nThe `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.\n\nHere's an example output of the ports command:\n\n```sh\n+-----------+-------------------+\n|   PORT    |      SERVICE      |\n+-----------+-------------------+\n| 3000/tcp  | Grafana           |\n| 3100/tcp  | Loki              |\n| 4040/tcp  | Pyropscope        |\n| 4317/tcp  | OTLP (gRPC)       |\n| 4318/tcp  | OTLP (HTTP)       |\n| 8094/tcp  | Syslog (RFC3164)  |\n| 9090/tcp  | Prometheus Direct |\n| 9411/tcp  | Zipkin            |\n| 14268/tcp | Jaeger            |\n+-----------+-------------------+\n```\n\n## Local Service Links\n\n* [Grafana Loki](http://localhost:3000/explore?orgId=1\u0026left=%7B%22datasource%22:%22P8E80F9AEF21F6940%22,%22queries%22:%5B%7B%22refId%22:%22A%22,%22datasource%22:%7B%22type%22:%22loki%22,%22uid%22:%22P8E80F9AEF21F6940%22%7D%7D%5D,%22range%22:%7B%22from%22:%22now-1h%22,%22to%22:%22now%22%7D%7D)\n* [Grafana Tempo](http://localhost:3000/explore?orgId=1\u0026left=%7B%22datasource%22:%22tempo%22,%22queries%22:%5B%7B%22refId%22:%22A%22,%22datasource%22:%7B%22type%22:%22tempo%22,%22uid%22:%22tempo%22%7D%7D%5D,%22range%22:%7B%22from%22:%22now-1h%22,%22to%22:%22now%22%7D%7D)\n* [Grafana Prometheus](http://localhost:3000/explore?orgId=1\u0026left=%7B%22datasource%22:%22prometheus%22,%22queries%22:%5B%7B%22refId%22:%22A%22,%22datasource%22:%7B%22type%22:%22prometheus%22,%22uid%22:%22prometheus%22%7D%7D%5D,%22range%22:%7B%22from%22:%22now-1h%22,%22to%22:%22now%22%7D%7D)\n* [Prometheus Direct](http://localhost:9090/)\n* [Pyroscope Direct](http://localhost:4040/)\n\n## Documentation\n\n* [FlameQL](https://pyroscope.io/docs/flameql/)\n* [LogQL](https://grafana.com/docs/loki/latest/logql/)\n* [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/)\n* [TraceQL](https://grafana.com/docs/tempo/latest/traceql/)\n\n## Troubleshooting\n\n`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.\n\nMake sure you run `run-o11y-run -clean` to clean up the configurations before attempting any troubleshooting steps.\n\nIn case you need further assistance, refer to the [Docker documentation](https://docs.docker.com/) and [Docker troubleshooting guide](https://docs.docker.com/engine/troubleshooting/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrzko%2Frun-o11y-run","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkrzko%2Frun-o11y-run","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrzko%2Frun-o11y-run/lists"}