OpenTelemetry: Index page. Usage guides about OTel Collector and Telegraf. #334
Conversation
|
Caution Review failedThe pull request is closed. WalkthroughAdds comprehensive OpenTelemetry documentation and examples: a new OTel landing page, Collector and Telegraf integration guides, Docker Compose stacks, Collector and Telegraf configs, a Prometheus adapter config, DDL for a metrics table, and sample Python metric emitters. Updates telemetry index to include an OpenTelemetry integration card. No application logic changes. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor App as OTel SDK App
participant OTEL as OTel Collector
participant PRW as Prometheus Remote Write Exporter
participant Adapter as CrateDB Prometheus Adapter
participant DB as CrateDB
App->>OTEL: Emit metrics (OTLP / Carbon)
OTEL->>PRW: Batch metrics
PRW->>Adapter: POST /write (remote_write)
Adapter->>DB: INSERT into testdrive.metrics
DB-->>Adapter: ACK
Adapter-->>PRW: 200 OK
PRW-->>OTEL: Success
note over DB,Adapter: Table partitioned by day__generated
sequenceDiagram
autonumber
actor App as OTel SDK App
participant T as Telegraf (inputs.opentelemetry)
participant DB as CrateDB (outputs.cratedb)
App->>T: OTLP gRPC metrics
T->>DB: INSERT metrics (table_create optional)
DB-->>T: ACK
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (12)
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
opentelemetry
branch
from
7f70c07 to
9bd8063
Compare
amotl
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
|
|
||
| ### Use Python | ||
|
|
||
| Submit metrics using the OpenTelemetry Python SDK. Download the example file |
There was a problem hiding this comment.
| Submit metrics using the OpenTelemetry Python SDK. Download the example file | |
| To submit metrics using the OpenTelemetry Python SDK, download the example file |
There was a problem hiding this comment.
Thank you. Improved with 6b11d8a.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
docs/integrate/opentelemetry/collector/tutorial.md (2)
74-79: Make “Option” sections headings; keep OTLP protocol explicit
- Resolve MD036/MD053 by using headings and the existing [uv] link.
- Keep port 4317 (gRPC) or set protocol explicitly if switching to HTTP/4318.
-**Option 1: Using uv (recommended)** +#### Option 1: Using [uv] (recommended) ```shell -export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 +export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 +# (optional) make protocol explicit for clarity +export OTEL_EXPORTER_OTLP_PROTOCOL=grpc export OTEL_SERVICE_NAME=app uv run --with=opentelemetry-distro --with=opentelemetry-exporter-otlp opentelemetry-instrument python example.py-Option 2: Using pip
+#### Option 2: Using pip
Install dependencies:pip install opentelemetry-distro opentelemetry-exporter-otlpThen run the example:
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 +export OTEL_EXPORTER_OTLP_PROTOCOL=grpc +export OTEL_SERVICE_NAME=app opentelemetry-instrument --service_name=app python example.pyNotes: - OTLP default ports: 4317=gRPC, 4318=HTTP. ([opentelemetry.io](https://opentelemetry.io/docs/specs/otlp/?utm_source=openai)) - Python zero‑code defaults to OTLP exporter; docs describe gRPC unless protocol is set to http/protobuf. ([opentelemetry.io](https://opentelemetry.io/docs/zero-code/python/configuration/?utm_source=openai)) Also applies to: 81-89 --- `24-28`: **Optional: consider adding -w to nc alias** You can bake a small timeout into the nc alias to avoid indefinite waits. ```diff -alias nc="docker run --rm -i --network=cratedb-demo docker.io/toolbelt/netcat:2025-08-23" +alias nc="docker run --rm -i --network=cratedb-demo docker.io/toolbelt/netcat:2025-08-23 -w 2"Also applies to: 34-36, 40-45
docs/integrate/opentelemetry/telegraf/tutorial.md (1)
62-67: Fix markdown lint; add OTLP env for Option 2; (optionally) make protocol explicit
- Convert emphasized “Option” lines to headings and reference [uv].
- Set endpoint/service in Option 2 for parity.
- If you stick with gRPC, make protocol explicit (grpc) to avoid confusion with HTTP/4318.
-**Option 1: Using uv (recommended)** +#### Option 1: Using [uv] (recommended) ```shell export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 +export OTEL_EXPORTER_OTLP_PROTOCOL=grpc export OTEL_SERVICE_NAME=app uv run --with=opentelemetry-distro --with=opentelemetry-exporter-otlp opentelemetry-instrument python example.py-Option 2: Using pip
+#### Option 2: Using pip
Install dependencies:pip install opentelemetry-distro opentelemetry-exporter-otlpThen run the example:
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 +export OTEL_EXPORTER_OTLP_PROTOCOL=grpc +export OTEL_SERVICE_NAME=app opentelemetry-instrument --service_name=app python example.py- OTLP default ports: 4317=gRPC, 4318=HTTP. ([opentelemetry.io](https://opentelemetry.io/docs/specs/otlp/?utm_source=openai)) - Python agent docs show gRPC unless protocol overridden. ([opentelemetry.io](https://opentelemetry.io/docs/zero-code/python/configuration/?utm_source=openai)) Also applies to: 69-77 </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 d08c29c232a2e6acc4db7187d1d8e79e804a44c8 and 6b11d8a88bcb50cfe4fa5fd24f96d643753c5dcb. </details> <details> <summary>📒 Files selected for processing (2)</summary> * `docs/integrate/opentelemetry/collector/tutorial.md` (1 hunks) * `docs/integrate/opentelemetry/telegraf/tutorial.md` (1 hunks) </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🧠 Learnings (5)</summary> <details> <summary>📚 Learning: 2025-08-12T21:57:26.343Z</summary>Learnt from: amotl
PR: #247
File: docs/integrate/mqtt/learn.md:38-46
Timestamp: 2025-08-12T21:57:26.343Z
Learning: Docker Desktop for Mac supports --network=host networking and works well with the commands in the CrateDB MQTT integration tutorial. The user amotl confirmed this works correctly on their macOS installation with Docker Desktop installed via brew.**Applied to files:** - `docs/integrate/opentelemetry/collector/tutorial.md` </details> <details> <summary>📚 Learning: 2025-08-12T21:59:18.870Z</summary>Learnt from: amotl
PR: #247
File: docs/integrate/mqtt/learn.md:38-46
Timestamp: 2025-08-12T21:59:18.870Z
Learning: Docker Desktop host networking on Windows (even in version 4.34+) has significant limitations: Linux containers only, Layer 4 protocols only, cannot bind to host NIC IPs, potential listener scaling issues (~18 concurrent ports), and various WSL2 compatibility problems. For tutorials, explicit port mapping with bridge networks is more reliable than --network=host on Windows.**Applied to files:** - `docs/integrate/opentelemetry/collector/tutorial.md` </details> <details> <summary>📚 Learning: 2025-08-12T21:59:18.870Z</summary>Learnt from: amotl
PR: #247
File: docs/integrate/mqtt/learn.md:38-46
Timestamp: 2025-08-12T21:59:18.870Z
Learning: For Windows Docker command aliases, PowerShell functions with args are recommended over Set-Alias for commands with arguments. Command Prompt uses doskey with $* for argument forwarding. Both require platform-specific setup (PowerShell profile or doskey batch file with registry AutoRun).**Applied to files:** - `docs/integrate/opentelemetry/collector/tutorial.md` - `docs/integrate/opentelemetry/telegraf/tutorial.md` </details> <details> <summary>📚 Learning: 2025-09-22T14:29:08.606Z</summary>Learnt from: amotl
PR: #334
File: docs/integrate/opentelemetry/telegraf/tutorial.md:64-65
Timestamp: 2025-09-22T14:29:08.606Z
Learning: The opentelemetry-instrument command uses --service_name (with underscore) flag, not --service-name (with hyphen), as confirmed by the actual command's --help output.**Applied to files:** - `docs/integrate/opentelemetry/telegraf/tutorial.md` </details> <details> <summary>📚 Learning: 2025-09-22T14:29:08.606Z</summary>Learnt from: amotl
PR: #334
File: docs/integrate/opentelemetry/telegraf/tutorial.md:64-65
Timestamp: 2025-09-22T14:29:08.606Z
Learning: The opentelemetry-instrument command uses --service_name (with underscore) flag, not --service-name (with hyphen), as confirmed by official OpenTelemetry documentation and the --help output.**Applied to files:** - `docs/integrate/opentelemetry/telegraf/tutorial.md` </details> </details><details> <summary>🪛 markdownlint-cli2 (0.18.1)</summary> <details> <summary>docs/integrate/opentelemetry/collector/tutorial.md</summary> 62-62: Emphasis used instead of a heading (MD036, no-emphasis-as-heading) --- 108-108: Link and image reference definitions should be needed Unused link or image reference definition: "uv" (MD053, link-image-reference-definitions) </details> <details> <summary>docs/integrate/opentelemetry/telegraf/tutorial.md</summary> 62-62: Emphasis used instead of a heading (MD036, no-emphasis-as-heading) --- 108-108: Link and image reference definitions should be needed Unused link or image reference definition: "uv" (MD053, link-image-reference-definitions) </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 (5)</summary><blockquote> <details> <summary>docs/integrate/opentelemetry/collector/tutorial.md (3)</summary><blockquote> `22-28`: **Good: portable aliases and compose networking** Aliases use docker compose exec and a named network, avoiding host networking pitfalls on macOS/Windows. Looks solid. --- `66-66`: **Fix netcat: drop unsupported -c; add timeout** Many nc builds don’t support -c. Use service DNS and add a short timeout to prevent hangs. ```diff -printf "temperature;job=app 42.42 1758486061\nhumidity;job=app 84.84 1758486061" | nc -c otelcol 2003 +printf "temperature;job=app 42.42 1758486061\nhumidity;job=app 84.84 1758486061" | nc -w 2 otelcol 2003
52-58: Resolved — OTLP ports are exposed on the host
otelcol.yaml binds OTLP receivers to 0.0.0.0:4317 and 0.0.0.0:4318, and compose.yaml maps "4317:4317" and "4318:4318".docs/integrate/opentelemetry/telegraf/tutorial.md (2)
21-26: Good: unified crash helpers across OSesPortable compose exec shortcuts with proper arg forwarding. Nice.
Also applies to: 29-33, 37-41
51-53: Telegraf OTLP (port 4317) is configured and exposed.inputs.opentelemetry present; service_address is commented (defaults to 0.0.0.0:4317) — docs/integrate/opentelemetry/telegraf/telegraf.conf (lines 3–6). compose maps "4317:4317/tcp" for telegraf — docs/integrate/opentelemetry/telegraf/compose.yaml (lines 16–19).
amotl
changed the title
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/integrate/opentelemetry/telegraf/usage.md (1)
4-6: Tighten to active voiceSmall microcopy tweak.
Apply:
-This how-to guide walks you through configuring [Telegraf] to receive -[OpenTelemetry] [metrics] and store them into CrateDB. +This guide shows you how to configure [Telegraf] to receive [OpenTelemetry] [metrics] and store them in CrateDB.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/integrate/opentelemetry/collector/usage.md(1 hunks)docs/integrate/opentelemetry/index.md(1 hunks)docs/integrate/opentelemetry/telegraf/usage.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/integrate/opentelemetry/index.md
🧰 Additional context used
🧠 Learnings (3)
📚 Learning: 2025-08-12T21:57:26.343Z
Learnt from: amotl
PR: crate/cratedb-guide#247
File: docs/integrate/mqtt/learn.md:38-46
Timestamp: 2025-08-12T21:57:26.343Z
Learning: Docker Desktop for Mac supports --network=host networking and works well with the commands in the CrateDB MQTT integration tutorial. The user amotl confirmed this works correctly on their macOS installation with Docker Desktop installed via brew.
Applied to files:
docs/integrate/opentelemetry/collector/usage.md
📚 Learning: 2025-08-12T21:59:18.870Z
Learnt from: amotl
PR: crate/cratedb-guide#247
File: docs/integrate/mqtt/learn.md:38-46
Timestamp: 2025-08-12T21:59:18.870Z
Learning: Docker Desktop host networking on Windows (even in version 4.34+) has significant limitations: Linux containers only, Layer 4 protocols only, cannot bind to host NIC IPs, potential listener scaling issues (~18 concurrent ports), and various WSL2 compatibility problems. For tutorials, explicit port mapping with bridge networks is more reliable than --network=host on Windows.
Applied to files:
docs/integrate/opentelemetry/collector/usage.md
📚 Learning: 2025-08-12T21:59:18.870Z
Learnt from: amotl
PR: crate/cratedb-guide#247
File: docs/integrate/mqtt/learn.md:38-46
Timestamp: 2025-08-12T21:59:18.870Z
Learning: For Windows Docker command aliases, PowerShell functions with args are recommended over Set-Alias for commands with arguments. Command Prompt uses doskey with $* for argument forwarding. Both require platform-specific setup (PowerShell profile or doskey batch file with registry AutoRun).
Applied to files:
docs/integrate/opentelemetry/collector/usage.mddocs/integrate/opentelemetry/telegraf/usage.md
🪛 markdownlint-cli2 (0.18.1)
docs/integrate/opentelemetry/collector/usage.md
74-74: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
125-125: Link and image reference definitions should be needed
Unused link or image reference definition: "uv"
(MD053, link-image-reference-definitions)
docs/integrate/opentelemetry/telegraf/usage.md
62-62: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
108-108: Link and image reference definitions should be needed
Unused link or image reference definition: "uv"
(MD053, link-image-reference-definitions)
⏰ 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 (2)
docs/integrate/opentelemetry/collector/usage.md (1)
74-79: Use OTLP HTTP (4318) and make “Option” headings proper; add explicit protocol and parity for Option 2Align with OTLP HTTP defaults and fix markdownlint MD036/MD053 by turning emphasis into headings and referencing [uv]. Also set protocol explicitly.
Apply:
-**Option 1: Using uv (recommended)** +#### Option 1: Using [uv] (recommended) ```shell -export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 +export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf export OTEL_SERVICE_NAME=app uv run --with=opentelemetry-distro --with=opentelemetry-exporter-otlp opentelemetry-instrument python example.py-Option 2: Using pip
+#### Option 2: Using pip
Install dependencies:pip install opentelemetry-distro opentelemetry-exporter-otlpThen run the example:
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_SERVICE_NAME=app opentelemetry-instrument --service_name=app python example.pyPlease confirm the collector config exposes OTLP HTTP on 4318 (as in otelcol.yaml). If you intentionally use gRPC (4317), set OTEL_EXPORTER_OTLP_PROTOCOL=grpc and adjust ports accordingly. Also applies to: 81-89 </blockquote></details> <details> <summary>docs/integrate/opentelemetry/telegraf/usage.md (1)</summary><blockquote> `62-67`: **Align docs with telegraf: keep OTLP gRPC (4317).** telegraf.conf and compose.yaml use the OTLP gRPC listener on 4317. Update docs/integrate/opentelemetry/telegraf/usage.md: - Change headings to "#### Option 1: Using [uv] (recommended)" and "#### Option 2: Using pip". - For both options add these envs: export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 export OTEL_EXPORTER_OTLP_PROTOCOL=grpc export OTEL_SERVICE_NAME=app If you prefer OTLP HTTP (4318), change telegraf.conf/compose.yaml to enable 4318 first; otherwise switching the docs to 4318 is inconsistent with the repository. > Likely an incorrect or invalid review comment. </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
| printf "temperature;job=app 42.42 1758486061\nhumidity;job=app 84.84 1758486061" | nc -c otelcol 2003 | ||
| ``` |
There was a problem hiding this comment.
Fix netcat option: use -N (or -q 0) instead of -c
Most nc variants don’t support -c here; the command may hang or error. Prefer -N (OpenBSD) or fallback to -q 0.
Apply:
-printf "temperature;job=app 42.42 1758486061\nhumidity;job=app 84.84 1758486061" | nc -c otelcol 2003
+printf "temperature;job=app 42.42 1758486061\nhumidity;job=app 84.84 1758486061" | nc -N otelcol 2003
+# If -N is unsupported in your nc, use:
+# printf "...same payload..." | nc -q 0 otelcol 2003📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| printf "temperature;job=app 42.42 1758486061\nhumidity;job=app 84.84 1758486061" | nc -c otelcol 2003 | |
| ``` | |
| printf "temperature;job=app 42.42 1758486061\nhumidity;job=app 84.84 1758486061" | nc -N otelcol 2003 | |
| # If -N is unsupported in your nc, use: | |
| # printf "temperature;job=app 42.42 1758486061\nhumidity;job=app 84.84 1758486061" | nc -q 0 otelcol 2003 |
🤖 Prompt for AI Agents
In docs/integrate/opentelemetry/collector/usage.md around lines 66 to 67, the
netcat example uses the -c option which many nc implementations don't support
and can hang; update the command to use -N (OpenBSD netcat) or use -q 0 as a
portable fallback (e.g., prefer -N, or if not available use -q 0) so the
connection closes after sending the data.
Line continuations are not compatible across operating systems or shell environments (Unix vs. PowerShell vs. DOS). This also has been learned and suggested by CodeRabbit now. Thanks.
amotl
force-pushed
the
opentelemetry
branch
from
12b2e14 to
da2f061
Compare
2 participants
About
In order to expand the Ingest / Telemetry section, the new subsection about the venerable OpenTelemetry accompanies subsections about integrations with Prometheus, rsyslog, and Telegraf.
Preview
References
Trivia
@coderabbitai: Please review and convert to active voice.
/cc @karynzv, @hammerhead, @WalBeh, @seut