Skip to contentSkip to conversation

doc: add deprecation for restrictions in telemetry naming

PATCH Superseded Bruce Richardson 6 participants 10 messages Jul 7, 2022 – Jul 15, 2022

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 doc: add deprecation for restrictions in telemetry naming

Following discussion on-list [1], we will look to limited the allowed characters in names for items in telemetry. This will simplify the escaping needed for json output, or any future output formats. The lists will initially be minimal, since expansion to allow more characters can be done without affecting compatibility, while reducing the set cannot.

[1] http://inbox.dpdk.org/dev/[email protected]/#r

---
 doc/guides/rel_notes/deprecation.rst | 6 ++++++
 1 file changed, 6 insertions(+)
doc/guides/rel_notes/deprecation.rst +6 -0
index 4e5b23c53d..9366690ec5 100644
@@ -119,6 +119,12 @@ Deprecation Notices
 * metrics: The function ``rte_metrics_init`` will have a non-void return
   in order to notify errors instead of calling ``rte_exit``.
 
+* telemetry: The allowed characters in names for dictionary values will be limited to
+  alphanumeric characters and a small subset of additional printable characters.
+  This will ensure that all dictionary parameter names can be output without escaping
+  in json - or in any future output format used. Names for the telemetry commands will
+  be similarly limited.
+
 * raw/ioat: The ``ioat`` rawdev driver has been deprecated, since it's
   functionality is provided through the new ``dmadev`` infrastructure.
   To continue to use hardware previously supported by the ``ioat`` rawdev driver,
Signature · 1 line
2.34.1
Acked-by on v1 1/1
#1 lore raw
Quoted 24 lines · Bruce Richardson

Following discussion on-list [1], we will look to limited the allowed characters in names for items in telemetry. This will simplify the escaping needed for json output, or any future output formats. The lists will initially be minimal, since expansion to allow more characters can be done without affecting compatibility, while reducing the set cannot.

[1] http://inbox.dpdk.org/dev/[email protected]/#r

---
  doc/guides/rel_notes/deprecation.rst | 6 ++++++
  1 file changed, 6 insertions(+)
doc/guides/rel_notes/deprecation.rst +0 -0
index 4e5b23c53d..9366690ec5 100644
@@ -119,6 +119,12 @@ Deprecation Notices
  * metrics: The function ``rte_metrics_init`` will have a non-void return
    in order to notify errors instead of calling ``rte_exit``.

doc/guides/rel_notes/deprecation.rst Deprecation Notices · line 130

Quoted 10 lines
doc/guides/rel_notes/deprecation.rst +6 -0
 
+* telemetry: The allowed characters in names for dictionary values will be limited to
+  alphanumeric characters and a small subset of additional printable characters.
+  This will ensure that all dictionary parameter names can be output without escaping
+  in json - or in any future output format used. Names for the telemetry commands will
+  be similarly limited.
+
  * raw/ioat: The ``ioat`` rawdev driver has been deprecated, since it's
    functionality is provided through the new ``dmadev`` infrastructure.
    To continue to use hardware previously supported by the ``ioat`` rawdev driver,
Acked-by on v1 1/1
#2 lore raw
In reply to Bruce Richardson
Quoted 32 lines

From: Bruce Richardson [mailto:[email protected]]
Sent: Thursday, 7 July 2022 15.40

Following discussion on-list [1], we will look to limited the allowed characters in names for items in telemetry. This will simplify the escaping needed for json output, or any future output formats. The lists
will initially be minimal, since expansion to allow more characters can be done without affecting compatibility, while reducing the set cannot.

[1] http://inbox.dpdk.org/dev/20220623164245.561371-1-
[email protected]/#r

---
 doc/guides/rel_notes/deprecation.rst | 6 ++++++
 1 file changed, 6 insertions(+)
doc/guides/rel_notes/deprecation.rst +0 -0
index 4e5b23c53d..9366690ec5 100644
@@ -119,6 +119,12 @@ Deprecation Notices
 * metrics: The function ``rte_metrics_init`` will have a non-void

return
in order to notify errors instead of calling ``rte_exit``.

Quoted 7 lines

+* telemetry: The allowed characters in names for dictionary values will be limited to
+ alphanumeric characters and a small subset of additional printable characters.
+ This will ensure that all dictionary parameter names can be output without escaping
+ in json - or in any future output format used. Names for the

json -> JSON

Quoted 2 lines

telemetry commands will
+ be similarly limited.

Perhaps also add a comment about parameters to telemetry commands, for completeness.

Quoted 8 lines

+
* raw/ioat: The ``ioat`` rawdev driver has been deprecated, since it's functionality is provided through the new ``dmadev`` infrastructure. To continue to use hardware previously supported by the ``ioat``
rawdev driver,
--
2.34.1

#3 lore raw
Quoted 32 lines · Morten Brørup
Quoted 32 lines

From: Bruce Richardson [mailto:[email protected]]
Sent: Thursday, 7 July 2022 15.40

Following discussion on-list [1], we will look to limited the allowed characters in names for items in telemetry. This will simplify the escaping needed for json output, or any future output formats. The lists
will initially be minimal, since expansion to allow more characters can be done without affecting compatibility, while reducing the set cannot.

[1] http://inbox.dpdk.org/dev/20220623164245.561371-1-
[email protected]/#r

---
 doc/guides/rel_notes/deprecation.rst | 6 ++++++
 1 file changed, 6 insertions(+)
doc/guides/rel_notes/deprecation.rst +0 -0
index 4e5b23c53d..9366690ec5 100644
@@ -119,6 +119,12 @@ Deprecation Notices
 * metrics: The function ``rte_metrics_init`` will have a non-void

return
in order to notify errors instead of calling ``rte_exit``.

Quoted 10 lines
Quoted 7 lines

+* telemetry: The allowed characters in names for dictionary values will be limited to
+ alphanumeric characters and a small subset of additional printable characters.
+ This will ensure that all dictionary parameter names can be output without escaping
+ in json - or in any future output format used. Names for the

json -> JSON

Capital idea! (pun very much intended :-) )

Quoted 5 lines
Quoted 2 lines

telemetry commands will
+ be similarly limited.

Perhaps also add a comment about parameters to telemetry commands, for completeness.

I was not intending to impose restrictions on the parameters themselves since currently they are not output as part of any json. However, now you have got me thinking that perhaps we should look to scan parameters for invalid characters before we hand them over to the individual functions. That would allow the possibility of including parameters in any replies in a future format.

Was this what you had in mind, or any other thoughts?

/Bruce

#4 lore raw
Quoted 51 lines

From: Bruce Richardson [mailto:[email protected]]
Sent: Monday, 11 July 2022 12.54

Quoted 4 lines · Morten Brørup
Quoted 4 lines

From: Bruce Richardson [mailto:[email protected]]
Sent: Thursday, 7 July 2022 15.40

Following discussion on-list [1], we will look to limited the

allowed

Quoted 4 lines
Quoted 4 lines

characters in names for items in telemetry. This will simplify the escaping needed for json output, or any future output formats. The lists
will initially be minimal, since expansion to allow more characters

can

Quoted 1 line
Quoted 1 line

be done without affecting compatibility, while reducing the set

cannot.

Quoted 23 lines
Quoted 23 lines

[1] http://inbox.dpdk.org/dev/20220623164245.561371-1-
[email protected]/#r

---
 doc/guides/rel_notes/deprecation.rst | 6 ++++++
 1 file changed, 6 insertions(+)
doc/guides/rel_notes/deprecation.rst +0 -0
index 4e5b23c53d..9366690ec5 100644
@@ -119,6 +119,12 @@ Deprecation Notices
 * metrics: The function ``rte_metrics_init`` will have a non-void

return
in order to notify errors instead of calling ``rte_exit``.

Quoted 3 lines
Quoted 3 lines

+* telemetry: The allowed characters in names for dictionary values will be limited to
+ alphanumeric characters and a small subset of additional

printable

Quoted 2 lines
Quoted 2 lines

characters.
+ This will ensure that all dictionary parameter names can be

output

Quoted 5 lines
Quoted 2 lines

without escaping
+ in json - or in any future output format used. Names for the

json -> JSON

Quoted 8 lines

Capital idea! (pun very much intended :-) )

Quoted 4 lines
Quoted 2 lines

telemetry commands will
+ be similarly limited.

Perhaps also add a comment about parameters to telemetry commands,

for completeness.

Quoted 1 line

I intentionally phrased this comment vaguely, to see what you had been thinking about this. And it certainly had the desired effect. :-)

Quoted 11 lines

I was not intending to impose restrictions on the parameters themselves since currently they are not output as part of any json. However, now you
have got me thinking that perhaps we should look to scan parameters for invalid characters before we hand them over to the individual functions.
That would allow the possibility of including parameters in any replies in
a future format.

Quoted 1 line

Was this what you had in mind, or any other thoughts?

Not exactly what I had in mind...

Your patch adds that "Names for the telemetry commands will be similarly limited.". This is input, not output. So you need to describe what restrictions are imposed on input.

The input commands and format don't follow any structured standard; command names, hierarchy and parameter names are individually chosen by each developer, and parameters are just a bunch of param=value with no types or limits to the values.

Also, the input is not JSON formatted, but - without looking deeply into the telemetry library - I suppose it might be URL encoded, where e.g. space is encoded as "%20" and '&' is encoded as "%26".

I think we should just leave the input without restrictions. Changing it would require a major overhaul to provide any significant improvement, e.g. attaching types to the parameters, so their values are not just BLOBs.

I don't strongly oppose to limiting the input command names; but we shouldn't impose any limit on what follows the command. So I'm proposing to explicitly mention that we don't impose any input limits beyond the command names.

Or we could provide input restrictions and parsing/formatting in a separate patch set.

Acked-by on v1 1/1
#5 lore raw
In reply to Bruce Richardson
Quoted 50 lines

-----Original Message-----
From: Richardson, Bruce <[email protected]>
Sent: Thursday 7 July 2022 14:40
To: [email protected]
Cc: Richardson, Bruce <[email protected]>; [email protected]; [email protected]; Power, Ciara <[email protected]>
Subject: [PATCH] doc: add deprecation for restrictions in telemetry naming

Following discussion on-list [1], we will look to limited the allowed characters in names for items in telemetry. This will simplify the escaping needed for json output, or any future output formats. The lists will initially be minimal, since expansion to allow more characters can be done without affecting compatibility, while reducing the set cannot.

[1] http://inbox.dpdk.org/dev/20220623164245.561371-1-
[email protected]/#r

---
 doc/guides/rel_notes/deprecation.rst | 6 ++++++
 1 file changed, 6 insertions(+)
doc/guides/rel_notes/deprecation.rst +9 -0
index 4e5b23c53d..9366690ec5 100644
@@ -119,6 +119,12 @@ Deprecation Notices
 * metrics: The function ``rte_metrics_init`` will have a non-void return
   in order to notify errors instead of calling ``rte_exit``.
 
+* telemetry: The allowed characters in names for dictionary values will
+be limited to
+  alphanumeric characters and a small subset of additional printable characters.
+  This will ensure that all dictionary parameter names can be output
+without escaping
+  in json - or in any future output format used. Names for the
+telemetry commands will
+  be similarly limited.
+
 * raw/ioat: The ``ioat`` rawdev driver has been deprecated, since it's
   functionality is provided through the new ``dmadev`` infrastructure.
   To continue to use hardware previously supported by the ``ioat`` rawdev
Quoted 3 lines

driver,
--
2.34.1

Acked-by on v1 1/1
#6 lore raw
In reply to Bruce Richardson
Quoted 7 lines · Bruce Richardson

Following discussion on-list [1], we will look to limited the allowed characters in names for items in telemetry. This will simplify the escaping needed for json output, or any future output formats. The lists will initially be minimal, since expansion to allow more characters can be done without affecting compatibility, while reducing the set cannot.

Quoted 5 lines
Signature · 1 line
David Marchand
#7 lore raw

PATCH v2 1/1 doc: add deprecation for restrictions in telemetry naming

In reply to Bruce Richardson

Following discussion on-list [1], we will look to limited the allowed characters in names for items in telemetry. This will simplify the escaping needed for json output, or any future output formats. The lists will initially be minimal, since expansion to allow more characters can be done without affecting compatibility, while reducing the set cannot.

[1] http://inbox.dpdk.org/dev/[email protected]/#r

---
 doc/guides/rel_notes/deprecation.rst | 7 +++++++
 1 file changed, 7 insertions(+)
doc/guides/rel_notes/deprecation.rst +7 -0
index 4e5b23c53d..6ef93758d4 100644
@@ -119,6 +119,13 @@ Deprecation Notices
 * metrics: The function ``rte_metrics_init`` will have a non-void return
   in order to notify errors instead of calling ``rte_exit``.
 
+* telemetry: The allowed characters in names for dictionary values will be limited to
+  alphanumeric characters and a small subset of additional printable characters.
+  This will ensure that all dictionary parameter names can be output without escaping
+  in JSON - or in any future output format used. Names for the telemetry commands will
+  be similarly limited. The parameters for telemetry commands are unaffected by this
+  change.
+
 * raw/ioat: The ``ioat`` rawdev driver has been deprecated, since it's
   functionality is provided through the new ``dmadev`` infrastructure.
   To continue to use hardware previously supported by the ``ioat`` rawdev driver,
Signature · 1 line
2.34.1
#8 lore raw

PATCH v3 1/1 doc: add deprecation for restrictions in telemetry naming

In reply to Bruce Richardson

Following discussion on-list [1], we will look to limited the allowed characters in names for items in telemetry. This will simplify the escaping needed for json output, or any future output formats. The lists will initially be minimal, since expansion to allow more characters can be done without affecting compatibility, while reducing the set cannot.

[1] http://inbox.dpdk.org/dev/[email protected]/#r

---
 doc/guides/rel_notes/deprecation.rst | 7 +++++++
 1 file changed, 7 insertions(+)
doc/guides/rel_notes/deprecation.rst +7 -0
index 4e5b23c53d..6ef93758d4 100644
@@ -119,6 +119,13 @@ Deprecation Notices
 * metrics: The function ``rte_metrics_init`` will have a non-void return
   in order to notify errors instead of calling ``rte_exit``.
 
+* telemetry: The allowed characters in names for dictionary values will be limited to
+  alphanumeric characters and a small subset of additional printable characters.
+  This will ensure that all dictionary parameter names can be output without escaping
+  in JSON - or in any future output format used. Names for the telemetry commands will
+  be similarly limited. The parameters for telemetry commands are unaffected by this
+  change.
+
 * raw/ioat: The ``ioat`` rawdev driver has been deprecated, since it's
   functionality is provided through the new ``dmadev`` infrastructure.
   To continue to use hardware previously supported by the ``ioat`` rawdev driver,
Signature · 1 line
2.34.1
Acked-by Andrew Rybchenko Acked-by Morten Brørup Acked-by Ciara Power Acked-by David Marchand on v3 1/1 Applied
#9 lore raw

12/07/2022 11:09, Bruce Richardson:

Quoted 9 lines

Following discussion on-list [1], we will look to limited the allowed characters in names for items in telemetry. This will simplify the escaping needed for json output, or any future output formats. The lists will initially be minimal, since expansion to allow more characters can be done without affecting compatibility, while reducing the set cannot.

[1] http://inbox.dpdk.org/dev/[email protected]/#r

Applied, thanks.