prometheus / prometheus/OpenMetrics

ABNF of text format seems wrong

Open
#288 2 comments 0 reactions 1 assignee View on GitHub

@ywwg is already working on this.

Since Feb 5, 2025.

OM 1.0
Dominant language
Go
Stars
2.5k
Forks
175
PR merge metrics
No merged PRs in 30d

Description

https://github.com/prometheus/OpenMetrics/blob/main/specification/OpenMetrics.md#abnf is using escaped-string for help message.

According to python parser, we use a different rule for help message. In this rule, " is handled as a normal character.
https://github.com/prometheus/client_python/blob/92b23970f032cbc990aa0e501708c425708e51ea/prometheus_client/parser.py#L32-L41
The testdata also show that " is allowed as a normal character. For example, the following line cannot be parsed with escaped-string since the first \\ is handled as an escaped \ and the following " is handled as an unescaped special character.
https://github.com/prometheus/OpenMetrics/blob/534d77ad9f2a5b7dcfbef3372d32ce45daf03b8f/tests/testdata/parsers/help_escaping/metrics#L29

Updating ABNF as follows solves this problem.

diff --git a/specification/OpenMetrics.md b/specification/OpenMetrics.md
index 5c1eac5..6deee2a 100644
--- a/specification/OpenMetrics.md
+++ b/specification/OpenMetrics.md
@@ -334,7 +334,7 @@ metricset = *metricfamily
 metricfamily = *metric-descriptor *metric
 
 metric-descriptor = HASH SP type SP metricname SP metric-type LF
-metric-descriptor =/ HASH SP help SP metricname SP escaped-string LF
+metric-descriptor =/ HASH SP help SP metricname SP help-escaped-string LF
 metric-descriptor =/ HASH SP unit SP metricname SP *metricname-char LF
 
 metric = *sample
@@ -404,6 +404,15 @@ escaped-char =/ BS normal-char
 
 ; Any unicode character, except newline, double quote, and backslash
 normal-char = %x00-09 / %x0B-21 / %x23-5B / %x5D-D7FF / %xE000-10FFFF
+
+help-escaped-string = *help-escaped-char
+
+help-escaped-char = help-normal-char
+help-escaped-char =/ BS ("n" / BS)
+help-escaped-char =/ BS help-normal-char
+
+; Any unicode character, except newline and backslash
+help-normal-char = %x00-09 / %x0B-5B / %x5D-D7FF / %xE000-10FFFF
 ~~~~
 
 ### Overall Structure

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.