OpenTelemetry Protocol(OTLP)

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

OTLP/HTTP

GreptimeDB 通过原生支持 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 数据类型来原生支持这两种类型。