[Resolved] CloudEvents type attribute for our events

[erkist]

The following is stated for the type attribute of events in the CloudEvents spec:

https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#type

This attribute contains a value describing the type of event related to the originating occurrence. Often this attribute is used for routing, observability, policy enforcement, etc. The format of this is producer defined and might include information such as the version of the type - see Versioning of Attributes in the Primer for more information.

SHOULD be prefixed with a reverse-DNS name. The prefixed domain dictates the organization which defines the semantics of this event type.

This leads me to conclude that the recommendation for us would be something along the lines of "foundation.cd.abc.xyz.v1", but it is only a recommendation.

Should we go for the recommendation here, or should we come up with own guidelines for event types?

[erkist]

My personal preference would be cdf.[bucket].[event_type_name].[version] which would lead to event types such as:

cdf.deployment.environment_created.v1 and cdf.source.change_created.v1

While not the prettiest, it is very deterministic, in that every event type has exactly four elements, separated by dots.

[erkist]

I am generally against abbreviations, but if they can be considered well-known and don't cause any confusion I won't cause a fuzz about it.
"env" for "environment", "src" for "source", "svc" for "service" and "cfg" for "configuration" are examples I could be OK with.
"ts" for "test suite", "plr" for "pipeline run" and "dep" for deployment are more likely to cause confusion.

[salaboy]

@erkist ""env" for "environment", "src" for "source", "svc" for "service" and "cfg" for "configuration" + 1 for those..

and yeah for this causing confusion "ts" for "test suite", "plr" for "pipeline run" and "dep".

I think that we are in the same page with this one.

[m-linner-ericsson]

Seems I have a lot of contradicting thoughts. Hope I don't sound too discouraging...

• I think we need to explain why we need to shorten things as it becomes more difficult to read. I would prefer to spell them out instead.
• What is the idea of having them sorted into buckets? What would be the consequence if we decide to move them or rename the buckets? Isn't it more future proof to just have the event name?
• Regarding versions in the name. If you would like to have schema to validate the events against would it be easier if the version was a field of its own?

[erkist]

I think we need to explain why we need to shorten things as it becomes more difficult to read. I would prefer to spell them out instead.

I would also prefer writing it out, but if we agree on some non-confusing abbreviations I won't complain.

What is the idea of having them sorted into buckets? What would be the consequence if we decide to move them or rename the buckets? Isn't it more future proof to just have the event name?

I am generally in favor of name-spacing, especially as the number of events goes up. I do agree about the issue with moving and renaming buckets, so we'd need to be really sure about those names and the types of events they should contain.

Regarding versions in the name. If you would like to have schema to validate the events against would it be easier if the version was a field of its own?

Perhaps slightly easier, yes, but having the version at a fixed position (4th) in the event type syntax is not very hard to handle either. But the only reason I chose that syntax is that is stated as an example in the CloudEvents spec. However, the spec itself states that it has no strong opinions on how to handle versioning https://github.com/cloudevents/spec/blob/v1.0.1/primer.md#versioning-of-attributes

[afrittoli]

Seems I have a lot of contradicting thoughts. Hope I don't sound too discouraging...

Diversity of opinions will hopefully help us move in a good direction :)

• I think we need to explain why we need to shorten things as it becomes more difficult to read. I would prefer to spell them out instead.

I don't think there is any technical constraint that would force us to shorten name, and in general I'm in favour of spelled out names. Aspects we might consider:

• people writing filters or other logic about the events might be slightly more prone to spelling errors with longer names
• the event type is likely to end up in indexes in event storages or databases of some kind, and to be indexed upon. It may be used for filtering upon large amounts of events. The size of the string is likely to have an impact on the size and performance of the index and filter operations

That said, I don't have numbers to really quantify what the impact might be.

• What is the idea of having them sorted into buckets? What would be the consequence if we decide to move them or rename the buckets? Isn't it more future proof to just have the event name?

Buckets might help human to reason about events, since events might be too many to consider all at once. Buckets in the event types help with selection and filtering logic, as they allow to respond to group of events in one rule.
On the flip side, buckets may not be future proof, and will end up being somewhat controversial, as they l most likely feel wrong for someone, or defy someone's perception.

I think the initial buckets will help identify and reason about the events, but the categories in the event types will have to be more specific, i.e. "build", "test", "deploy", "scan", "sign" etc.

• Regarding versions in the name. If you would like to have schema to validate the events against would it be easier if the version was a field of its own?

The cloud events spec does not say much about versions: https://github.com/cloudevents/spec/blob/v1.0.1/primer.md#versioning-of-attributes.
In Tekton I chose to include the version number in the type following one of the examples from the spec, but I'm not necessarily advocating for that approach for our CD events.
We will produce a spec, which will have versions, and events will have to match a specific version - i.e. a system might support v1 or v2 of our spec, but not a mix of the two. Events will have to include that version somewhere. If not in the event type string, in some other header.

It feels like versioning might warrant a discussion of its own?

[afrittoli]

Link to the original comment: https://github.com/cdfoundation/sig-events/pull/5/files#r588264728

[afrittoli]

I'm not sure about having the CDF in the event types.
Nothing against the CDF, only I think the standard should have its own brand and the name should be associated with it.
I liked @erkist idea to claim our own domain name, so I think we should:

• find a good (and cool 😎) name for our standard
• claim a DNS domain
• setup a website with an intro to the standard and links to github (see https://cloudevents.io/)
• use the reverse DNS domain for event types

[salaboy]

@afrittoli why do you think that this shouldn't reference the CD.foundation more directly? There are two different things here: CloudEvents and the vocabulary which doesn't needs to be attached to the implementation. For the vocabulary, I don't see anything wrong with prefixing and having a reference to the CD.foundation. For CloudEvents, we are aiming more for an extension. I would try to avoid doing something that generic that looks like doesn't have any organization behind it. But you might have some concrete ideas or cons of doing it so, can you please share?

[erkist]

Resolved in https://github.com/cdfoundation/sig-events/blob/main/cde/sdk/go/pkg/cdf/events/event_types.go with the format
PipelineRunStartedEventV1 CDEventType = "cd.pipelinerun.started.v1"