Skip to content

Commit 9bd8063

Browse files
amotlamotl
committed
OpenTelemetry: Telegraf tutorial
1 parent 66fb71a commit 9bd8063

File tree

5 files changed

+201
-1
lines changed

5 files changed

+201
-1
lines changed

‎docs/integrate/opentelemetry/index.md‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ applications, allowing for the use of a single standard across different
1919
observability tools.
2020

2121
The [OpenTelemetry Collector] and its [Prometheus Remote Write Exporter] can
22-
be used to submit and store [metrics] data into CrateDB.
22+
be used to submit and store [metrics] data into CrateDB. Alternatively, you
23+
can use [Telegraf].
2324

2425
:::{rubric} Synopsis
2526
:::
@@ -33,6 +34,15 @@ Configure OpenTelemetry Collector to send metrics data to the [CrateDB Prometheu
3334
:lines: 38-43
3435
:::
3536

37+
Configure Telegraf to store OpenTelemetry metrics data into CrateDB.
38+
39+
:::{literalinclude} telegraf/telegraf.conf
40+
:lines: 1-6
41+
:::
42+
:::{literalinclude} telegraf/telegraf.conf
43+
:lines: 27-33
44+
:::
45+
3646

3747
:::{rubric} Learn
3848
:::
@@ -45,13 +55,20 @@ Configure OpenTelemetry Collector to send metrics data to the [CrateDB Prometheu
4555
How to configure OpenTelemetry Collector to submit metrics to CrateDB.
4656
:::
4757

58+
:::{grid-item-card} Tutorial: Use Telegraf and CrateDB
59+
:link: opentelemetry-telegraf-tutorial
60+
:link-type: ref
61+
How to configure Telegraf to submit OpenTelemetry metrics to CrateDB.
62+
:::
63+
4864
::::
4965

5066

5167
:::{toctree}
5268
:maxdepth: 1
5369
:hidden:
5470
Collector Tutorial <collector/tutorial>
71+
Telegraf Tutorial <telegraf/tutorial>
5572
:::
5673

5774

@@ -61,4 +78,5 @@ Collector Tutorial <collector/tutorial>
6178
[OpenTelemetry]: https://opentelemetry.io/docs/what-is-opentelemetry/
6279
[OpenTelemetry Collector]: https://opentelemetry.io/docs/collector/
6380
[Prometheus Remote Write Exporter]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/prometheusremotewriteexporter
81+
[Telegraf]: https://www.influxdata.com/time-series-platform/telegraf/
6482
[traces]: https://opentelemetry.io/docs/concepts/signals/traces/

‎docs/integrate/opentelemetry/telegraf/compose.yaml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Service composition file for Docker Compose or Podman Compose
2+
3+
services:
4+
5+
cratedb:
6+
image: docker.io/crate/crate:latest
7+
ports:
8+
- "4200:4200/tcp"
9+
- "5432:5432/tcp"
10+
healthcheck:
11+
test: ["CMD", "curl", "-f", "http://localhost:4200/"]
12+
interval: 5s
13+
timeout: 30s
14+
retries: 5
15+
16+
telegraf:
17+
image: docker.io/telegraf:latest
18+
ports:
19+
- "4317:4317/tcp" # OTLP gRPC
20+
volumes:
21+
- ./telegraf.conf:/etc/telegraf/telegraf.conf:ro
22+
depends_on:
23+
- cratedb

‎docs/integrate/opentelemetry/telegraf/example.py‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# OpenTelemetry demo application.
2+
from opentelemetry import metrics
3+
4+
5+
def main():
6+
7+
meter = metrics.get_meter("testdrive.meter.name")
8+
temperature = meter.create_gauge("temperature")
9+
humidity = meter.create_gauge("humidity")
10+
11+
temperature.set(42.42)
12+
humidity.set(84.84)
13+
14+
15+
if __name__ == "__main__":
16+
main()

‎docs/integrate/opentelemetry/telegraf/telegraf.conf‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# OpenTelemetry Input Plugin
2+
# https://github.com/influxdata/telegraf/blob/release-1.36/plugins/inputs/opentelemetry/README.md
3+
[[inputs.opentelemetry]]
4+
## Override the default (0.0.0.0:4317) destination OpenTelemetry gRPC service
5+
## address:port
6+
# service_address = "0.0.0.0:4317"
7+
8+
## Override the default (5s) new connection timeout
9+
# timeout = "5s"
10+
11+
## Override the default (prometheus-v1) metrics schema.
12+
## Supports: "prometheus-v1", "prometheus-v2"
13+
## For more information about the alternatives, read the Prometheus input
14+
## plugin notes.
15+
# metrics_schema = "prometheus-v1"
16+
17+
## Optional TLS Config.
18+
## For advanced options: https://github.com/influxdata/telegraf/blob/v1.18.3/docs/TLS.md
19+
##
20+
## Set one or more allowed client CA certificate file names to
21+
## enable mutually authenticated TLS connections.
22+
# tls_allowed_cacerts = ["/etc/telegraf/clientca.pem"]
23+
## Add service certificate and key.
24+
# tls_cert = "/etc/telegraf/cert.pem"
25+
# tls_key = "/etc/telegraf/key.pem"
26+
27+
# CrateDB Output Plugin
28+
# https://github.com/influxdata/telegraf/tree/master/plugins/outputs/cratedb
29+
[[outputs.cratedb]]
30+
## Connection parameters for accessing the database see
31+
## https://pkg.go.dev/github.com/jackc/pgx/v4#ParseConfig
32+
## for available options
33+
url = "postgres://crate:crate@cratedb/doc?sslmode=disable"
34+
35+
## Timeout for all CrateDB queries.
36+
# timeout = "5s"
37+
38+
## Name of the table to store metrics in.
39+
table = "metrics"
40+
41+
## If true, and the metrics table does not exist, create it automatically.
42+
table_create = true
43+
44+
## The character(s) to replace any '.' in an object key with
45+
# key_separator = "_"

‎docs/integrate/opentelemetry/telegraf/tutorial.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
(opentelemetry-telegraf-tutorial)=
2+
# Store OpenTelemetry metrics using Telegraf and CrateDB
3+
4+
This tutorial walks you through configuring [Telegraf] to receive
5+
[OpenTelemetry] [metrics] and store them into CrateDB.
6+
7+
## Prerequisites
8+
9+
Docker is used for running all components. This approach works consistently
10+
across Linux, macOS, and Windows. Alternatively, you can use Podman.
11+
12+
### Commands
13+
14+
Prepare shortcut for {ref}`crate-crash:index` command.
15+
16+
::::{tab-set}
17+
:sync-group: os
18+
19+
:::{tab-item} Linux and macOS
20+
:sync: unix
21+
Add these settings to your shell profile (`~/.profile`) to make them persistent.
22+
```shell
23+
alias crash="docker run --rm -it --network=host crate/crate:latest crash"
24+
```
25+
:::
26+
:::{tab-item} Windows PowerShell
27+
:sync: powershell
28+
Add these settings to your PowerShell profile (`$PROFILE`) to make them persistent.
29+
```powershell
30+
function crash { docker run --rm -i --network=host crate/crate:latest crash @args }
31+
```
32+
:::
33+
:::{tab-item} Windows Command
34+
:sync: dos
35+
```shell
36+
doskey crash=docker run --rm -i --network=host crate/crate:latest crash $*
37+
```
38+
:::
39+
40+
::::
41+
42+
### Services
43+
44+
Save the files {download}`compose.yaml` and {download}`telegraf.conf`
45+
to your machine and start all services using
46+
Docker Compose or Podman Compose.
47+
```shell
48+
docker compose up
49+
```
50+
51+
## Submit data
52+
53+
### Use Python
54+
55+
Use the OTel Python language SDK to submit metrics. To do that,
56+
save the Python OTel example file {download}`example.py` to your machine and
57+
use the `opentelemetry-instrument` program to invoke your Python application.
58+
```shell
59+
opentelemetry-instrument --service_name=app python example.py
60+
```
61+
:::{literalinclude} example.py
62+
:::
63+
The [uv] utility can invoke the demo program including dependencies,
64+
otherwise install them using `pip install opentelemetry-distro opentelemetry-exporter-otlp`
65+
or similarly.
66+
```shell
67+
uv run --with=opentelemetry-distro --with=opentelemetry-exporter-otlp \
68+
opentelemetry-instrument --service_name=app python example.py
69+
```
70+
71+
### Use any language
72+
73+
Use any of the available [OpenTelemetry language APIs & SDKs] for C++, C#/.NET,
74+
Erlang/Elixir, Go, Java, JavaScript, PHP, Python, Ruby, Rust, or Swift.
75+
76+
## Explore data
77+
78+
CrateDB stored the metrics in the designated table, ready for inspection and analysis.
79+
```shell
80+
crash --hosts "http://crate:crate@localhost:4200/" \
81+
-c "SELECT * FROM metrics ORDER BY timestamp LIMIT 5;"
82+
```
83+
```psql
84+
+---------------------+---------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+---------------+
85+
| hash_id | timestamp | name | tags | fields | day |
86+
+---------------------+---------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+---------------+
87+
| 4549776513022193265 | 1758500094846 | temperature | {"host": "2805bf17ee55", "otel_library_name": "testdrive.meter.name", "service_name": "app", "telemetry_auto_version": "0.58b0", "telemetry_sdk_language": "python", "telemetry_sdk_name": "opentelemetry", "telemetry_sdk_version": "1.37.0"} | {"gauge": 42.42} | 1758499200000 |
88+
| -926134856403504308 | 1758500094846 | humidity | {"host": "2805bf17ee55", "otel_library_name": "testdrive.meter.name", "service_name": "app", "telemetry_auto_version": "0.58b0", "telemetry_sdk_language": "python", "telemetry_sdk_name": "opentelemetry", "telemetry_sdk_version": "1.37.0"} | {"gauge": 84.84} | 1758499200000 |
89+
+---------------------+---------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+---------------+
90+
SELECT 2 rows in set (0.049 sec)
91+
```
92+
93+
94+
[metrics]: https://opentelemetry.io/docs/concepts/signals/metrics/
95+
[OpenTelemetry]: https://opentelemetry.io/docs/what-is-opentelemetry/
96+
[OpenTelemetry language APIs & SDKs]: https://opentelemetry.io/docs/languages/
97+
[Telegraf]: https://www.influxdata.com/time-series-platform/telegraf/
98+
[uv]: https://docs.astral.sh/uv/

0 commit comments

Comments
 (0)