From b2e8d9c61495617dca3e60e1ab1e969aecd5a64a Mon Sep 17 00:00:00 2001 From: shuiyisong Date: Mon, 18 May 2026 11:00:34 +0800 Subject: [PATCH 1/2] docs: add otlp translation docs Signed-off-by: shuiyisong --- .../for-observability/opentelemetry.md | 15 ++++++++++++++- .../for-observability/opentelemetry.md | 15 ++++++++++++++- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/ingest-data/for-observability/opentelemetry.md b/docs/user-guide/ingest-data/for-observability/opentelemetry.md index e76fc01e9..6b478fa66 100644 --- a/docs/user-guide/ingest-data/for-observability/opentelemetry.md +++ b/docs/user-guide/ingest-data/for-observability/opentelemetry.md @@ -122,7 +122,7 @@ If you have not ingested any OTLP metrics before, it will automatically use the Otherwise, it will remain the old data format with the existing table, but use the new data format for any newly created tables. GreptimeDB pre-processes the incoming data before persisting them, including: -1. Converting the metric names(table names) and the label names to the Prometheus style(e.g: replace `.` with `_`). See [here](https://opentelemetry.io/docs/specs/otel/compatibility/prometheus_and_openmetrics/#metric-metadata-1) for details. +1. Converting the metric names(table names) and the label names to the Prometheus style(e.g: replace `.` with `_`). By default, GreptimeDB also adds Prometheus-style suffixes based on the metric unit and type. See [here](https://opentelemetry.io/docs/specs/otel/compatibility/prometheus_and_openmetrics/#metric-metadata-1) for details. Here are some examples of the conversion: @@ -149,6 +149,19 @@ You can set the HTTP headers to configure the pre-processing behaviors. Here are 2. `x-greptime-otlp-metric-promote-resource-attrs`: If not persisting all resource attributes, the attribute name list to be kept. Use `;` to join the name list. 3. `x-greptime-otlp-metric-ignore-resource-attrs`: If persisting all resource attributes, the attribute name list to be ignored. Use `;` to join the name list. 4. `x-greptime-otlp-metric-promote-scope-attrs`: Whether to persist the scope attributes. Default to `false`. +5. `x-greptime-otlp-metric-translation-strategy`: How to translate OTLP metric names(table names) and label names(tag columns) before persisting them. Default to `UnderscoreEscapingWithSuffixes`. + +The `x-greptime-otlp-metric-translation-strategy` header accepts the following values: + +| Value | Metric name behavior | Label name behavior | +| :--- | :--- | :--- | +| `UnderscoreEscapingWithSuffixes` | Convert unsupported characters to `_`, and add Prometheus-style unit/type suffixes. For example, a monotonic sum metric `disk.io` with unit `By` becomes `disk_io_bytes_total`. | Convert unsupported characters to `_`. For example, `service.name` becomes `service_name`. | +| `UnderscoreEscapingWithoutSuffixes` | Convert unsupported characters to `_`, but do not add unit/type suffixes. For example, `disk.io` becomes `disk_io`. | Convert unsupported characters to `_`. For example, `service.name` becomes `service_name`. | +| `NoUTF8EscapingWithSuffixes` | Keep the original metric name characters, and add Prometheus-style unit/type suffixes. For example, a monotonic sum metric `disk.io` with unit `By` becomes `disk.io_bytes_total`. | Keep the original label name characters. For example, `service.name` remains `service.name`. | +| `NoTranslation` | Keep the original metric name without adding suffixes. For example, `disk.io` remains `disk.io`. | Keep the original label name characters. For example, `service.name` remains `service.name`. | + +The header value is case-sensitive. Invalid values are rejected with a `400 Bad Request` response. +See [OTel specs](https://opentelemetry.io/docs/specs/otel/metrics/sdk_exporters/prometheus/#translation-strategy) and [Prometheus docs](https://prometheus.io/docs/guides/opentelemetry/#utf-8) for more details. ### Data Model diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/ingest-data/for-observability/opentelemetry.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/ingest-data/for-observability/opentelemetry.md index 991d6faac..4f9d45904 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/ingest-data/for-observability/opentelemetry.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/ingest-data/for-observability/opentelemetry.md @@ -124,7 +124,7 @@ exporter = OTLPMetricExporter( 否则，GreptimeDB 会对已经存在的表保留原有的数据模型，只有对新创建的指标表使用兼容模式写入。 GreptimeDB 会首先对数据进行预处理，包括： -1. 将指标名（表名）和标签名转换成 Prometheus 风格的命名（例如：将 `.` 替换为 `_`）。具体信息请参考[这里](https://opentelemetry.io/docs/specs/otel/compatibility/prometheus_and_openmetrics/#metric-metadata-1) +1. 将指标名（表名）和标签名转换成 Prometheus 风格的命名（例如：将 `.` 替换为 `_`）。默认情况下，GreptimeDB 还会根据指标单位和类型添加 Prometheus 风格的后缀。具体信息请参考[这里](https://opentelemetry.io/docs/specs/otel/compatibility/prometheus_and_openmetrics/#metric-metadata-1) 以下是一些转换示例： @@ -151,6 +151,19 @@ GreptimeDB 将会直接保存它们，不会进行累计值（cumulative value 2. `x-greptime-otlp-metric-promote-resource-attrs`: 如果不保存所有 resource 资源，需要保存的资源名称列表，用 `;` 连接。 3. `x-greptime-otlp-metric-ignore-resource-attrs`: 如果保存所有的 resource 资源，需要丢弃的资源名称列表，用 `;` 连接。 4. `x-greptime-otlp-metric-promote-scope-attrs`: 是否需要保存 scope 资源。默认是 `false`。 +5. `x-greptime-otlp-metric-translation-strategy`: 在保存前如何转换 OTLP 指标名（表名）和标签名（tag 列）。默认是 `UnderscoreEscapingWithSuffixes`。 + +`x-greptime-otlp-metric-translation-strategy` 请求头支持以下取值： + +| 取值 | 指标名行为 | 标签名行为 | +| :--- | :--- | :--- | +| `UnderscoreEscapingWithSuffixes` | 将不支持的字符转换为 `_`，并添加 Prometheus 风格的单位和类型后缀。例如，单位为 `By` 的 monotonic sum 指标 `disk.io` 会转换为 `disk_io_bytes_total`。 | 将不支持的字符转换为 `_`。例如，`service.name` 会转换为 `service_name`。 | +| `UnderscoreEscapingWithoutSuffixes` | 将不支持的字符转换为 `_`，但不添加单位和类型后缀。例如，`disk.io` 会转换为 `disk_io`。 | 将不支持的字符转换为 `_`。例如，`service.name` 会转换为 `service_name`。 | +| `NoUTF8EscapingWithSuffixes` | 保留指标名中的原始字符，并添加 Prometheus 风格的单位和类型后缀。例如，单位为 `By` 的 monotonic sum 指标 `disk.io` 会转换为 `disk.io_bytes_total`。 | 保留标签名中的原始字符。例如，`service.name` 保持为 `service.name`。 | +| `NoTranslation` | 保留原始指标名，并且不添加后缀。例如，`disk.io` 保持为 `disk.io`。 | 保留标签名中的原始字符。例如，`service.name` 保持为 `service.name`。 | + +请求头取值区分大小写。无效取值会被拒绝，并返回 `400 Bad Request`。 +更多信息请参考 [OTel 规范](https://opentelemetry.io/docs/specs/otel/metrics/sdk_exporters/prometheus/#translation-strategy)和 [Prometheus 文档](https://prometheus.io/docs/guides/opentelemetry/#utf-8)。 ### 数据模型 From fdad8793f213a225a62cf4187500eb96241a0180 Mon Sep 17 00:00:00 2001 From: shuiyisong Date: Tue, 19 May 2026 10:48:36 +0800 Subject: [PATCH 2/2] chore: add examples of translation Signed-off-by: shuiyisong --- .../ingest-data/for-observability/opentelemetry.md | 12 ++++++------ .../ingest-data/for-observability/opentelemetry.md | 12 ++++++------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/user-guide/ingest-data/for-observability/opentelemetry.md b/docs/user-guide/ingest-data/for-observability/opentelemetry.md index 6b478fa66..d2873f9d9 100644 --- a/docs/user-guide/ingest-data/for-observability/opentelemetry.md +++ b/docs/user-guide/ingest-data/for-observability/opentelemetry.md @@ -153,12 +153,12 @@ You can set the HTTP headers to configure the pre-processing behaviors. Here are The `x-greptime-otlp-metric-translation-strategy` header accepts the following values: -| Value | Metric name behavior | Label name behavior | -| :--- | :--- | :--- | -| `UnderscoreEscapingWithSuffixes` | Convert unsupported characters to `_`, and add Prometheus-style unit/type suffixes. For example, a monotonic sum metric `disk.io` with unit `By` becomes `disk_io_bytes_total`. | Convert unsupported characters to `_`. For example, `service.name` becomes `service_name`. | -| `UnderscoreEscapingWithoutSuffixes` | Convert unsupported characters to `_`, but do not add unit/type suffixes. For example, `disk.io` becomes `disk_io`. | Convert unsupported characters to `_`. For example, `service.name` becomes `service_name`. | -| `NoUTF8EscapingWithSuffixes` | Keep the original metric name characters, and add Prometheus-style unit/type suffixes. For example, a monotonic sum metric `disk.io` with unit `By` becomes `disk.io_bytes_total`. | Keep the original label name characters. For example, `service.name` remains `service.name`. | -| `NoTranslation` | Keep the original metric name without adding suffixes. For example, `disk.io` remains `disk.io`. | Keep the original label name characters. For example, `service.name` remains `service.name`. | +| Value | Metric name behavior | Label name behavior | Original names | Translated names | +| :--- | :--- | :--- | :--- | :--- | +| `UnderscoreEscapingWithSuffixes` | Convert unsupported characters to `_`, and add Prometheus-style unit/type suffixes. | Convert unsupported characters to `_`. | Metric: `http.server.request-duration_total` (monotonic sum, unit `ms`)
Label: `_http.status-code` | Metric: `http_server_request_duration_milliseconds_total`
Label: `key_http_status_code` | +| `UnderscoreEscapingWithoutSuffixes` | Convert unsupported characters to `_`, but do not add unit/type suffixes. | Convert unsupported characters to `_`. | Metric: `http.server.request-duration_total` (monotonic sum, unit `ms`)
Label: `_http.status-code` | Metric: `http_server_request_duration_total`
Label: `key_http_status_code` | +| `NoUTF8EscapingWithSuffixes` | Keep the original metric name characters, and add Prometheus-style unit/type suffixes. | Keep the original label name characters. | Metric: `http.server.request-duration_total` (monotonic sum, unit `ms`)
Label: `_http.status-code` | Metric: `http.server.request-duration_milliseconds_total`
Label: `_http.status-code` | +| `NoTranslation` | Keep the original metric name without adding suffixes. | Keep the original label name characters. | Metric: `http.server.request-duration_total` (monotonic sum, unit `ms`)
Label: `_http.status-code` | Metric: `http.server.request-duration_total`
Label: `_http.status-code` | The header value is case-sensitive. Invalid values are rejected with a `400 Bad Request` response. See [OTel specs](https://opentelemetry.io/docs/specs/otel/metrics/sdk_exporters/prometheus/#translation-strategy) and [Prometheus docs](https://prometheus.io/docs/guides/opentelemetry/#utf-8) for more details. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/ingest-data/for-observability/opentelemetry.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/ingest-data/for-observability/opentelemetry.md index 4f9d45904..e1a9ed368 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/ingest-data/for-observability/opentelemetry.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/ingest-data/for-observability/opentelemetry.md @@ -155,12 +155,12 @@ GreptimeDB 将会直接保存它们，不会进行累计值（cumulative value `x-greptime-otlp-metric-translation-strategy` 请求头支持以下取值： -| 取值 | 指标名行为 | 标签名行为 | -| :--- | :--- | :--- | -| `UnderscoreEscapingWithSuffixes` | 将不支持的字符转换为 `_`，并添加 Prometheus 风格的单位和类型后缀。例如，单位为 `By` 的 monotonic sum 指标 `disk.io` 会转换为 `disk_io_bytes_total`。 | 将不支持的字符转换为 `_`。例如，`service.name` 会转换为 `service_name`。 | -| `UnderscoreEscapingWithoutSuffixes` | 将不支持的字符转换为 `_`，但不添加单位和类型后缀。例如，`disk.io` 会转换为 `disk_io`。 | 将不支持的字符转换为 `_`。例如，`service.name` 会转换为 `service_name`。 | -| `NoUTF8EscapingWithSuffixes` | 保留指标名中的原始字符，并添加 Prometheus 风格的单位和类型后缀。例如，单位为 `By` 的 monotonic sum 指标 `disk.io` 会转换为 `disk.io_bytes_total`。 | 保留标签名中的原始字符。例如，`service.name` 保持为 `service.name`。 | -| `NoTranslation` | 保留原始指标名，并且不添加后缀。例如，`disk.io` 保持为 `disk.io`。 | 保留标签名中的原始字符。例如，`service.name` 保持为 `service.name`。 | +| 取值 | 指标名行为 | 标签名行为 | 原始名称 | 转换后名称 | +| :--- | :--- | :--- | :--- | :--- | +| `UnderscoreEscapingWithSuffixes` | 将不支持的字符转换为 `_`，并添加 Prometheus 风格的单位和类型后缀。 | 将不支持的字符转换为 `_`。 | 指标：`http.server.request-duration_total`（monotonic sum，单位 `ms`）
标签：`_http.status-code` | 指标：`http_server_request_duration_milliseconds_total`
标签：`key_http_status_code` | +| `UnderscoreEscapingWithoutSuffixes` | 将不支持的字符转换为 `_`，但不添加单位和类型后缀。 | 将不支持的字符转换为 `_`。 | 指标：`http.server.request-duration_total`（monotonic sum，单位 `ms`）
标签：`_http.status-code` | 指标：`http_server_request_duration_total`
标签：`key_http_status_code` | +| `NoUTF8EscapingWithSuffixes` | 保留指标名中的原始字符，并添加 Prometheus 风格的单位和类型后缀。 | 保留标签名中的原始字符。 | 指标：`http.server.request-duration_total`（monotonic sum，单位 `ms`）
标签：`_http.status-code` | 指标：`http.server.request-duration_milliseconds_total`
标签：`_http.status-code` | +| `NoTranslation` | 保留原始指标名，并且不添加后缀。 | 保留标签名中的原始字符。 | 指标：`http.server.request-duration_total`（monotonic sum，单位 `ms`）
标签：`_http.status-code` | 指标：`http.server.request-duration_total`
标签：`_http.status-code` | 请求头取值区分大小写。无效取值会被拒绝，并返回 `400 Bad Request`。 更多信息请参考 [OTel 规范](https://opentelemetry.io/docs/specs/otel/metrics/sdk_exporters/prometheus/#translation-strategy)和 [Prometheus 文档](https://prometheus.io/docs/guides/opentelemetry/#utf-8)。