doc: add deprecation for restrictions in telemetry naming
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
@@ -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
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.
Signed-off-by Bruce Richardson <[email protected]>[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@@ -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,
Quoted 32 lines
From: Bruce Richardson [mailto:[email protected]]
Sent: Thursday, 7 July 2022 15.40Following 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.Signed-off-by Bruce Richardson <[email protected]>[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@@ -119,6 +119,12 @@ Deprecation Notices * metrics: The function ``rte_metrics_init`` will have a non-voidreturn
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
Quoted 32 lines · Morten Brørup
Quoted 32 lines
From: Bruce Richardson [mailto:[email protected]]
Sent: Thursday, 7 July 2022 15.40Following 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.Signed-off-by Bruce Richardson <[email protected]>[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@@ -119,6 +119,12 @@ Deprecation Notices * metrics: The function ``rte_metrics_init`` will have a non-voidreturn
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 thejson -> 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
Quoted 51 lines
From: Bruce Richardson [mailto:[email protected]]
Sent: Monday, 11 July 2022 12.54Quoted 4 lines · Morten Brørup
Quoted 4 lines
From: Bruce Richardson [mailto:[email protected]]
Sent: Thursday, 7 July 2022 15.40Following 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 characterscan
Quoted 1 line
Quoted 1 line
be done without affecting compatibility, while reducing the set
cannot.
Quoted 23 lines
Quoted 23 lines
Signed-off-by Bruce Richardson <[email protected]>[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@@ -119,6 +119,12 @@ Deprecation Notices * metrics: The function ``rte_metrics_init`` will have a non-voidreturn
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 additionalprintable
Quoted 2 lines
Quoted 2 lines
characters.
+ This will ensure that all dictionary parameter names can beoutput
Quoted 5 lines
Quoted 2 lines
without escaping
+ in json - or in any future output format used. Names for thejson -> 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.
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 namingFollowing 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.
Signed-off-by Bruce Richardson <[email protected]>[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@@ -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
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
Signed-off-by Bruce Richardson <[email protected]>
Signature · 1 line
David Marchand
PATCH v2 1/1 doc: add deprecation for restrictions in telemetry naming
In reply to Bruce RichardsonFollowing 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
@@ -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
PATCH v3 1/1 doc: add deprecation for restrictions in telemetry naming
In reply to Bruce RichardsonFollowing 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
@@ -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
Thomas Monjalon
Acked-by Andrew Rybchenko Acked-by Morten Brørup Acked-by Ciara Power Acked-by David Marchand on v3 1/1 Applied12/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
Signed-off-by Bruce Richardson <[email protected]>
Applied, thanks.