Define extension schema policy and registry #415

LPardue · 2024-03-17T23:59:57Z

Alternative to #284.

This follows Lennox's suggestion to take influence from RFC 8285 and reference
extension schema according to a URI. IETF documents can use URNs under a formal
namespace, and as such we register a new qlog URN Sub-namespace for
Registered Protocol Parameter Identifiers.

Fixes #283

Alternative to #284. This follows Lennox's suggestion to take influence from RFC 8285 and reference extension schema according to a URI. IETF documents can use URNs under a formal namespace, and as such we register a new `qlog` URN Sub-namespace for Registered Protocol Parameter Identifiers. Fixes #283

LPardue · 2024-03-18T00:09:13Z

@JonathanLennox I tried to borrow a lot from RFC 8285 but not take it fully verbatim. Would welcome your thoughts.

JonathanLennox · 2024-03-18T07:38:06Z

This matches my suggestion, looks good to me!

rmarx

Couple of things here that could use clarification, but in general I of course think this is a good approach :)

draft-ietf-quic-qlog-main-schema.md

rmarx · 2024-03-18T09:38:29Z

draft-ietf-quic-qlog-main-schema.md

+
+## Extended Event Schema
+
+New events SHOULD be defined using an extension schema, using the annotations


Suggested change

New events SHOULD be defined using an extension schema, using the annotations

New event documents SHOULD be defined using an extension schema, using the annotations

Not clear it's not the individual events that are affected, but rather groups of events?

Thought a bit more on this. What I think we want is for logical groups of qlog events to be defined under a single schema. There should not be a restriction that a single IETF document defines only a single schema - for example, we might want to have a single document that defines events for a bunch of QUIC extensions and split them out by extension-specific schemas.

I don't think the current text, or the proposal, articulate this well. Will try to come up with a some different text.

draft-ietf-quic-qlog-main-schema.md

rmarx · 2024-03-18T10:01:31Z

draft-ietf-quic-qlog-main-schema.md

+element and assignment of the URI MUST have been authorized by the owner of the
+domain name on or very close to that date. (This avoids problems when domain
+names change ownership.) If the resource or document defines several categories
+or groups of events, then the URI MUST identify the actual extension in use,


this could do with an example maybe? not sure what that would look like if you're for example using quic events... would you need to list #connectivity and #transport as separate subentries in additional_event_schema or not? Where do you draw the line?

Good point, this was another copy-paste. I could argue either way. On one hand, it seems annoying to have to expand out all the categories in e.g. our QUIC events specification. On the other hand, the capability to state what events a logging endpoint could have used has come up in other discussions, and this fragment identifier seems like a solution. It isn't clear to me though if the fragments need to be registered explicitly, so I'll follow up with the RTP folks.

I agree an example would be useful if we want to keep this feature.

Is there an option to say: if you don't define # or ?, then you mean EVERYTHING included in the URI. If you want to select only specific parts, use # or ? to specify that?

e.g., urn:ietf:params:qlog:quic means ALL QUIC events, while urn:ietf:params:qlog:quic#recovery means ONLY the recovery events and nothing else? How does RFC 8285 manage such things?

This is an open question we should ask in the meeting

I spoke with some people in the hallways. There's a reason that RFC 8285 does it that way, due to how RTP stuff works. However, everyone seemed to agree that requiring the full expansions wasn't that onerous and was more clear. Allowing the url without those seems like a microoptimization.

There's another reason the full expansion is nice. If any documents in the future extend a namespace, then its not clear what extensions are used or not. That makes the implicit include quite insipid.

draft-ietf-quic-qlog-main-schema.md

Co-authored-by: Robin Marx <rmarx@akamai.com>

LPardue · 2024-03-19T05:42:42Z

I pushed some changes to update the text in h3, if we like that approach I will carry it over to the quic doc.

draft-ietf-quic-qlog-h3-events.md

Co-authored-by: Robin Marx <rmarx@akamai.com>

LPardue · 2024-04-01T11:36:02Z

On thinking some more, I think allowing extension of categories with new events is a complication we can avoid. Specifically, allowing different documents to extend a category risks non-unique event names if the document author is not careful with type names. For example. if ext-schema-a and ext-schema-b both extend h3 with a my-ev-type event (concating to the name h3:my-ev-type, then they'll be fine until someone tries to use both. It's going to be very hard to police event type names, especially for private extensions.

Instead, we can enforce that new schema need to define new globally-unique categories. For example, if we wanted to add new quic events in the future as part of a rollup extension schema, we could define quic-2030, recovery-2030 etc. Adding this to the guidance pushes private extensions to avoid the problem, and requires standard extensions to do it.

I pushed an update that attempts to explain all this.

rmarx

As you'll see, a few remarks, most tiny, but a few that imo should be tackled.

I'm personally not a big fan of disallowing extensions to extend existing protocol/category namespaces... I get the rationale, but I think this will cause unnecessary churn and overhead for implementers (listing all extension docs in additional_event_schema, requesting addition to IANA, tools having to decide how to validate etc.). That said... I don't really have a better solution atm to the issues this solves :(

If we do keep this, imo we do need to add some guidance on naming of new extensions for existing qlog definitions.

For example, https://www.ietf.org/archive/id/draft-ietf-tsvwg-careful-resume-07.html#name-cr_phase-event, is really a good fit for "quic:recovery", but wouldn't be able to just use that... so what should it do?

It can't just do quic-ext:recovery because that would pollute quic-ext for all other extensions... it can't do quic-rfcXYZA:recovery because juck. It might do quic-careful-resume:recovery but this should probably be recommended by the main spec to prevent a weird growth of these things going forward (UNLESS you expect all this to be caught in the IANA registration process, where expert reviews can catch quic-ext and require it be renamed to something like quic-careful-resume? even then though... a bit of prose with an example could be nice here).

rmarx · 2024-04-02T09:16:11Z

draft-ietf-quic-qlog-h3-events.md

+This document registers a new entry in the "qlog event extension schema
+identifer" registry.
+
+Extension URI:


Not sure if this is actually an issue, but IIUC, this would mean that listing the H3 events in additional_event_schemas will lead to a URI like this:

urn:ietf:params:qlog:h3#h3

Conceptually fine, but the duplication of h3 is a bit weird. Makes me wonder if in general we should go for the "full acronym" in the extension URI (i.e., http3 instead of h3, analogous to quic instead of q1)?

yeah that makes sense

how about urn:ietf:params:qlog:http#h3? That would make it easy to add support for other HTTP versions or extensions as new catagories

draft-ietf-quic-qlog-main-schema.md

rmarx · 2024-04-02T09:18:32Z

draft-ietf-quic-qlog-main-schema.md

-that specify the name (category + type) and data needed for each individual
-event. Examples include the QUIC event definitions {{QLOG-QUIC}} and HTTP/3
-event definitions {{QLOG-H3}}.
+It is not possible to extend a category with new events. Instead, extension


Suggested change

It is not possible to extend a category with new events. Instead, extension

It is not possible to extend an existing category, defined in a different document, with new events. Instead, extension

I don't think we need the "different document" qualification, there may be no document at all for something like a private extension. The blanket rule is always the same, no extension.

draft-ietf-quic-qlog-main-schema.md

rmarx · 2024-04-02T09:21:29Z

draft-ietf-quic-qlog-main-schema.md

+disambuiguated.
+
+Each extension schema is named by a URI. That URI MUST be absolute; it precisely
+identifies the format and meaning of the extension. URIs that contain a domain


Not exactly sure what the intention is of including "format" here... might be confused with "serialization format", which is certainly not the intent. Replace with a different word or remove?

lol, still a hangover from copy/paste. What we should say here is that a schema URI precisely identifies the category name and the event type(s) (the CDDL definition)

draft-ietf-quic-qlog-main-schema.md

rmarx · 2024-04-02T09:35:30Z

draft-ietf-quic-qlog-main-schema.md

+
+A log file that uses events from extension schema SHOULD list all schema
+identifiers in the `additional_event_schemas` field; see {{qlog-file-schema}}
+and {{qlog-file-seq-schema}}.


So here, I'm wondering if we should give guidance to tools on how to actually use the additional_event_schemas field? Like, they SHOULD use it to see if they support the listed event categories, but they SHOULD NOT bork on unexpected events (and rather just ignore them).

put differently: I think we need to make clear that tools/users MUST NOT treat this as a fully qualified list and expect all/none events to be present, but rather more as a hint to further improve operations.

Yeah that would be good to have.

Co-authored-by: Robin Marx <rmarx@akamai.com>

LPardue · 2024-04-02T10:46:28Z

As you'll see, a few remarks, most tiny, but a few that imo should be tackled.

I'm personally not a big fan of disallowing extensions to extend existing protocol/category namespaces... I get the rationale, but I think this will cause unnecessary churn and overhead for implementers (listing all extension docs in additional_event_schema, requesting addition to IANA, tools having to decide how to validate etc.). That said... I don't really have a better solution atm to the issues this solves :(

I don't think it's that much extra work really. An IANA registration request is as simple as an email that will be forwarded to the designated experts (probably you, me and anyone else that wants to volunteer). Lazy implementations can omit the additional schema field at the cost of risk that tools will break.

If we allowed extension to categories while only recommending that additional_event_schema is provided, we risk tools having to deal with ambiguous types, which sucks.

If we do keep this, imo we do need to add some guidance on naming of new extensions for existing qlog definitions.

For example, https://www.ietf.org/archive/id/draft-ietf-tsvwg-careful-resume-07.html#name-cr_phase-event, is really a good fit for "quic:recovery", but wouldn't be able to just use that... so what should it do?

It can't just do quic-ext:recovery because that would pollute quic-ext for all other extensions... it can't do quic-rfcXYZA:recovery because juck. It might do quic-careful-resume:recovery but this should probably be recommended by the main spec to prevent a weird growth of these things going forward (UNLESS you expect all this to be caught in the IANA registration process, where expert reviews can catch quic-ext and require it be renamed to something like quic-careful-resume? even then though... a bit of prose with an example could be nice here).

The careful resume event is a good example but I disagree about your analysis. The definition of the event leaves it completely ambiguous about what category it belongs to, so it is unclear what it's serialized name would be. You seem to assume the event is for QUIC, but careful resume is a transport-independent. So, assuming we get this PR hammered out, the careful resume document would have clearer guidance to follow about defining an extension schema. My recommendation would for it to define a new URI like urn:ietf:params:qlog:careful-resume and category identifier cr, then the event type could be phase_updated and it's serialized name would be cr:phase_updated.

rmarx · 2024-04-02T12:38:40Z

If we allowed extension to categories while only recommending that additional_event_schema is provided, we risk tools having to deal with ambiguous types, which sucks.

I agree, and that's why I said I also don't see a better solution (sadly) :)

The careful resume event is a good example but I disagree about your analysis

So ok, maybe careful-resume can get away with its own identifier outside of quic :) but then let's assume a loss-bits extension that is specific to QUIC's header and defines the loss_bits_updated event. Then it's still a bit unclear if they should have urn:ietf:params:qlog:loss-bits or urn:ietf:params:qlog:quic-loss-bits or urn:ietf:params:qlog:quic-ext-loss-bits or... (or if this even matters as much ;)) and thus if we should have a bit of guidance for that (i.e., extensions of existing protocols/categories)

LPardue · 2024-04-02T14:13:05Z

I don't think the schema identifier is that important, it's just a unique thing.

Guidance for category identifiers would be useful but I'm not sure we have enough experience to be that helpful. It should reflect the expert guidance, the the category name should be specific and unique, and also keep in mind that it can't be extended in future. So if there's a loss bit extension schema that wanted to have different categories if could have urn:ietf:params:qlog:loss-bits#quic-loss-bits and urn:ietf:params:qlog:loss-bits#sctp-loss-bits.

That does raise the question whether we should allow adding new categories to existing schema. That seems something that is OK.

LPardue requested review from rmarx, marten-seemann and lnicco as code owners March 17, 2024 23:59

Add Jonathan Lennox to acknowledgements

42d9348

rmarx requested changes Mar 18, 2024

View reviewed changes

Robin's suggestions

3b822f0

Co-authored-by: Robin Marx <rmarx@akamai.com>

This was referenced Mar 18, 2024

Discuss extensibility of extension points through type or group sockets #416

Open

additional_schema using URI/URN #329

Closed

LPardue added 5 commits March 19, 2024 03:51

additional_event_schema*s* and add example

d98119d

tweak review criteria

e8ae653

More clearly state how the H3 document defines an extension schema

ccee79b

Clarify event, catagory, and scheme relationships and multiplicity

0db49c3

s/element/schema

4f2d3ba

I can't count

36396a1

rmarx reviewed Mar 19, 2024

View reviewed changes

draft-ietf-quic-qlog-h3-events.md Outdated Show resolved Hide resolved

LPardue and others added 2 commits March 21, 2024 05:41

Update draft-ietf-quic-qlog-h3-events.md

3944349

Co-authored-by: Robin Marx <rmarx@akamai.com>

expand out the concerns about category names

b641a53

LPardue added 2 commits April 1, 2024 12:38

s/that/it

db0a608

s/QUIC/HTTP/3

889d6d4

rmarx requested changes Apr 2, 2024

View reviewed changes

Robin's suggestions extension

2735dea

Co-authored-by: Robin Marx <rmarx@akamai.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Define extension schema policy and registry #415

Define extension schema policy and registry #415

LPardue commented Mar 17, 2024

LPardue commented Mar 18, 2024

JonathanLennox commented Mar 18, 2024

rmarx left a comment

rmarx Mar 18, 2024

LPardue Mar 18, 2024

rmarx Mar 18, 2024

LPardue Mar 18, 2024

rmarx Mar 18, 2024

LPardue Mar 19, 2024

LPardue Apr 1, 2024

LPardue commented Mar 19, 2024

LPardue commented Apr 1, 2024

rmarx left a comment

rmarx Apr 2, 2024

LPardue Apr 2, 2024

LPardue May 22, 2024

rmarx Apr 2, 2024

LPardue Apr 2, 2024

rmarx Apr 2, 2024

LPardue Apr 2, 2024

rmarx Apr 2, 2024

LPardue Apr 2, 2024

LPardue commented Apr 2, 2024

rmarx commented Apr 2, 2024 •

edited

LPardue commented Apr 2, 2024


		## Extended Event Schema

		New events SHOULD be defined using an extension schema, using the annotations

	New events SHOULD be defined using an extension schema, using the annotations
	New event documents SHOULD be defined using an extension schema, using the annotations

	It is not possible to extend a category with new events. Instead, extension
	It is not possible to extend an existing category, defined in a different document, with new events. Instead, extension

Define extension schema policy and registry #415

Are you sure you want to change the base?

Define extension schema policy and registry #415

Conversation

LPardue commented Mar 17, 2024

LPardue commented Mar 18, 2024

JonathanLennox commented Mar 18, 2024

rmarx left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LPardue commented Mar 19, 2024

LPardue commented Apr 1, 2024

rmarx left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LPardue commented Apr 2, 2024

rmarx commented Apr 2, 2024 • edited

LPardue commented Apr 2, 2024

rmarx commented Apr 2, 2024 •

edited