Skip to content

Commit 22cbd39

Browse files
paomianpaomian
authored
chore: copy otel collector docs to 0.14 (#1755)
1 parent 50aa9b6 commit 22cbd39

File tree

4 files changed

+308
-58
lines changed
  • i18n/zh/docusaurus-plugin-content-docs/version-0.14
  • versioned_docs/version-0.14

4 files changed

+308
-58
lines changed

‎i18n/zh/docusaurus-plugin-content-docs/version-0.14/greptimecloud/integrations/otlp.md‎

Lines changed: 63 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,10 @@ description: 介绍如何通过 OpenTelemetry Protocol (OTLP) 将指标数据发
1111

1212
要通过 OpenTelemetry SDK 库将 OpenTelemetry 指标发送到 GreptimeDB，请使用以下信息：
1313

14-
* URL: `https://<host>/v1/otlp/v1/metrics`
15-
* Headers:
16-
* `X-Greptime-DB-Name`: `<dbname>`
17-
* `Authorization`: `Basic` 认证，是 `<username>:<password>` 的 Base64 编码字符串。更多信息，请参阅 HTTP API 中的[认证](https://docs.greptime.cn/nightly/user-guide/protocols/http#鉴权)。
14+
- URL: `https://<host>/v1/otlp/v1/metrics`
15+
- Headers:
16+
- `X-Greptime-DB-Name`: `<dbname>`
17+
- `Authorization`: `Basic` 认证，是 `<username>:<password>` 的 Base64 编码字符串。更多信息，请参阅 HTTP API 中的[认证](https://docs.greptime.cn/nightly/user-guide/protocols/http#鉴权)。
1818

1919
由于请求中使用二进制 protobuf 编码的 payload，因此需要使用支持 `HTTP/protobuf` 的包。例如，在 Node.js 中，可以使用 [`exporter-trace-otlp-proto`](https://www.npmjs.com/package/@opentelemetry/exporter-trace-otlp-proto)；在 Go 中，可以使用 [`go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp`](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp)；在 Java 中，可以使用 [`io.opentelemetry:opentelemetry-exporter-otlp`](https://mvnrepository.com/artifact/io.opentelemetry/opentelemetry-exporter-otlp)；在 Python 中，可以使用 [`opentelemetry-exporter-otlp-proto-http`](https://pypi.org/project/opentelemetry-exporter-otlp-proto-http/)。
2020

@@ -24,10 +24,66 @@ description: 介绍如何通过 OpenTelemetry Protocol (OTLP) 将指标数据发
2424

2525
## OpenTelemetry Collector
2626

27-
如果你使用单独的 OTel 收集器，我们推荐更加成熟的 [Grafana
28-
Alloy](https://grafana.com/docs/alloy/latest/)
27+
OpenTelemetry Collector 是 OpenTelemetry 的一个与厂商无关的实现，下面是一个导出到 GreptimeDB 的示例配置。你可以使用 [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) 将指标、日志和追踪数据发送到 GreptimeDB。
2928

30-
一个简单输出到 GreptimeDB 的配置例子：
29+
```yaml
30+
extensions:
31+
basicauth/client:
32+
client_auth:
33+
username: <username>
34+
password: <password>
35+
36+
receivers:
37+
otlp:
38+
protocols:
39+
grpc:
40+
endpoint: 0.0.0.0:4317
41+
http:
42+
endpoint: 0.0.0.0:4318
43+
44+
exporters:
45+
otlphttp/traces:
46+
endpoint: 'https://<host>/v1/otlp'
47+
auth:
48+
authenticator: basicauth/client
49+
headers:
50+
x-greptime-db-name: '<dbname>'
51+
x-greptime-pipeline-name: 'greptime_trace_v1'
52+
otlphttp/logs:
53+
endpoint: 'https://<host>/v1/otlp'
54+
auth:
55+
authenticator: basicauth/client
56+
headers:
57+
x-greptime-db-name: '<dbname>'
58+
# x-greptime-log-table-name: "<pipeline_name>"
59+
60+
otlphttp/metrics:
61+
endpoint: 'https://<host>/v1/otlp'
62+
auth:
63+
authenticator: basicauth/client
64+
headers:
65+
x-greptime-db-name: '<dbname>'
66+
67+
service:
68+
extensions: [basicauth/client]
69+
pipelines:
70+
traces:
71+
receivers: [otlp]
72+
exporters: [otlphttp/traces]
73+
logs:
74+
receivers: [otlp]
75+
exporters: [otlphttp/logs]
76+
metrics:
77+
receivers: [otlp]
78+
exporters: [otlphttp/metrics]
79+
```
80+
81+
82+
## Grafana Alloy
83+
84+
如果你更倾向于使用 [Grafana Alloy](https://grafana.com/docs/alloy/latest/) 的 OpenTelemetry 导出器，可以使用如下配置来发送你的数据。
85+
86+
一个简单的配置示例如下：
3187
3288
```
3389
otelcol.exporter.otlphttp "greptimedb" {

‎i18n/zh/docusaurus-plugin-content-docs/version-0.14/user-guide/ingest-data/for-observability/opentelemetry.md‎

Lines changed: 93 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,10 @@ GreptimeDB 通过原生支持 [OTLP/HTTP](https://opentelemetry.io/docs/specs/ot
2121

2222
使用下面的信息通过 Opentelemetry SDK 库发送 Metrics 到 GreptimeDB：
2323

24-
* URL: `https://<host>/v1/otlp/v1/metrics`
25-
* Headers:
26-
* `X-Greptime-DB-Name`: `<dbname>`
27-
* `Authorization`: `Basic` 认证，是 `<username>:<password>` 的 Base64 编码字符串。更多信息请参考 [鉴权](https://docs.greptime.cn/user-guide/deployments/authentication/static/) 和 [HTTP API](https://docs.greptime.cn/user-guide/protocols/http#authentication)。
24+
- URL: `https://<host>/v1/otlp/v1/metrics`
25+
- Headers:
26+
- `X-Greptime-DB-Name`: `<dbname>`
27+
- `Authorization`: `Basic` 认证，是 `<username>:<password>` 的 Base64 编码字符串。更多信息请参考 [鉴权](https://docs.greptime.cn/user-guide/deployments/authentication/static/) 和 [HTTP API](https://docs.greptime.cn/user-guide/protocols/http#authentication)。
2828

2929
请求中使用 binary protobuf 编码 payload，因此你需要使用支持 `HTTP/protobuf` 的包。例如，在 Node.js 中，可以使用 [`exporter-trace-otlp-proto`](https://www.npmjs.com/package/@opentelemetry/exporter-trace-otlp-proto)；在 Go 中，可以使用 [`go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp`](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp)；在 Java 中，可以使用 [`io.opentelemetry:opentelemetry-exporter-otlp`](https://mvnrepository.com/artifact/io.opentelemetry/opentelemetry-exporter-otlp)；在 Python 中，可以使用 [`opentelemetry-exporter-otlp-proto-http`](https://pypi.org/project/opentelemetry-exporter-otlp-proto-http/)。
3030

@@ -45,12 +45,12 @@ GreptimeDB 通过原生支持 [OTLP/HTTP](https://opentelemetry.io/docs/specs/ot
4545
```ts
4646
const auth = Buffer.from(`${username}:${password}`).toString('base64')
4747
const exporter = new OTLPMetricExporter({
48-
url: `https://${dbHost}/v1/otlp/v1/metrics`,
49-
headers: {
50-
Authorization: `Basic ${auth}`,
51-
"X-Greptime-DB-Name": db,
52-
},
53-
timeoutMillis: 5000,
48+
url: `https://${dbHost}/v1/otlp/v1/metrics`,
49+
headers: {
50+
Authorization: `Basic ${auth}`,
51+
'X-Greptime-DB-Name': db,
52+
},
53+
timeoutMillis: 5000,
5454
})
5555
```
5656

@@ -122,7 +122,7 @@ OTLP 指标数据模型按照下方的规则被映射到 GreptimeDB 数据模型
122122
- 所有的 Attribute，包含 resource 级别、scope 级别和 data_point 级别，都被作为 GreptimeDB 表的 tag 列。
123123
- 数据点的时间戳被作为 GreptimeDB 的时间戳索引，列名 `greptime_timestamp`。
124124
- Gauge/Sum 两种类型的数据点数据被作为 field 列，列名 `greptime_value`。
125-
- Summary 类型的每个 quantile 被作为单独的数据列，列名 `greptime_pxx`，其中 xx 是 quantile 的数据，如 90 / 99 等。
125+
- Summary 类型的每个 quantile 被作为单独的数据列，列名 `greptime_pxx`，其中 xx 是 quantile 的数据，如 90 / 99 等。
126126
- Histogram 和 ExponentialHistogram 暂时未被支持，我们可能在后续版本中推出 Histogram 数据类型来原生支持这两种类型。
127127

128128
## Logs
@@ -133,14 +133,14 @@ GreptimeDB 是能够通过 [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/
133133

134134
要通过 OpenTelemetry SDK 库将 OpenTelemetry 日志发送到 GreptimeDB，请使用以下信息：
135135

136-
* **URL:** `https://<host>/v1/otlp/v1/logs`
137-
* **Headers:**
138-
* `X-Greptime-DB-Name`: `<dbname>`
139-
* `Authorization`: `Basic` 认证，这是一个 Base64 编码的 `<username>:<password>` 字符串。更多信息，请参考 [鉴权](/user-guide/deployments/authentication/static.md) 和 [HTTP API](/user-guide/protocols/http.md#鉴权)。
140-
* `X-Greptime-Log-Table-Name`: `<table_name>`（可选）- 存储日志的表名。如果未提供，默认表名为 `opentelemetry_logs`。
141-
* `X-Greptime-Log-Extract-Keys`: `<extract_keys>`（可选）- 从属性中提取对应 key 的值到表的顶级字段。key 应以逗号（`,`）分隔。例如，`key1,key2,key3` 将从属性中提取 `key1`、`key2` 和 `key3`，并将它们提升到日志的顶层，设置为标签。如果提取的字段类型是数组、浮点数或对象，将返回错误。如果提供了 pipeline name，此设置将被忽略。
142-
* `X-Greptime-Log-Pipeline-Name`: `<pipeline_name>`（可选）- 处理日志的 pipeline 名称。如果未提供，将使用 `X-Greptime-Log-Extract-Keys` 来处理日志。
143-
* `X-Greptime-Log-Pipeline-Version`: `<pipeline_version>`（可选）- 处理日志的 pipeline 的版本。如果未提供，将使用 pipeline 的最新版本。
136+
- **URL:** `https://<host>/v1/otlp/v1/logs`
137+
- **Headers:**
138+
- `X-Greptime-DB-Name`: `<dbname>`
139+
- `Authorization`: `Basic` 认证，这是一个 Base64 编码的 `<username>:<password>` 字符串。更多信息，请参考 [鉴权](/user-guide/deployments/authentication/static.md) 和 [HTTP API](/user-guide/protocols/http.md#鉴权)。
140+
- `X-Greptime-Log-Table-Name`: `<table_name>`（可选）- 存储日志的表名。如果未提供，默认表名为 `opentelemetry_logs`。
141+
- `X-Greptime-Log-Extract-Keys`: `<extract_keys>`（可选）- 从属性中提取对应 key 的值到表的顶级字段。key 应以逗号（`,`）分隔。例如，`key1,key2,key3` 将从属性中提取 `key1`、`key2` 和 `key3`，并将它们提升到日志的顶层，设置为标签。如果提取的字段类型是数组、浮点数或对象，将返回错误。如果提供了 pipeline name，此设置将被忽略。
142+
- `X-Greptime-Log-Pipeline-Name`: `<pipeline_name>`（可选）- 处理日志的 pipeline 名称。如果未提供，将使用 `X-Greptime-Log-Extract-Keys` 来处理日志。
143+
- `X-Greptime-Log-Pipeline-Version`: `<pipeline_version>`（可选）- 处理日志的 pipeline 的版本。如果未提供，将使用 pipeline 的最新版本。
144144

145145
请求使用二进制 protobuf 编码负载，因此您需要使用支持 `HTTP/protobuf` 的包。
146146

@@ -152,7 +152,8 @@ GreptimeDB 是能够通过 [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/
152152

153153
### 示例代码
154154

155-
请参考 [Alloy 文档](alloy.md#日志)中的示例代码，了解如何将 OpenTelemetry 日志发送到 GreptimeDB。
155+
请参考 [opentelemetry-collector](#opentelemetry-collector) 中的示例代码，里面包含了如何将 OpenTelemetry 日志发送到 GreptimeDB。
156+
也可参考 [Alloy 文档](alloy.md#日志)中的示例代码，了解如何将 OpenTelemetry 日志发送到 GreptimeDB。
156157

157158
### 数据模型
158159

@@ -200,15 +201,15 @@ GreptimeDB 支持直接写入 OpenTelemetry 协议的 traces 数据，并内置
200201

201202
要通过 OpenTelemetry SDK 库将 OpenTelemetry 的 traces 数据发送到 GreptimeDB，请使用以下信息：
202203

203-
* URL: `http{s}://<host>/v1/otlp/v1/traces`
204-
* Headers: headers 与 [Logs](#Logs) 部分相同，你可以参考 [Logs](#Logs) 部分获取更多信息。
204+
- URL: `http{s}://<host>/v1/otlp/v1/traces`
205+
- Headers: headers 与 [Logs](#Logs) 部分相同，你可以参考 [Logs](#Logs) 部分获取更多信息。
205206

206207
默认地，GreptimeDB 会将 traces 数据写入到 `public` 数据库中的 `opentelemetry_traces` 表中。如果想要将 traces 数据写入到不同的表中，你可以使用 `X-Greptime-DB-Name` 和 `X-Greptime-Log-Table-Name` 头部信息来指定数据库和表名。
207208

208209
GreptimeDB 会接受 **protobuf 编码的 traces 数据** 通过 **HTTP 协议** 发送，其中对 HTTP header 有如下要求：
209210

210-
- `content-type` 应配置为 `application/x-protobuf`；
211-
- `x-greptime-pipeline-name` 应配置为 `greptime_trace_v1`；
211+
- `content-type` 应配置为 `application/x-protobuf`；
212+
- `x-greptime-pipeline-name` 应配置为 `greptime_trace_v1`；
212213

213214
### 示例代码
214215

@@ -255,3 +256,71 @@ OTLP traces 数据模型根据以下规则映射到 GreptimeDB 数据模型：
255256
### Append 模式
256257

257258
通过此接口创建的表，默认为[Append 模式](/user-guide/administration/design-table.md#何时使用-append-only-表).
259+
260+
# 使用 OpenTelemetry Collector 将数据发送到 GreptimeDB
261+
262+
OpenTelemetry Collector 是一个可扩展的服务，用于接收、处理和导出 OpenTelemetry 数据。它可以作为数据的中间层，将数据从不同的源发送到 GreptimeDB。
263+
以下是使用 OpenTelemetry Collector 将数据发送到 GreptimeDB 的配置示例。
264+
265+
```yaml
266+
extensions:
267+
basicauth/client:
268+
client_auth:
269+
username: <your_username>
270+
password: <your_password>
271+
272+
receivers:
273+
otlp:
274+
protocols:
275+
grpc:
276+
endpoint: 0.0.0.0:4317
277+
http:
278+
endpoint: 0.0.0.0:4318
279+
280+
exporters:
281+
otlphttp/traces:
282+
endpoint: 'http://127.0.0.1:4000/v1/otlp'
283+
# auth:
284+
# authenticator: basicauth/client
285+
headers:
286+
# x-greptime-db-name: '<your_db_name>'
287+
x-greptime-pipeline-name: 'greptime_trace_v1'
288+
tls:
289+
insecure: true
290+
otlphttp/logs:
291+
endpoint: 'http://127.0.0.1:4000/v1/otlp'
292+
# auth:
293+
# authenticator: basicauth/client
294+
headers:
295+
# x-greptime-db-name: '<your_db_name>'
296+
# x-greptime-log-table-name: "<pipeline_name>"
297+
tls:
298+
insecure: true
299+
300+
otlphttp/metrics:
301+
endpoint: 'http://127.0.0.1:4000/v1/otlp'
302+
# auth:
303+
# authenticator: basicauth/client
304+
headers:
305+
# x-greptime-db-name: '<your_db_name>'
306+
tls:
307+
insecure: true
308+
309+
service:
310+
# extensions: [basicauth/client]
311+
pipelines:
312+
traces:
313+
receivers: [otlp]
314+
exporters: [otlphttp/traces]
315+
logs:
316+
receivers: [otlp]
317+
exporters: [otlphttp/logs]
318+
metrics:
319+
receivers: [otlp]
320+
exporters: [otlphttp/metrics]
321+
```
322+
323+
在上面的配置中，我们定义了一个接收器 `otlp`，它可以接收来自 OpenTelemetry 的数据。我们还定义了三个导出器 `otlphttp/traces`、`otlphttp/logs` 和 `otlphttp/metrics`，它们将数据发送到 GreptimeDB 的 OTLP 路径。
324+
在 otlphttp 协议的基础上，我们增加了一些 header 用来指定一些参数，比如 `x-greptime-pipeline-name` 和 `x-greptime-log-table-name`，`x-greptime-pipeline-name` 用来指定要使用的 pipeline 名称，`x-greptime-log-table-name` 用来指定数据将要写入 GreptimeDB 的表名。
325+
如果你在 GreptimeDB 设置了鉴权。则需要使用 `basicauth/client` 扩展来处理基本的身份验证。
326+
这里我们强烈建议使用不同的导出器来分别处理 traces、logs 和 metrics 数据，一方面是因为 GreptimeDB 会支持一些特定的 header 来自定义一些处理流程，另一方面也可以做好数据隔离。

‎versioned_docs/version-0.14/greptimecloud/integrations/otlp.md‎

Lines changed: 62 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,10 @@ agents.
1515
To send OpenTelemetry Metrics to GreptimeDB through OpenTelemetry SDK libraries,
1616
use the following information:
1717

18-
* URL: `https://<host>/v1/otlp/v1/metrics`
19-
* Headers:
20-
* `X-Greptime-DB-Name`: `<dbname>`
21-
* `Authorization`: `Basic` authentication, which is a Base64 encoded string of `<username>:<password>`. For more information, please refer to [Authentication](https://docs.greptime.com/nightly/user-guide/protocols/http#authentication) in HTTP API.
18+
- URL: `https://<host>/v1/otlp/v1/metrics`
19+
- Headers:
20+
- `X-Greptime-DB-Name`: `<dbname>`
21+
- `Authorization`: `Basic` authentication, which is a Base64 encoded string of `<username>:<password>`. For more information, please refer to [Authentication](https://docs.greptime.com/nightly/user-guide/protocols/http#authentication) in HTTP API.
2222

2323
The request uses binary protobuf to encode the payload, so you need to use packages that support `HTTP/protobuf`. For example, in Node.js, you can use [`exporter-trace-otlp-proto`](https://www.npmjs.com/package/@opentelemetry/exporter-trace-otlp-proto); in Go, you can use [`go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp`](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp); in Java, you can use [`io.opentelemetry:opentelemetry-exporter-otlp`](https://mvnrepository.com/artifact/io.opentelemetry/opentelemetry-exporter-otlp); and in Python, you can use [`opentelemetry-exporter-otlp-proto-http`](https://pypi.org/project/opentelemetry-exporter-otlp-proto-http/).
2424

@@ -28,8 +28,64 @@ The package names may change according to OpenTelemetry, so we recommend that yo
2828

2929
## OpenTelemetry Collector
3030

31-
We recommend [Grafana Alloy](https://grafana.com/docs/alloy/latest/) as OTel
32-
collector if you use OpenTelemetry transformation or other advanced features.
31+
OpenTelemetry Collector is a vendor-agnostic implementation of OpenTelemetry, below is a sample configuration for
32+
exporting to GreptimeDB. You can use the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) to send metrics, logs, and traces to GreptimeDB.
33+
34+
```yaml
35+
extensions:
36+
basicauth/client:
37+
client_auth:
38+
username: <username>
39+
password: <password>
40+
41+
receivers:
42+
otlp:
43+
protocols:
44+
grpc:
45+
endpoint: 0.0.0.0:4317
46+
http:
47+
endpoint: 0.0.0.0:4318
48+
49+
exporters:
50+
otlphttp/traces:
51+
endpoint: 'https://<host>/v1/otlp'
52+
auth:
53+
authenticator: basicauth/client
54+
headers:
55+
x-greptime-db-name: '<dbname>'
56+
x-greptime-pipeline-name: 'greptime_trace_v1'
57+
otlphttp/logs:
58+
endpoint: 'https://<host>/v1/otlp'
59+
auth:
60+
authenticator: basicauth/client
61+
headers:
62+
x-greptime-db-name: '<dbname>'
63+
# x-greptime-log-table-name: "<pipeline_name>"
64+
65+
otlphttp/metrics:
66+
endpoint: 'https://<host>/v1/otlp'
67+
auth:
68+
authenticator: basicauth/client
69+
headers:
70+
x-greptime-db-name: '<dbname>'
71+
72+
service:
73+
extensions: [basicauth/client]
74+
pipelines:
75+
traces:
76+
receivers: [otlp]
77+
exporters: [otlphttp/traces]
78+
logs:
79+
receivers: [otlp]
80+
exporters: [otlphttp/logs]
81+
metrics:
82+
receivers: [otlp]
83+
exporters: [otlphttp/metrics]
84+
```
85+
86+
## Grafana Alloy
87+
88+
If you prefer to use [Grafana Alloy](https://grafana.com/docs/alloy/latest/)'s OpenTelemetry exporter, you can use the following configuration to send your data.
3389
3490
A sample configuration for exporting to GreptimeDB:
3591

0 commit comments

Comments
 (0)