From 5b208ef27c4a525d4f924b7ece3bb82f1022b499 Mon Sep 17 00:00:00 2001 From: Kristof Kowalski Date: Sun, 28 May 2023 09:44:09 +1000 Subject: [PATCH] docs: refactor docs --- README.md | 39 +++++++++++++++----- docs/docker-compose.yaml | 15 ++++++++ docs/external-network.md | 78 ++++++++++++++++++++++++++++++++++++++++ multi-compose.md | 62 -------------------------------- 4 files changed, 124 insertions(+), 70 deletions(-) create mode 100644 docs/docker-compose.yaml create mode 100644 docs/external-network.md delete mode 100644 multi-compose.md diff --git a/README.md b/README.md index 31073e8..981b699 100644 --- a/README.md +++ b/README.md @@ -49,12 +49,14 @@ Download the latest version from the [Releases](https://github.com/krzko/run-o11 * Jaeger: http://localhost:14268 * Zipkin: http://localhost:9411 * Logs are procedd via two means: - * Tailed from `/var/log/*.log` and `$(PWD)/*.log` on your local machine. + * 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`. + ```sh $ run-o11y-run start @@ -68,16 +70,37 @@ $ run-o11y-run start ✔ loki 9 layers [⣿⣿⣿⣿⣿⣿⣿⣿⣿] 0B/0B Pulled 81.8s ``` -`run-o11y-run` is a command-line tool with three simple commands: `start`, `stop`, and `clean`. +### 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`: + +```sh +run-o11y-run start --registry +``` + +Replace `` 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. -- `start`: Starts run-o11y-run containers. You can use the `--registry` flag to specify a Docker Registry. By default, it uses Docker Hub, but if you wish to specifcy your own, use this example - Example: `run-o11y-run start --registry ` +For more details on using the `--external-network` flag, refer to the [External Network Guide](docs/external-network.md). -- `stop`: Stops run-o11y-run containers. - Example: `run-o11y-run stop` +### Stop Command -- `clean`: Stops and removes run-o11y-run containers, files, and networks. - Example: `run-o11y-run clean` +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: + +```sh +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: + +```sh +run-o11y-run clean +``` ## Local Service Links diff --git a/docs/docker-compose.yaml b/docs/docker-compose.yaml new file mode 100644 index 0000000..1fe1e08 --- /dev/null +++ b/docs/docker-compose.yaml @@ -0,0 +1,15 @@ +version: '2' + +networks: + o11y: + name: o11y + driver: bridge + external: true + +services: + curl: + image: curlimages/curl:latest + networks: + - o11y + # Generates, HTTP/1.1 405 Method Not Allowed + command: "-v otel-collector:4318/v1/traces" diff --git a/docs/external-network.md b/docs/external-network.md new file mode 100644 index 0000000..bd53339 --- /dev/null +++ b/docs/external-network.md @@ -0,0 +1,78 @@ +# External Network + +In certain scenarios, users may need to integrate their own `docker-compose` configurations with `run-o11y-run`. To facilitate this, we provide support for a multi docker-compose setup. + +To utilise this feature, simply run `run-o11y-run` with the `--external-network` flag. This allows you to seamlessly integrate your existing `docker-compose` configurations with `run-o11y-run`, enabling you to leverage the power of both environments in a unified manner. + +Here's an example of how you can set up your `docker-compose` configurations to work with `run-o11y-run`: + +1. To start `run-o11y-run` with an external bridged `o11y` network, simply run the following command: + +```sh +run-o11y-run start --external-network +``` + +This command initiates `run-o11y-run` and enables seamless integration with your existing infrastructure through the `o11y` network. By using the `--external-network` flag, you establish a bridge between `run-o11y-run` and your custom `docker-compose` configurations. + +2. Modify your `docker-compose.yaml` file to include a network definition for the o11y network: + +```yaml +networks: + o11y: + name: o11y + driver: bridge + external: true +``` + +3. Update the services in your `docker-compose.yaml` file to use the `o11y` network: + +```yaml +services: + foo: + image: ... + networks: + - o11y + environments: + - OTEL_EXPORTER_OTLP_ENDPOINT: otel-collector:431... + + bar: + image: ... + networks: + - o11y + environemnts: + - OTEL_EXPORTER_OTLP_ENDPOINT: otel-collector:431... +``` + +By connecting your customer-managed `docker-compose` setup with `run-o11y-run` assets through the `o11y` network, you establish communication between your applications and the observability components provided by `run-o11y-run`. + +## Network flow + +Here's a visual representation of the network flow: + +```mermaid +flowchart TD + + subgraph run-o11y-run["run-o11y-run docker-compose"] + direction LR + + collector + minio --- loki + collector --- loki + collector --- prometheus + collector --- zipkin + end + + subgraph application["application docker-compose"] + direction LR + + app1[app 1] + app2[app 2] + app1 --"default network"---app2 + end + + application---collector +``` + +This diagram illustrates how your application services (`app1` and `app2`) can communicate with the observability components provided by `run-o11y-run` through the `o11y` network. + +You can refer to the example file provided [here](docker-compose.yaml). diff --git a/multi-compose.md b/multi-compose.md deleted file mode 100644 index df9a296..0000000 --- a/multi-compose.md +++ /dev/null @@ -1,62 +0,0 @@ -# multi docker-compose setup - -In some cases user may want to integrate theirs own `docker-compose` with `run-o11-run`. - -To achieve this goal, please run `run-o11y-run` with `--external-network` flag - -```sh -run-o11y-run start --external-network -``` - -and modify your dockerfile to use `o11y` network. Sample setup may look like: - -```yaml -networks: - o11y: - name: o11y - driver: bridge - external: true - -services: - foo: - image: ... - networks: - - o11y - environments: - - OTEL_EXPORTER_OTLP_ENDPOINT: otel-collector:431... - - bar: - image: ... - networks: - - o11y - environemnts: - - OTEL_EXPORTER_OTLP_ENDPOINT: otel-collector:431... -``` - -## Network flow - -Customer managed `docker-compose` with `app 1` & `app 2` is connected to `run-o11y-run` assets via `o11y` network which is defined as external. - -```mermaid -flowchart TD - - subgraph run-o11y-run["run-o11y-run docker-compose"] - direction LR - - collector - minio --- loki - collector --- loki - collector --- prometheus - collector --- zipkin - end - - subgraph application["application docker-compose"] - direction LR - - app1[app 1] - app2[app 2] - app1 --"default network"---app2 - end - - application---collector -``` \ No newline at end of file