OpenTelemetry Protocol (OTLP)

OpenTelemetry 是一个供应商中立的开源可观测性框架，用于检测、生成、收集和导出观测数据，例如 traces, metrics 和 logs。 OpenTelemetry Protocol (OTLP) 定义了观测数据在观测源和中间进程（例如收集器和观测后端）之间的编码、传输机制。

OpenTelemetry Collectors

你可以很简单地将 GreptimeDB 配置为 OpenTelemetry Collector 的目标。 有关更多信息，请参阅 Grafana Alloy 示例。

Metrics

GreptimeDB 通过原生支持 OTLP/HTTP 协议，可以作为后端存储服务来接收 OpenTelemetry 指标数据。

OTLP/HTTP API

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

  • URL: https://<host>/v1/otlp/v1/metrics
  • Headers:
  • X-Greptime-DB-Name: <dbname>
  • Authorization: Basic 认证，是 <username>:<password> 的 Base64 编码字符串。更多信息请参考 鉴权 和 HTTP API。

请求中使用 binary protobuf 编码 payload，因此你需要使用支持 HTTP/protobuf 的包。例如，在 Node.js 中，可以使用 exporter-trace-otlp-proto；在 Go 中，可以使用 go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp；在 Java 中，可以使用 io.opentelemetry:opentelemetry-exporter-otlp；在 Python 中，可以使用 opentelemetry-exporter-otlp-proto-http。

OpenTelemetry Protocol (OTLP) - 图1注意

包名可能会根据 OpenTelemetry 的发展发生变化，因此建议你参考 OpenTelemetry 官方文档以获取最新信息。

请参考 Opentelementry 的官方文档获取它所支持的编程语言的更多信息。

示例代码

下面是一些编程语言设置请求的示例代码：

  • TypeScript
  • Go
  • Java
  • Python
1. const auth = Buffer.from(`${username}:${password}`).toString('base64')
2. const exporter = new OTLPMetricExporter({
3. url: `https://${dbHost}/v1/otlp/v1/metrics`,
4. headers: {
5. Authorization: `Basic ${auth}`,
6. "X-Greptime-DB-Name": db,
7. },
8. timeoutMillis: 5000,
9. })

1. auth := base64.StdEncoding.EncodeToString([]byte(fmt.Sprintf("%s:%s", *username, *password)))
2. exporter, err := otlpmetrichttp.New(
3. context.Background(),
4. otlpmetrichttp.WithEndpoint(*dbHost),
5. otlpmetrichttp.WithURLPath("/v1/otlp/v1/metrics"),
6. otlpmetrichttp.WithHeaders(map[string]string{
7. "X-Greptime-DB-Name": *dbName,
8. "Authorization":      "Basic " + auth,
9. }),
10. otlpmetrichttp.WithTimeout(time.Second*5),
11. )

1. String endpoint = String.format("https://%s/v1/otlp/v1/metrics", dbHost);
2. String auth = username + ":" + password;
3. String b64Auth = new String(Base64.getEncoder().encode(auth.getBytes()));
4. OtlpHttpMetricExporter exporter = OtlpHttpMetricExporter.builder()
5. .setEndpoint(endpoint)
6. .addHeader("X-Greptime-DB-Name", db)
7. .addHeader("Authorization", String.format("Basic %s", b64Auth))
8. .setTimeout(Duration.ofSeconds(5))
9. .build();

1. auth = f"{username}:{password}"
2. b64_auth = base64.b64encode(auth.encode()).decode("ascii")
3. endpoint = f"https://{host}/v1/otlp/v1/metrics"
4. exporter = OTLPMetricExporter(
5. endpoint=endpoint,
6. headers={"Authorization": f"Basic {b64_auth}", "X-Greptime-DB-Name": db},
7. timeout=5)

你可以在 Github 中找到可执行的 Demo：Go, Java, Python, and Node.js.

OpenTelemetry Protocol (OTLP) - 图2注意

示例代码可能会根据 OpenTelemetry 的发展发生变化，因此建议你参考 OpenTelemetry 官方文档以获取最新信息。

关于示例代码，请参考 Opentelementry 的官方文档获取它所支持的编程语言获取更多信息。

数据模型

OTLP 指标数据模型按照下方的规则被映射到 GreptimeDB 数据模型中：

  • Metric 的名称将被作为 GreptimeDB 表的名称，当表不存在时会自动创建。
  • 所有的 Attribute ，包含 resource 级别、scope 级别和 data_point 级别，都被作为 GreptimeDB 表的 tag 列。
  • 数据点的时间戳被作为 GreptimeDB 的时间戳索引，列名 greptime_timestamp。
  • Gauge/Sum 两种类型的数据点数据被作为 field 列，列名 greptime_value。
  • Summary 类型的每个 quantile 被作为单独的数据列，列名 greptime_pxx，其中 xx 是 quantile 的数据，如 90 / 99 等。
  • Histogram 和 ExponentialHistogram 暂时未被支持，我们可能在后续版本中推出 Histogram 数据类型来原生支持这两种类型。

Logs

GreptimeDB 是能够通过 OTLP/HTTP 协议原生地消费 OpenTelemetry 日志。

OTLP/HTTP API

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

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

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

OpenTelemetry Protocol (OTLP) - 图3提示

包名可能会根据 OpenTelemetry 的更新而变化，因此我们建议您参考官方 OpenTelemetry 文档以获取最新信息。

有关 OpenTelemetry SDK 的更多信息，请参考您首选编程语言的官方文档。

示例代码

请参考 Alloy 文档中的示例代码，了解如何将 OpenTelemetry 日志发送到 GreptimeDB。

数据模型

OTLP 日志数据模型根据以下规则映射到 GreptimeDB 数据模型：

默认表结构：

1. +-----------------------+---------------------+------+------+---------+---------------+
2. | Column                | Type                | Key  | Null | Default | Semantic Type |
3. +-----------------------+---------------------+------+------+---------+---------------+
4. | timestamp             | TimestampNanosecond | PRI  | NO   |         | TIMESTAMP     |
5. | trace_id              | String              |      | YES  |         | FIELD         |
6. | span_id               | String              |      | YES  |         | FIELD         |
7. | severity_text         | String              |      | YES  |         | FIELD         |
8. | severity_number       | Int32               |      | YES  |         | FIELD         |
9. | body                  | String              |      | YES  |         | FIELD         |
10. | log_attributes        | Json                |      | YES  |         | FIELD         |
11. | trace_flags           | UInt32              |      | YES  |         | FIELD         |
12. | scope_name            | String              | PRI  | YES  |         | TAG           |
13. | scope_version         | String              |      | YES  |         | FIELD         |
14. | scope_attributes      | Json                |      | YES  |         | FIELD         |
15. | scope_schema_url      | String              |      | YES  |         | FIELD         |
16. | resource_attributes   | Json                |      | YES  |         | FIELD         |
17. | resource_schema_url   | String              |      | YES  |         | FIELD         |
18. +-----------------------+---------------------+------+------+---------+---------------+
19. 17 rows in set (0.00 sec)
  • 您可以使用 X-Greptime-Log-Table-Name 指定存储日志的表名。如果未提供，默认表名为 opentelemetry_logs。
  • 所有属性，包括资源属性、范围属性和日志属性，将作为 JSON 列存储在 GreptimeDB 表中。
  • 日志的时间戳将用作 GreptimeDB 中的时间戳索引，列名为 timestamp。建议使用 time_unix_nano 作为时间戳列。如果未提供 time_unix_nano，将使用 observed_time_unix_nano。