Integrate/Telegraf: Add micro tutorial. Improve layout on index page. #267
Conversation
|
Warning Rate limit exceeded@amotl has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 14 minutes and 41 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (2)
WalkthroughAdds a new Telegraf tutorial and restructures the Telegraf integration index into a grid/card layout, splitting Overview items, inserting an architecture diagram item, replacing the Learn link with two cards (tutorial and blog), adding a toctree for the tutorial, and updating the example Telegraf output config. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor User
participant Docker
participant CrateDB
participant Telegraf
participant CLI as crash CLI
Note over User,Docker: Setup & deploy
User->>Docker: create cratedb-demo network & start CrateDB container
Docker->>CrateDB: run CrateDB
Note over User,Telegraf: Configure & start Telegraf
User->>Telegraf: generate config (inputs + output filter cratedb)
Telegraf->>CrateDB: write metrics (table, table_create, key_separator)
Note over Telegraf,CrateDB: flush_interval determines timing
Note over User,CLI: Verify ingestion
User->>CLI: query `doc.metrics` via crash
CLI->>CrateDB: execute query
CrateDB-->>CLI: return rows
CLI-->>User: show results
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related issues
Suggested labels
Suggested reviewers
Poem
✨ Finishing Touches🧪 Generate unit tests
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (8)
docs/integrate/telegraf/tutorial.md (6)
1-3: Adopt the documented “-learn” anchor naming convention for tutorialsPer previous restructuring, tutorial pages use the “-learn” suffix (e.g., azure-functions-learn). Consider renaming the anchor to keep anchors predictable across integrations.
Apply this minimal change here:
-(telegraf-tutorial)= +(telegraf-learn)= # Load data into CrateDB using Telegraf…and update inbound refs (see index.md suggestion below).
59-63: Pin container image versions for reproducibilityUsing floating tags can break the tutorial when upstream images change defaults. Recommend pinning explicit versions (and optionally
--pull=alwaysfor the config-generation step).Example:
-docker run --rm docker.io/telegraf \ +docker run --rm --pull=always docker.io/telegraf:<version> \ --input-filter cpu \ --output-filter cratedb \ config > telegraf.confLikewise consider pinning
docker.io/crate:<version>above and the Telegraf runtime image below.
20-23: Consider lowering the default heap or mention adjustability
CRATE_HEAP_SIZE=2gmay exceed available RAM on small laptops/CI. Either reduce to1gor add a short note that users should adjust to their environment.
41-45: Clarify persistence for Windows Command promptYou advise persisting for Linux/macOS and PowerShell, but not for cmd.exe. Add a note that
doskeyis session-scoped and how to persist via Autorun or a startup script if desired.
4-7: Tighten phrasing“agent/broker” and “system metrics measurement values” read awkwardly. Consider simplifying to “agent” and “system metrics.”
Example:
-The tutorial will walk you through starting the [Telegraf] agent/broker -and CrateDB, and configuring Telegraf to submit system metrics measurement -values to CrateDB. +This tutorial walks you through starting the [Telegraf] agent and CrateDB, +then configuring Telegraf to submit system metrics to CrateDB.
65-71: Explicitly configure the target table in Telegraf’s CrateDB outputBy default, if you don’t set
table, the plugin will fall back to each metric’s name (which can vary by version or input), so your verification query (SELECT * FROM doc.metrics;) may break. Please uncomment and pin the table name to"metrics":# Configuration for CrateDB to send metrics to. [[outputs.cratedb]] url = "postgres://crate@cratedb/doc?sslmode=disable" - # table = "metrics" + table = "metrics" # table_create = trueOr, if you’re using
sedas above:sed -i 's!# table = "metrics"!table = "metrics"!' telegraf.confThen update both verification steps (originally at lines 65–71 and again at 84–87) to match:
-crash --hosts cratedb -c "SELECT * FROM doc.metrics;" +crash --hosts cratedb -c "SELECT * FROM doc.metrics LIMIT 5;"If you’d rather do a simple count-based smoke test:
crash --hosts cratedb -c "SELECT count(*) FROM doc.metrics;"docs/integrate/telegraf/index.md (2)
39-41: Avoid hotlinking external images (stability/licenses)Embedding a remote image can break if the URL changes and may have licensing implications. Prefer vendoring the image in the repo or switching to a first-party asset.
51-55: If you adopt the “-learn” anchor, update the card linkAlign the ref with the renamed tutorial anchor for consistency across integrations.
-:::{grid-item-card} Tutorial: Use Telegraf with CrateDB -:link: telegraf-tutorial +:::{grid-item-card} Tutorial: Use Telegraf with CrateDB +:link: telegraf-learn :link-type: ref How to configure Telegraf to submit metrics to CrateDB. :::
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
docs/integrate/telegraf/index.md(2 hunks)docs/integrate/telegraf/tutorial.md(1 hunks)
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
📚 Learning: 2025-08-09T16:19:43.966Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
Applied to files:
docs/integrate/telegraf/tutorial.md
📚 Learning: 2025-08-15T18:56:11.508Z
Learnt from: amotl
PR: crate/cratedb-guide#255
File: docs/integrate/influxdb/tutorial.md:120-123
Timestamp: 2025-08-15T18:56:11.508Z
Learning: In CrateDB integration tutorials, when using `ctk load table` with `--cluster-url="crate://userhost:port/schema/table"`, the verification query should reference the target schema.table combination specified in the cluster URL, not derive it from the source system's naming. For example, if loading from InfluxDB bucket/measurement `testdrive/demo` to CrateDB `doc/testdrive`, the verification query should be `SELECT * FROM doc.testdrive`.
Applied to files:
docs/integrate/telegraf/tutorial.md
🪛 LanguageTool
docs/integrate/telegraf/tutorial.md
[grammar] ~1-~1: There might be a mistake here.
Context: (telegraf-tutorial)= # Load data into CrateDB using Telegraf T...
(QB_NEW_EN)
[grammar] ~4-~4: There might be a mistake here.
Context: ...ugh starting the [Telegraf] agent/broker and CrateDB, and configuring Telegraf to...
(QB_NEW_EN)
[grammar] ~5-~5: There might be a mistake here.
Context: ...raf to submit system metrics measurement values to CrateDB. ## Prerequisites Do...
(QB_NEW_EN)
[grammar] ~29-~29: There might be a mistake here.
Context: ...{tab-set} :::{tab-item} Linux and macOS To make the settings persistent, add the...
(QB_NEW_EN)
[grammar] ~34-~34: There might be a mistake here.
Context: ....io/crate/cratedb-toolkit crash" ``` ::: :::{tab-item} Windows PowerShell To make...
(QB_NEW_EN)
[grammar] ~35-~35: There might be a mistake here.
Context: ...``` ::: :::{tab-item} Windows PowerShell To make the settings persistent, add the...
(QB_NEW_EN)
[grammar] ~40-~40: There might be a mistake here.
Context: ...te/cratedb-toolkit crash @Args } ::: :::{tab-item} Windows Commandshell d...
(QB_NEW_EN)
[style] ~53-~53: Consider replacing this word to strengthen your wording.
Context: ...ng it. Telegraf is a plugin-driven tool and has plugins to collect many different t...
(AND_THAT)
[grammar] ~56-~56: There might be a mistake here.
Context: ... send the collected data to CrateDB, use --output-filter cratedb. ```shell dock...
(QB_NEW_EN)
[grammar] ~65-~65: There might be a mistake here.
Context: ... a pgx/v4 connection string. Configure table_create = true to automatically l...
(QB_NEW_EN)
[grammar] ~66-~66: There might be a mistake here.
Context: ...ly let Telegraf create the metrics table if it doesn't exist. ```shell sed -i 's!...
(QB_NEW_EN)
[grammar] ~81-~81: There might be a mistake here.
Context: ...n CrateDB. To adjust the value, navigate to flush_interval = "10s" in `telegraf...
(QB_NEW_EN)
docs/integrate/telegraf/index.md
[grammar] ~27-~27: There might be a mistake here.
Context: ...Overview ::: ::::{grid} :::{grid-item} - IoT sensors: Collect critical stateful...
(QB_NEW_EN)
[grammar] ~39-~39: There might be a mistake here.
Context: ...k view of your apps. ::: :::{grid-item} 
[grammar] ~40-~40: There might be a mistake here.
Context: ...-Diagram_06.01.2022v1.png){loading=lazy} ::: :::: :::{rubric} Learn ::: ::::{...
(QB_NEW_EN)
[grammar] ~46-~46: There might be a mistake here.
Context: ...ding=lazy} ::: :::: :::{rubric} Learn ::: ::::{grid} :::{grid-item-card} Tut...
(QB_NEW_EN)
[grammar] ~67-~67: There might be a mistake here.
Context: ...a with Grafana. ::: :::: :::{toctree} :maxdepth: 1 :hidden: Tutorial <tutorial...
(QB_NEW_EN)
[grammar] ~68-~68: There might be a mistake here.
Context: ...a. ::: :::: :::{toctree} :maxdepth: 1 :hidden: Tutorial ::: ```{se...
(QB_NEW_EN)
[grammar] ~69-~69: There might be a mistake here.
Context: ...::: :::{toctree} :maxdepth: 1 :hidden: Tutorial ::: ```{seealso} [C...
(QB_NEW_EN)
[grammar] ~70-~70: There might be a mistake here.
Context: ...maxdepth: 1 :hidden: Tutorial ::: ```{seealso} [CrateDB and Telegraf]...
(QB_NEW_EN)
🔇 Additional comments (2)
docs/integrate/telegraf/index.md (2)
67-71: Toctree looks goodHidden toctree targets the local tutorial file, keeping sidebar navigation coherent. No changes needed.
25-44: Ensure the sphinx-design extension is enabled for grid directivesI did not find any explicit reference to
sphinx_designindocs/conf.py, and the initialextensionslist is imported from the parent theme (crate.theme.rtd.conf.cratedb_guide). Please verify that this theme includes thesphinx-designextension. If it does not, you’ll need to enable it locally by adding:# In docs/conf.py, after importing the parent theme’s config: if "sphinx_design" not in extensions: extensions += ["sphinx_design"]This ensures the
gridandgrid-itemdirectives build correctly.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/integrate/telegraf/tutorial.md (1)
71-84: Split Linux vs macOS for sed; BSD sed needs a different -i form.The current “Linux and macOS” block will fail on macOS because BSD sed requires
-i ''. Also, consider setting the table name explicitly to avoid relying on implicit defaults.Apply this diff to split tabs and add an explicit table setting:
-:::{tab-item} Linux and macOS -```shell -sed -i 's!postgres://user:password@localhost/schema?sslmode=disable!postgres://crate@cratedb/doc?sslmode=disable!g' telegraf.conf -sed -i 's!# table_create = false!table_create = true!' telegraf.conf -``` -::: +:::{tab-item} Linux +```shell +sed -i 's!postgres://user:password@localhost/schema?sslmode=disable!postgres://crate@cratedb/doc?sslmode=disable!g' telegraf.conf +sed -i 's!# table_create = false!table_create = true!' telegraf.conf +# (Optional) Set the table name explicitly +sed -i 's!# table = "metrics"!table = "metrics"!' telegraf.conf +``` +::: +:::{tab-item} macOS +```shell +sed -i '' 's!postgres://user:password@localhost/schema?sslmode=disable!postgres://crate@cratedb/doc?sslmode=disable!g' telegraf.conf +sed -i '' 's!# table_create = false!table_create = true!' telegraf.conf +# (Optional) Set the table name explicitly +sed -i '' 's!# table = "metrics"!table = "metrics"!' telegraf.conf +``` +::: :::{tab-item} Windows PowerShell ```powershell (Get-Content telegraf.conf) -replace 'postgres://user:password@localhost/schema\?sslmode=disable','postgres://crate@cratedb/doc?sslmode=disable' | ForEach-Object { $_ -replace '# table_create = false','table_create = true' } | Set-Content telegraf.conf:::
</blockquote></details> </blockquote></details> <details> <summary>🧹 Nitpick comments (4)</summary><blockquote> <details> <summary>docs/integrate/telegraf/tutorial.md (3)</summary><blockquote> `86-110`: **Good OS‑specific run commands; just fix CMD code fence language.** The Windows Command block is CMD syntax, not generic shell. Change the fence for accurate highlighting and linters. ```diff -:::{tab-item} Windows Command -```shell +:::{tab-item} Windows Command +```cmd docker run --name=telegraf --rm -it --network=cratedb-demo ^ --volume "%cd%\telegraf.conf:/etc/telegraf/telegraf.conf" ^ docker.io/telegraf:::
--- `117-120`: **Make the crash host explicit to avoid DNS/scheme ambiguity.** Some environments won’t resolve bare hostnames or will default to HTTPS. Use the full URL and default CrateDB port. ```diff -crash --hosts cratedb -c "SELECT * FROM doc.metrics LIMIT 5;" +crash --hosts http://cratedb:4200 -c "SELECT * FROM doc.metrics LIMIT 5;"
9-11: If mentioning Podman, provide equivalents or drop the claim.Right now only Docker commands are provided. Either add minimal Podman variants (network/create/run) or rephrase to “We use Docker. Podman can be used as a drop‑in replacement.”
If you want, I can add a compact Podman tab with
podman network create,podman run --name cratedb ..., and volume syntax notes (SELinux:Z).docs/integrate/telegraf/index.md (1)
54-69: Align connection host with the tutorial or document both options.Here the snippet uses localhost, while the tutorial runs Telegraf in Docker with CrateDB on the same user‑defined network (host
cratedb). This mismatch may confuse users copying snippets between pages.Option A — switch to
cratedbto mirror the tutorial:- url = "postgres://crate@localhost/doc?sslmode=disable" + # If Telegraf runs in the same Docker network as CrateDB: + url = "postgres://crate@cratedb/doc?sslmode=disable"Option B — document both:
- url = "postgres://crate@localhost/doc?sslmode=disable" + # Docker network: + # url = "postgres://crate@cratedb/doc?sslmode=disable" + # Host (Telegraf on the host talking to mapped ports): + url = "postgres://crate@localhost/doc?sslmode=disable"
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
docs/integrate/telegraf/index.md(2 hunks)docs/integrate/telegraf/tutorial.md(1 hunks)
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2025-08-09T16:19:43.966Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
Applied to files:
docs/integrate/telegraf/tutorial.md
📚 Learning: 2025-08-15T18:56:11.508Z
Learnt from: amotl
PR: crate/cratedb-guide#255
File: docs/integrate/influxdb/tutorial.md:120-123
Timestamp: 2025-08-15T18:56:11.508Z
Learning: In CrateDB integration tutorials, when using `ctk load table` with `--cluster-url="crate://userhost:port/schema/table"`, the verification query should reference the target schema.table combination specified in the cluster URL, not derive it from the source system's naming. For example, if loading from InfluxDB bucket/measurement `testdrive/demo` to CrateDB `doc/testdrive`, the verification query should be `SELECT * FROM doc.testdrive`.
Applied to files:
docs/integrate/telegraf/tutorial.md
🪛 LanguageTool
docs/integrate/telegraf/index.md
[grammar] ~27-~27: There might be a mistake here.
Context: ...Overview ::: ::::{grid} :::{grid-item} - IoT sensors: Collect critical stateful...
(QB_NEW_EN)
[grammar] ~39-~39: There might be a mistake here.
Context: ...k view of your apps. ::: :::{grid-item} 
[grammar] ~40-~40: There might be a mistake here.
Context: ...-Diagram_06.01.2022v1.png){loading=lazy} ::: :::: :::{rubric} Synopsis ::: Te...
(QB_NEW_EN)
[grammar] ~46-~46: There might be a mistake here.
Context: ...g=lazy} ::: :::: :::{rubric} Synopsis ::: Telegraf output plugin configuratio...
(QB_NEW_EN)
[grammar] ~72-~72: There might be a mistake here.
Context: ...separator = "" ``` :::{rubric} Learn ::: ::::{grid} :::{grid-item-card} Tut...
(QB_NEW_EN)
[grammar] ~93-~93: There might be a mistake here.
Context: ...a with Grafana. ::: :::: :::{toctree} :maxdepth: 1 :hidden: Tutorial <tutorial...
(QB_NEW_EN)
[grammar] ~94-~94: There might be a mistake here.
Context: ...a. ::: :::: :::{toctree} :maxdepth: 1 :hidden: Tutorial ::: ```{se...
(QB_NEW_EN)
[grammar] ~95-~95: There might be a mistake here.
Context: ...::: :::{toctree} :maxdepth: 1 :hidden: Tutorial ::: ```{seealso} [C...
(QB_NEW_EN)
[grammar] ~96-~96: There might be a mistake here.
Context: ...maxdepth: 1 :hidden: Tutorial ::: ```{seealso} [CrateDB and Telegraf]...
(QB_NEW_EN)
docs/integrate/telegraf/tutorial.md
[grammar] ~1-~1: There might be a mistake here.
Context: (telegraf-tutorial)= # Load data into CrateDB using Telegraf T...
(QB_NEW_EN)
[grammar] ~4-~4: There might be a mistake here.
Context: ...arting the [Telegraf] agent and CrateDB, then configuring Telegraf to submit syst...
(QB_NEW_EN)
[grammar] ~28-~28: There might be a mistake here.
Context: ...{tab-set} :::{tab-item} Linux and macOS To make the settings persistent, add the...
(QB_NEW_EN)
[grammar] ~34-~34: There might be a mistake here.
Context: ...cratedb-demo docker.io/telegraf" ``` ::: :::{tab-item} Windows PowerShell To make...
(QB_NEW_EN)
[grammar] ~35-~35: There might be a mistake here.
Context: ...``` ::: :::{tab-item} Windows PowerShell To make the settings persistent, add the...
(QB_NEW_EN)
[grammar] ~41-~41: There might be a mistake here.
Context: ...-demo docker.io/telegraf @Args } ::: :::{tab-item} Windows Commandshell d...
(QB_NEW_EN)
[style] ~55-~55: Consider replacing this word to strengthen your wording.
Context: ...ng it. Telegraf is a plugin-driven tool and has plugins to collect many different t...
(AND_THAT)
[grammar] ~58-~58: There might be a mistake here.
Context: ... send the collected data to CrateDB, use --output-filter cratedb. ```shell tele...
(QB_NEW_EN)
[grammar] ~70-~70: There might be a mistake here.
Context: ...table if it doesn't exist. ::::{tab-set} :::{tab-item} Linux and macOS ```shell s...
(QB_NEW_EN)
[grammar] ~76-~76: There might be a mistake here.
Context: ...le_create = true!' telegraf.conf ::: :::{tab-item} Windows PowerShellpowe...
(QB_NEW_EN)
[grammar] ~83-~83: There might be a mistake here.
Context: ... } | Set-Content telegraf.conf ``` ::: :::: Start Telegraf. ::::{tab-set} :::...
(QB_NEW_EN)
[grammar] ~88-~88: There might be a mistake here.
Context: ...::: :::: Start Telegraf. ::::{tab-set} :::{tab-item} Linux and macOS ```shell d...
(QB_NEW_EN)
[grammar] ~95-~95: There might be a mistake here.
Context: ...graf.conf \ docker.io/telegraf ::: :::{tab-item} Windows PowerShellpowe...
(QB_NEW_EN)
[grammar] ~102-~102: There might be a mistake here.
Context: ...raf.conf" ` docker.io/telegraf ::: :::{tab-item} Windows Commandshell d...
(QB_NEW_EN)
[grammar] ~109-~109: There might be a mistake here.
Context: ...raf.conf" ^ docker.io/telegraf ``` ::: :::: After 10 seconds, which is the de...
(QB_NEW_EN)
[grammar] ~114-~114: There might be a mistake here.
Context: ...n CrateDB. To adjust the value, navigate to flush_interval = "10s" in `telegraf...
(QB_NEW_EN)
⏰ 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
🔇 Additional comments (4)
docs/integrate/telegraf/tutorial.md (1)
28-46: Nice cross‑platform launcher shortcuts; clear and consistent.The alias/function/doskey trio for crash/telegraf is tidy and mirrors prior guide patterns. This should reduce friction for users across shells.
docs/integrate/telegraf/index.md (3)
25-44: Overview grid layout reads better; good use of sphinx‑design.The two‑column split with the architecture diagram works well and keeps the page scannable.
93-97: Confirm anchor/path naming aligns with the guide’s convention.Earlier restructurings use “-learn” for tutorial anchors/files (e.g., azure-functions-learn). Here the file is “tutorial.md” and the anchor is
telegraf-tutorial. If this is the new standard, all good—otherwise consider renaming for consistency.Using prior learning: you noted the “-learn” suffix pattern across integration tutorials. Do we keep that, or is “tutorial” the new convention going forward?
61-69: Nice to see table/table_create/key_separator called out explicitly.Calling out these options reduces guesswork for users migrating from other Telegraf outputs.
amotl
added
sanding-1200
Let's defer this to a future iteration to have an immediate improvement available, while a later edit can add this easily after validating it? RationaleOnly a few tutorials from our pen made a start to consider cloud details the other day. While this was meant as a blueprint how to start documenting relevant details, we observe very little user testing on those aspects in general, nor contributions in the same area, despite asking for support so often. Because other patches also don't take a particular focus, ... we'd suggest to merge early, and do relevant improvements on behalf of future iterations, sweepingly across all the tutorials, possibly on behalf of a special initiative. Contributions are very much welcome. 🍀 Thoughts
In general, the documentation shouldn't exclude specific audiences from experiencing a successful application of CrateDB within their relevant use case or problem they are solving, so it needs to strike the balance between Cloud use and standalone use. Because CrateDB isn't so popular on its own, we can't afford to leave non-Cloud users behind. Because of unilateral product policies of the past, we are only slowly getting back on track in increasing interests about CrateDB within its native habitats again 1. Through relevant network effects, this will also increase interest in CrateDB Cloud products. It would be sad if we would cut off those delicate little plants of increased attention again, only because they don't fit into a hypothetic user journey. Evaluating products on developer's workstations on hands-on data is a well-known and established user journey to evaluate new technologies, because users are absolutely safe that the data entrusted by their clients will never leave their premises. In this spirit, directing users to use CrateDB Cloud, will significantly decrease abilities of those audiences, which usually just don't have the time to do significant research, but expect to find relevant information on their fingertips, like the bunch of requests shared above demonstrate. CrateDB Cloud can be an option for some people as the preferred way for production hosting, because then it's our responsibility not to make it crash under load, but it's certainly not applicable for technology evaluations of the usual kind within existing software infrastructures. In this particular case about Telegraf, where CrateDB would fit into the metrics store market landscape well, like others, we think it is mostly on-premise datacenter use where CrateDB could play out its strengths in this regard, as demonstrated through relevant conversations. It would be sad again to introduce category failures into our product policies again that would now even condensate on the documentation with a wrong bias, just because there is no collective awareness about relevant details yet, that there is no "one fits all" solution, also not about creating homogenity on the documentation while reality is different. Footnotes
|
|
I agree we should cater to both audiences, but as we decided to have a primary focus initially on Cloud users for getting started easily, we should add instructions for Cloud for those ingestion methods we currently have in focus as highly important. Incrementally improving seems a better approach to me that waiting for a big overhaul across the board. |
|
Hi. Everything works which draws attention to the problem. Contributions are always welcome. I don't think we should block the patch though. |
| ::::{tab-set} | ||
| :::{tab-item} Linux and macOS | ||
| ```shell | ||
| sed -i 's!postgres://user:password@localhost/schema?sslmode=disable!postgres://crate@cratedb/doc?sslmode=disable!g' telegraf.conf |
There was a problem hiding this comment.
BSD sed and GNU sed do not have the same semantics for option -i. I suggest to use -i '' to cover both cases.
There was a problem hiding this comment.
@coderabbiai already suggested the same, thanks!
In docs/integrate/telegraf/tutorial.md, we recommend to...
71-84: Split Linux vs macOS for sed; BSD sed needs a different -i form.The current “Linux and macOS” block will fail on macOS because BSD sed requires
-i ''. Also, consider setting the table name explicitly to avoid relying on implicit defaults.
3 participants
About
Using Telegraf and CrateDB to collect and store system metrics, all based on using Docker for executing any command.
Preview
References
/cc @hammerhead