Prometheus: Usage guide #300
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
WalkthroughAdded a new ignore pattern to docs linkcheck, relabeled sections and links in the Prometheus integration index, and added a new Prometheus "Usage" guide documenting a Docker Compose setup for Prometheus → CrateDB ingestion. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (3)
🚧 Files skipped from review as they are similar to previous changes (3)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🧪 Early access (Sonnet 4.5): enabledWe are currently testing the Sonnet 4.5 model, which is expected to improve code review quality. However, this model may lead to increased noise levels in the review comments. Please disable the early access features if the noise level causes any inconvenience. Note:
Comment |
amotl
force-pushed
the
prometheus
branch
2 times, most recently
from
8ed9a9a to
efb7776
Compare
|
@coderabbitai review and please refactor to active voice. |
|
@amotl I'll review the PR and focus on identifying passive voice constructions that should be refactored to active voice, as per your previous guidance. 🧠 Learnings used✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (16)
docs/conf.py (1)
74-76: Drop the ComputerHope ignore (remove the brittle external link instead).You added this ignore only to accommodate an external “text editor” link in the tutorial. Replace that link in the tutorial (see my comment there) and remove this ignore to keep linkcheck strict.
- # 403 Client Error: Forbidden for url - r"https://www.computerhope.com/",After applying the tutorial change, run Sphinx linkcheck to confirm it passes without this ignore.
docs/integrate/prometheus/tutorial.md (15)
4-4: Remove ego voice in the intro.Switch to neutral, active voice.
-In this tutorial, I show how to +This tutorial shows how to:
9-9: Tighten version note; use active voice.-*Note: this blog post uses CrateDB 4.7.0, Prometheus 2.33.3 and CrateDB Prometheus Adapter 0.4.0* +*Note: These examples use CrateDB 4.7.0, Prometheus 2.33.3, and the CrateDB Prometheus Adapter 0.4.0.*Consider pinning the same versions in the docker-compose snippet below for consistency.
21-27: Rewrite setup paragraphs to active voice and remove the brittle external “text editor” link.-Both CrateDB, Prometheus, and the CrateDB Prometheus Adapter applications can be run as [Docker containers](https://www.docker.com/resources/what-container). To then centralize the container management I use [Docker Compose](https://docs.docker.com/compose/), this way I can build and run all the containers with a single command and set up the connections between them in a YAML file. - -Before anything else, I follow the [Docker Installation Tutorial](https://docs.docker.com/get-docker/) to get Docker in my local machine. - -Then, I create a directory in my local machine to host the necessary configuration files. -I’ll have a total of three of them, all following the YAML format. They can be easily created using any [text editor](https://www.computerhope.com/jargon/e/editor.htm), like TextEdit on a Mac, and then saved with the `.yml` format. +Run CrateDB, Prometheus, and the CrateDB Prometheus Adapter as [Docker containers](https://www.docker.com/resources/what-container). +Use [Docker Compose](https://docs.docker.com/compose/) to centralize container management so you can build and run all containers with one command and define their connections in a YAML file. + +Install Docker by following the [Docker installation guide](https://docs.docker.com/get-docker/). + +Create a directory on your machine to host the configuration files. +Create three YAML files with your preferred editor and save them with the `.yml` extension.If you prefer keeping a “what is a text editor” link, point to a more stable source (or omit the link).
30-33: Remove first person; keep instructions direct.-### Create `docker-compose.yml` - -The first YAML file I create is `docker-compose.yml`, which wraps up the configurations for the three containers. - -I specify CrateDB, Prometheus, and Adapter as services. Then, I add `config.yml` and `prometheus.yml` files as volumes to the Adapter and Prometheus containers, respectively. These files will be created in the following steps. +### Create `docker-compose.yml` + +Create `docker-compose.yml` to configure the three containers. +Define services for CrateDB, Prometheus, and the adapter. Mount `config.yml` and `prometheus.yml` into the adapter and Prometheus containers, respectively. You will create these files in the following steps.
34-52: Pin image versions and persist CrateDB data.Pin images to the versions you mention above and add a data volume for CrateDB. Also add basic restart policies.
services: cratedb: - image: "crate" + image: "crate:4.7.0" # Pin for reproducibility; update as needed ports: - "4200:4200" - "5432:5432" + volumes: + - cratedb-data:/data + restart: unless-stopped prometheus: - image: "prom/prometheus" + image: "prom/prometheus:v2.33.3" volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml ports: - "9090:9090" + restart: unless-stopped cratedb-prometheus-adapter: - image: "ghcr.io/crate/cratedb-prometheus-adapter" + image: "ghcr.io/crate/cratedb-prometheus-adapter:0.4.0" volumes: - ./config.yml:/etc/cratedb-prometheus-adapter/config.yml ports: - "9268:9268" + depends_on: + - cratedb + restart: unless-stoppedAdd this at the end of the compose file to define the named volume:
volumes: cratedb-data:Verify the exact tags you want to recommend (or update to current stable). If using Compose V2, consider adding a top-level
name:for a predictable network/volume prefix.
56-65: Active voice and clarity in the Prometheus config section.-Next, following the[ Prometheus Documentation](https://prometheus.io/docs/prometheus/latest/getting_started/), I create a `prometheus.yml` file, which holds the scraping configuration for whichever service Prometheus collects metrics from. - -To keep it simple, I follow the example in the Prometheus documentation and set it to monitor itself. - -One last bit of configuration necessary to forward requests from Prometheus to the CrateDB Adapter is to set `remote_write` and `remote_read` to the Adapter URL, as stated in [CrateDB Prometheus Adapter Setup](https://github.com/crate/cratedb-prometheus-adapter). - -As I’m running the Adapter on Docker instead of locally, the host in its URL will not be `localhost`, but rather however I called the Adapter service previously in my `docker-compose.yml` file, in this case, `cratedb-prometheus-adapter`. - -The resulting prometheus.yml looks then like this: +Next, create `prometheus.yml` as described in the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/getting_started/). This file defines which services Prometheus scrapes. + +To keep it simple, monitor Prometheus itself. + +To forward samples to CrateDB, set `remote_write` and `remote_read` to the adapter URL (see the [CrateDB Prometheus Adapter setup](https://github.com/crate/cratedb-prometheus-adapter)). + +Because the adapter runs in Docker, use the adapter service name from `docker-compose.yml` (`cratedb-prometheus-adapter`) instead of `localhost` in the URLs. + +Use the following `prometheus.yml`:
93-107: Active voice in adapter config section.-Finally, following the [CrateDB Prometheus Adapter setup instructions](https://github.com/crate/cratedb-prometheus-adapter), I create the `config.yml` file, which defines the CrateDB endpoints the Adapter writes to. - -As I did previously in the `prometheus.yml` file, the host is set to `cratedb`, which is how I declared the CrateDB service on the `docker-compose.yml` file, instead of the default `localhost`. The remaining variables are set with their default values. +Finally, create `config.yml` as described in the [CrateDB Prometheus Adapter setup](https://github.com/crate/cratedb-prometheus-adapter). This file defines the CrateDB endpoints the adapter writes to. + +Set the host to `cratedb` (the service name in `docker-compose.yml`) instead of `localhost`. Keep the remaining variables at their defaults.
108-108: Fix agreement and remove first person.-I make sure both `docker-compose.yml`, `config.yml`, and `prometheus.yml` are in the same directory in my local machine. +Place `docker-compose.yml`, `config.yml`, and `prometheus.yml` in the same directory on your machine.
118-118: Remove the Google search link; link directly and use active voice.-With Docker Compose up and running, I follow the [CrateDB Prometheus Adapter setup instructions](https://github.com/crate/cratedb-prometheus-adapter), navigate to the [CrateDB Admin UI](https://www.google.com/search?client=safari&rls=en&q=cratedb+admin+ui&ie=UTF-8&oe=UTF-8) at [http://localhost:4200](http://localhost:4200/) and create a `metrics` table in CrateDB, which will store the metrics gathered by Prometheus. +After Docker Compose starts, open the CrateDB Admin UI at [http://localhost:4200](http://localhost:4200/) and create a `metrics` table to store metrics gathered by Prometheus.
131-136: Active voice and concise instructions for Prometheus UI.-Then I navigate to [http://localhost:9090](http://localhost:9090/), where I find the Prometheus UI. There, I head to **Status** and then **Targets** - - - -And confirm that Prometheus is successfully monitoring itself. +Navigate to [http://localhost:9090](http://localhost:9090/) to open the Prometheus UI. Go to **Status** → **Targets**. + + + +Confirm that Prometheus monitors itself.
139-147: Active voice and neutral tone; avoid marketing language.-Lastly, I head back to the CrateDB Admin UI and select the `metrics` table I just created. - -I see that only after a few minutes of running, Prometheus has gathered over 300k data points. +Return to the CrateDB Admin UI and select the `metrics` table you created. + +After a few minutes, Prometheus will have gathered hundreds of thousands of data points. - - -I can now enjoy CrateDB’s incredible query speed to analyze and visualize this -data using tools like {ref}`grafana`, which works effortlessly with CrateDB. + + +Use CrateDB’s query engine to analyze and visualize this data with tools like {ref}`grafana`.
84-85: Optional: scrape Prometheus via service name for clarity in Compose networks.Inside containers,
localhost:9090works, but using the service name improves readability.- - targets: ['localhost:9090'] + - targets: ['prometheus:9090']This requires the service to be named
prometheus(as in your Compose file), which it is.Also applies to: 87-90
34-52: Optional: add healthchecks for better startup sequencing.Consider simple HTTP healthchecks so
depends_oncan be extended tocondition: service_healthyif you choose to use it.cratedb: image: "crate:4.7.0" + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:4200"] + interval: 10s + timeout: 5s + retries: 12 prometheus: image: "prom/prometheus:v2.33.3" + healthcheck: + test: ["CMD", "wget", "-qO-", "http://localhost:9090/-/ready"] + interval: 10s + timeout: 5s + retries: 12 cratedb-prometheus-adapter: image: "ghcr.io/crate/cratedb-prometheus-adapter:0.4.0" + healthcheck: + test: ["CMD", "wget", "-qO-", "http://localhost:9268/health"] + interval: 10s + timeout: 5s + retries: 12
112-116: Use Compose V2 syntax and remove shell prompts (fixes MD014).File: docs/integrate/prometheus/tutorial.md (lines 112–116)
-Finally, I navigate to my CrateDB-Prometheus directory in my terminal and start Docker Compose with the `docker-compose up` command +Finally, navigate to your CrateDB–Prometheus directory and start Docker Compose: ```shell -$ cd /Users/Path/To/Directory/CrateDB-Prometheus -$ docker-compose up +cd /Users/Path/To/Directory/CrateDB-Prometheus +docker compose up -d--- `1-152`: **Remove first‑person and passive constructions in docs/integrate/prometheus/tutorial.md** Occurrences found — rephrase to neutral/imperative voice. - First‑person (I / I'm / I'll / we): lines 4, 21, 23, 25, 26, 30, 32, 56, 58, 62, 93, 95, 108, 112, 118, 131, 139, 141, 145. - Passive/key phrases (can be, will be, is set to, etc.): lines 21, 26, 32, 95. Quick examples: - Line 4: "In this tutorial, I show how to" → "This tutorial shows how to" - Line 21: "can be run as Docker containers" → "run as Docker containers" - Line 112: "Finally, I navigate ... and start Docker Compose with `docker-compose up`" → "From the CrateDB‑Prometheus directory, run `docker-compose up`" </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: CodeRabbit UI **Review profile**: CHILL **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 427d70177fd239764a925f35649bf8565b94b4cd and efb7776b0bd56af7f54646dfbc123679916cbac3. </details> <details> <summary>📒 Files selected for processing (3)</summary> * `docs/conf.py` (1 hunks) * `docs/integrate/prometheus/index.md` (2 hunks) * `docs/integrate/prometheus/tutorial.md` (1 hunks) </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🪛 markdownlint-cli2 (0.17.2)</summary> <details> <summary>docs/integrate/prometheus/index.md</summary> 115-115: Dollar signs used before commands without showing output (MD014, commands-show-output) </details> </details> </details> <details> <summary>⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)</summary> * GitHub Check: Build docs </details> <details> <summary>🔇 Additional comments (2)</summary><blockquote> <details> <summary>docs/integrate/prometheus/index.md (2)</summary><blockquote> `67-69`: **LGTM: use internal cross‑reference for the tutorial card.** The switch to `:link-type: ref` improves durability and keeps navigation inside the docs. --- `115-120`: **LGTM: add hidden toctree entry for the tutorial.** This keeps the page discoverable in Sphinx while preserving the grid layout. </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (6)
docs/integrate/prometheus/tutorial.md (6)
15-20: Refactor motivation to active voice and tighten wordingImproves clarity and avoids passive/impersonal phrasing (“one can,” “comes into place”).
-[Prometheus](https://prometheus.io/docs/introduction/overview/) is a monitoring software for collecting metrics data from applications and infrastructures. Its focus lies on collecting big amounts of concise event data from the monitored system, roughly timestamp points with key-value pairs. - -Such data is very useful to track the state and trajectory of a system, so storing this data for the long term is a common need for Prometheus users. - -This is where [CrateDB](https://cratedb.com/database) comes into place. With the [CrateDB Prometheus Adapter](https://github.com/crate/cratedb-prometheus-adapter), one can easily store the collected metrics data in CrateDB and take advantage of its high ingestion and query speed and friendly UI to massively scale-out Prometheus. +[Prometheus](https://prometheus.io/docs/introduction/overview/) is a monitoring system that collects metrics from applications and infrastructure. It focuses on ingesting large volumes of concise time‑series events—timestamped points with key‑value labels. + +This data helps you track a system’s state and trajectory. Many Prometheus users want to retain it long term. + +[CrateDB](https://cratedb.com/database) helps here. With the [CrateDB Prometheus Adapter](https://github.com/crate/cratedb-prometheus-adapter), you can store metrics in CrateDB and use its fast ingestion, query performance, and admin UI to scale Prometheus.
71-71: Active voice: replace “as described in”Keeps instructions direct.
-Next, create `prometheus.yml` as described in the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/getting_started/). This file defines which services Prometheus scrapes. +Next, create `prometheus.yml` following the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/getting_started/). This file defines the services that Prometheus scrapes.
108-108: Active voice: replace “as described in”Matches tone used elsewhere.
-Finally, create `config.yml` as described in the [CrateDB Prometheus Adapter setup](https://github.com/crate/cratedb-prometheus-adapter). This file defines the CrateDB endpoints the adapter writes to. +Finally, create `config.yml` following the [CrateDB Prometheus Adapter setup](https://github.com/crate/cratedb-prometheus-adapter). This file defines the CrateDB endpoints that the adapter writes to.
149-149: Improve image alt text for accessibilityDescribe what readers should notice in each screenshot.
- + @@ - + @@ - +Also applies to: 153-153, 159-159
164-168: Fix bare URLs and tighten phrasingResolves markdownlint MD034 and keeps an active, direct style.
-Here are a few interesting tutorials on that matter: - -* https://cratedb.com/blog/visualizing-time-series-data-with-grafana-and-cratedb -* https://cratedb.com/blog/monitoring-cratedb-with-prometheus-and-grafana +Explore these related tutorials: + +* [Visualizing time‑series data with Grafana and CrateDB](https://cratedb.com/blog/visualizing-time-series-data-with-grafana-and-cratedb) +* [Monitoring CrateDB with Prometheus and Grafana](https://cratedb.com/blog/monitoring-cratedb-with-prometheus-and-grafana)
127-131: Consider Compose V2 commandIf you target modern Docker, prefer “docker compose” (V2) and add “-d” to detach.
-docker-compose up +docker compose up -d
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/integrate/prometheus/tutorial.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
docs/integrate/prometheus/tutorial.md
166-166: Bare URL used
(MD034, no-bare-urls)
167-167: Bare URL used
(MD034, no-bare-urls)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Build docs
amotl
force-pushed
the
prometheus
branch
2 times, most recently
from
3691767 to
5c66096
Compare
amotl
commented
Sep 20, 2025
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
amotl
force-pushed
the
prometheus
branch
2 times, most recently
from
c99c51a to
e27df98
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
About
Continue adding integration guides from the community forum.
Preview
References