Prometheus: Refresh usage guide based on Docker Compose

[amotl]

About

This patch compresses the fundamental tutorial about Storing long-term metrics with Prometheus in CrateDB into a more concise usage guide, while still retaining a few screenshots from the original article written in 2022.

Preview

• https://cratedb-guide--401.org.readthedocs.build/integrate/prometheus/
• https://cratedb-guide--401.org.readthedocs.build/integrate/prometheus/usage.html

References

• INGEST / Metrics, telemetry, and logs: Improve and modernize section #56
• Improve general guidance aka. easy user journey #227

/cc @karynzv, @juanpardo, @WalBeh

[coderabbitai]

Walkthrough

Adds Prometheus integration documentation and artifacts: a Docker/Podman Compose stack, Prometheus config, a CrateDB Prometheus adapter configuration, and a metrics DDL. Reworks Prometheus docs pages and updates the how-to index by removing the 2022 rubric and expanding 2025 entries.

Changes

Cohort / File(s)	Summary
Prometheus integration assets docs/integrate/prometheus/compose.yaml, docs/integrate/prometheus/prometheus.yml, docs/integrate/prometheus/cratedb-prometheus-adapter.yaml, docs/integrate/prometheus/ddl.sql	Adds a compose stack (cratedb, ddl runner, prometheus, adapter) with volumes/healthcheck/restarts, a Prometheus config (scrape/remote_write/remote_read), an adapter endpoint schema (connection, pool, timeout, TLS fields), and a partitioned metrics table DDL.
Prometheus docs pages docs/integrate/prometheus/index.md, docs/integrate/prometheus/usage.md	Replaces layout with rubric/grid items; restructures usage into prerequisites/files/services/explore/screenshots; pivots from inline YAML to downloadable artifacts and simplified orchestration instructions (Docker/Podman).
How-to index curation docs/howto/index.md	Removes the 2022 rubric and its entries; expands the 2025 rubric with multiple new references (including prometheus-usage and several other integrations).

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User
  participant Compose as Docker/Podman Compose
  participant Prom as Prometheus
  participant Adapter as CrateDB Prometheus Adapter
  participant Crate as CrateDB

  User->>Compose: up -d
  Compose->>Crate: start CrateDB
  Compose->>Prom: start Prometheus (scrape & remote endpoints)
  Compose->>Adapter: start adapter (cratedb_endpoints)

  Note over Prom,Adapter: remote_write / remote_read via adapter

  loop scrape
    Prom->>Prom: scrape targets
  end

  Prom->>Adapter: remote_write(samples)
  Adapter->>Crate: INSERT into `testdrive.metrics`
  Crate-->>Adapter: ACK
  Adapter-->>Prom: Success

  User->>Prom: query/graph
  Prom->>Adapter: remote_read(query)
  Adapter->>Crate: SELECT from `testdrive.metrics`
  Crate-->>Adapter: Rows
  Adapter-->>Prom: Timeseries

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• OpenTelemetry: Index page. Usage guides about OTel Collector and Telegraf. #334 — Adds similar integration artifacts (adapter config and metrics DDL) for a related collector.
• Prometheus: Usage guide #300 — Overlapping changes to Prometheus integration docs (usage/index updates).
• Diátaxis: Index how-to guides and tutorials #364 — Edits to the how-to index affecting the 2022/2025 rubrics.

Suggested reviewers

• kneth
• hammerhead
• surister
• WalBeh

Poem

I hop between ports and weave a YAML trail,
I plant metric seeds where scrapes prevail.
Adapter nibbles rows, Crate keeps them tight,
Long-term carrots counted through day and night. 🐇📈

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title accurately summarizes the primary change of refreshing the Prometheus usage guide and emphasizes the adoption of Docker Compose. It is concise and specific, avoiding extraneous details while highlighting the refresh. The phrasing aligns clearly with the updates in the changeset. Therefore, it meets the requirement for a focused and informative pull request title.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.
Description Check	✅ Passed	The pull request description clearly explains that the patch compresses the existing Prometheus tutorial into a concise usage guide, references the original article, and provides preview links that align with the documented changes to the integration and usage documentation.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch prometheus-ng

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[amotl]

Refreshing this article did not take many efforts. It was merely just copy/paste from a series of others following the same scheme, then slotting in the Docker Compose file and configuration files from the original article. If you agree with those kinds of changes, we'd like to encourage you to find similar spots to modernize easily.

[amotl]

@michaelkremmel: The article Getting Started With Prometheus and CrateDB for Long-Term Storage still uses CrateDB 2.2 and already bears the admonition This article is more than 4 years old. That's fine, but let's stop referring to it hereby.

Now that the canonical documentation page will be modernized, can you prominently refer here at the top of the page instead?

• https://cratedb.com/docs/guide/integrate/prometheus/usage.html

[michaelkremmel]

Thanks for letting me know @amotl. I unpublished the blog post and created a redirect to the documentation. No need to keep old blog posts if they could confuse readers and also LLMs.

[amotl]

Excellent, thanks.

[amotl]

Now, let's review and bring in the updated content (this patch) to make the modernization complete.