Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Propose holistic simplification of source- attributes #129

Closed
wants to merge 3 commits into from
Closed

Propose holistic simplification of source- attributes #129

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c952748
Propose holistic simplification of source- attributes
inlined Mar 27, 2018
87e270b
Rename 'attributes' to 'labels'
inlined Mar 28, 2018
35b46fa
Fix poor grammar
inlined Mar 29, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 39 additions & 33 deletions spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,27 +107,19 @@ the event data. The context might also need to be serialized with the event
data for some use cases (e.g. a JSON implementation might use one JSON object
that contains both context and data).

### namespace
* Type: String
* Description: Identifier that uniquely identifies the organization publishing
the event.
* Constraints:
* REQUIRED
* MUST be a non-empty string
* Examples:
* kafka.apache.org
* com.microsoft.azure

### event-type
* Type: String
* Description: Type of the event `data`. Producers can specify the format of
this, depending on their service. This enables the interpretation of `data`,
and can be used for routing, policy and more.
* Description: Type of occurrence which has happened. The event type MUST be
namespaced with a package based on the reverse-DNS of a domain associated
with the software that produced the event. This MAY be used for routing,
observability, policy enforcement, etc.
* Constraints:
* REQUIRED
* MUST be a non-empty string
* MUST be prefixed with a reverse-DNS name associated with the software that
produces the event
* Examples:
* customer.created
* com.github.pull.create
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpicking: com.github.pull.create reads as a command rather than an event that took place.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: github docs use "create" for a notification that something has been created... not that we need to conform to some specific vendor. We could include a few divergent examples to be clear that we're not mandating anything or consider some guidance about naming if someone wants to see if there's a trend in existing implementations or other spec we want to borrow from.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agree this is a nit, and suggest it could be addressed in a follow-on PR

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As a consumer of an event, "event-type", to me, denotes whether it is a storage event or an messaging event or a timer event , etc. Then depending on the type of event, it could have different properties. For example, a storage event could have properties like "bucket name", "action performed on that bucket (created or update or delete)", a messaging event could have properties like "topic of the message".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@SeanFeldman I lean 20% more towards infinitive tense for a few reasons:

  1. It's nice that these names can be reused for other policies in the source software. E.g. only some developers will have "com.github.pull.create" permission in a repository.
  2. There seems to be precedent today for events to be named in the infinitive. E.g. onClick rather than onClicked

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First scenario is describing a permision, not an event. Permission to create a PR.
Second example is historical OnClick as an event handler for the click event. You'd not call it "WhenClick", but rather "WhenClicked" if that would be the convention back in the day.

I might remain in the minority with my belief that an event is a manifistation of something immutable that happened and therefore should be described in the past tense 🙂


### event-type-version
* Type: String
Expand All @@ -146,32 +138,46 @@ that contains both context and data).
* REQUIRED
* MUST be a non-empty string

### source
* Type: Object
* Description: This describes the software instance that emits the event at
runtime (i.e. the producer). It contains sub-properties (listed below)
* Constraints:
* REQUIRED
* MUST contain at least one non-empty sub-property.

### source-type
### source-authority
* Type: String
* Description: Type of the event source. Providers define list of event
sources.
* Description: The URI authority component of the source software.
* Constraints:
* REQUIRED
* MUST be a non-empty string
* MUST conform to the
["authority" component](https://tools.ietf.org/html/rfc3986#section-3.2)
of the URI spec
* Examples:
* s3
* github.com
* myenterpriseGitHubInstall.company.com

### source-id
* Type: String
* Description: ID of the event source.
### source-path
* Type: string
* Description: The URI path component of the resource that emitted an event.
* Constraints:
* REQUIRED
* MUST be a non-empty string
* OPTIONAL
* If present, MUST conform to the "path-rootless" grammar of the
[URI spec](https://tools.ietf.org/html/rfc3986#section-3.3)
* Examples:
* my.s3.bucket
* myorg/myrepo
* my/long/ftp/path.jpg

### source-labels
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do they refer to the "properties" of the source?
If so, I feel "source-properties" is a better name since property feels something intrinsic while "label" feels "add-on" .

Is it TRUE that different event source types could have different source-labels? Are we going to leave the definition of source-labels to event producers?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I proposed source-labels because that's the use case I had in mind. I'm leaving myself open to being convinced that other systems would be able to add their own labels as well. If we allow this, we should have a discussion about whether they are explicitly annotating the source (letting us keep it source-labels) or if they're adding other annotations that shouldn't be tied to the source.

The labels that I'm used to interacting with are under the developer's control, though the developer's software might automatically manage some labels with the developer's credentials. Some examples I've used in the past:

  • Google was rolling out some new infrastructure near a major conference. They told speakers to add a specific label on our project if we wanted to defer migration. Because projects (like many resources on Google Cloud) support labels, the team was able to skip over projects that would be used for on-stage demos without any coordination from any other team or a new permanent attribute on their API like "defer_2017_rollout": true
  • Firebase releases its own simplified tooling on top of Google Cloud Functions, which provides our customers with a golden road. We want to track when customers use this tooling, so we add a label that says our CLI managed the deploy. Since our CLI experience is K8S style (the customer gives us source and we make the project look like that source), we use this label to avoid deleting functions that are being managed with other tools.

You seem to know dramatically more about IoT and can interpret how the label concept would apply there. It seems totally reasonable to me that the user portal for managing devices would manage labels on those devices. It's also true that there could be a bit of disconnect originally from vendors that they use different label names to refer to similar concepts. Personally, I think this problem will be smaller in practice than deciding that every IoT device can only be correlated by one property.

* Type: Map <String, String>
* Description: Labels associated with the resource that emitted the event.
This allows filtering or routing based on non-hierarchical source metadata.
This is intended to include (but is not limited to) "labels" in cloud
platforms like AWS or Kubernetes.
* Constraints:
* OPTIONAL
* Keys MUST match the regular expression `[_.a-z0-9]+`
* Keys SHOULD use the character "." is as namespace separator
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Leave out "is"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

whoops. This is what happens when I copy+paste from other standards.

* Values MUST use URI-safe characters
* Examples:
* {
"sensor.configuration": "WINDOW"
"sensor.location": "deployments/house1/window3"
}

### event-id
* Type: String
Expand Down