OpenTelemetry Protocol(OTLP)

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

OTLP/HTTP

GreptimeDB 可以作为 collector 通过 OTLP/HTTP 协议接收 OpenTelemetry 指标。

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 的发展发生变化，因此建议你参考 OpenTelemetry 官方文档以获取最新信息。

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

示例代码

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

TypeScriptGoJavaPython

ts

  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. })

Go

  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. )

Java

  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();

python

  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 的发展发生变化，因此建议你参考 OpenTelemetry 官方文档以获取最新信息。

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

数据模型

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

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