From e77747bce39b7adc8d8455f7fd1cdfd9fc483e80 Mon Sep 17 00:00:00 2001 From: Nev Wylie <54870357+MSNev@users.noreply.github.com> Date: Thu, 28 Sep 2023 13:49:53 -0700 Subject: [PATCH 1/5] Project Tracking: Event API/Sdk/Definition Working Group --- projects/event-api.md | 90 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 projects/event-api.md diff --git a/projects/event-api.md b/projects/event-api.md new file mode 100644 index 00000000..ff833673 --- /dev/null +++ b/projects/event-api.md @@ -0,0 +1,90 @@ +### Description + +The Client / RUM Sig is looking to finalize, complete and resolve the outstanding issues / PR's that exist around the Event API / SDK and the Semantic Conventions that defines what an "event" is. + +* Defined, identifying an `event`) +* Created (API / Sdk) +* will be created from Describe the goals, objectives, and requirements for the project. This include the motivations for starting the project now, as opposed to later. + +### Project Board + +Once approved by TC, a project should be managed using a GitHub project board. This project board should be pre-populated with issues that cover all known deliverables, organized by timeline milestones. + +A [Technical Committee](https://github.com/open-telemetry/community/blob/main/community-members.md#technical-committee) (TC) member associated with the project can create the board, along with a new project-specific GitHub label to automatically associate issues and PRs with the project. The project lead and all other relevant project members should have edit access to the board. + +Once created, please link to the project board here. + +Preemptively created a board with the relevant and related issues +https://github.com/orgs/open-telemetry/projects/65 + +### Deliverables + +Resolve the outstanding Event Issues / PR's which will define +* What is an event? What does an event look like (what attributes identify it as an event) so that vendors, backends can perform any necessary routing, translation or storage. +* How are events transported (Logs Only, Logs / Span Event, etc) +* The semantic conventions to follow for defining "known" events + * Reserved (known) prefix's (either as the domain or name prefix) (possible known prefixes: `otel.`, `k8s.`, `azure.`, `aws.`, `ecs.`, `browser.`, `mobile.`, etc) all other "unknown" domains should/can be considered as "custom" by venders / backends. + * How / where are these are defined in semantic conventions (.yml) + * Updating tooling to properly handle the conventions + * Note: This group is not responsible for definition the semantic conventions of All domain specific events, only "how" those events will be represented / transported as an "event". +* Define when an event should be used vs a `Span` or `LogRecord` + +We have been working on the definition already as part of the Client / RUM Sig and prototypes current exist in JavaScript in the web sandbox repo using `event.data` as the transport mechanism for the "Payload" of the event. + +* JS prototype of setting data https://github.com/open-telemetry/opentelemetry-sandbox-web-js/blob/auto-instrumentation-poc/pkgs/api-events/src/types/Event.ts#L34 +* Swift setData() API https://github.com/open-telemetry/opentelemetry-swift/blob/main/Sources/OpenTelemetrySdk/Logs/LogRecordBuilderSdk.swift#L66 + +### Staffing / Help Wanted + +Who is currently planning to work on the project? If a project requires specialized domain expertise, please list it here. If a project is missing a critical mass of people in order to begin work, please clarify. + +#### Required staffing + +* Need: TC members (At least two sponsoring TC members.) +* Need: Scheduled meeting where TC members and domain experts can attend +* Need: more domain experts willing to define the OTel Event standard +* Need: engineers willing to write prototypes in at least one more language other than JavaScript. Language should be fairly different from JavaScript. +* Need: maintainers or approvers from those languages committed to reviewing the prototypes. + +@MSNev Nev Wylie - FTE project lead / browser domain expert +@martinkuba Martin Kuba - Domain expert and Maintainer / approver for JS +@scheler Santosh Cheler - Domain expert +@dennisme Matthew Dennison - Golang sdk +@patrickhousley Patrick Housley - Event domain expert +@breedx-splk Jason Plumb - Event domain expert + +### Meeting Times + +__Once a project is started, the working group should meet regularly for discussion. These meeting times should be posted on the OpenTelemetry public calendar.__ + +TBD + +### Timeline + +As several items are already underway, here is the optimistic (Ideal) timelines + +By End of 2023 + +* Define the shape of an event (attributes that represent an event) +* General of the semantic conventions (known/reserved domains) +* Location of domain specific semantic conventions +* Accepted definition of Event API / SDK +* Resolved whether Span Events will / can also represent an Event (Not necessarily "how", just a go/no-go call) +* How Application / Custom Events will be supported +* Initial Domain specific events using the Event API/SDK in multiple languages (this is already underway) + +By end of June 2024 + +* Updated tooling for semantic conventions, supporting generation for domain specific events +* Multiple implementations of Event API / SDK +* Mark the Event API/SDK as Stable + +Dissolve this specific working group. + +### Linked Issues and PRs + +See the project board for a collection of Issues related to the project. + +### Labels + +Additional labels to be able to identify "Event" related Issues / PR's would be ideal to help with tracking. From dd08aad98662fcc617c5104c25b329ee65619959 Mon Sep 17 00:00:00 2001 From: Nev Wylie <54870357+MSNev@users.noreply.github.com> Date: Fri, 6 Oct 2023 14:28:08 -0700 Subject: [PATCH 2/5] Integrate feedback, simplifying the definition --- projects/event-api.md | 82 ++++++++++++++++++------------------------- 1 file changed, 35 insertions(+), 47 deletions(-) diff --git a/projects/event-api.md b/projects/event-api.md index ff833673..c3051f25 100644 --- a/projects/event-api.md +++ b/projects/event-api.md @@ -2,9 +2,8 @@ The Client / RUM Sig is looking to finalize, complete and resolve the outstanding issues / PR's that exist around the Event API / SDK and the Semantic Conventions that defines what an "event" is. -* Defined, identifying an `event`) -* Created (API / Sdk) -* will be created from Describe the goals, objectives, and requirements for the project. This include the motivations for starting the project now, as opposed to later. +* Defined, identifying an `event` +* Created (API / SDK) ### Project Board @@ -12,31 +11,16 @@ Once approved by TC, a project should be managed using a GitHub project board. T A [Technical Committee](https://github.com/open-telemetry/community/blob/main/community-members.md#technical-committee) (TC) member associated with the project can create the board, along with a new project-specific GitHub label to automatically associate issues and PRs with the project. The project lead and all other relevant project members should have edit access to the board. -Once created, please link to the project board here. - -Preemptively created a board with the relevant and related issues -https://github.com/orgs/open-telemetry/projects/65 +Project Board: https://github.com/orgs/open-telemetry/projects/65 ### Deliverables Resolve the outstanding Event Issues / PR's which will define -* What is an event? What does an event look like (what attributes identify it as an event) so that vendors, backends can perform any necessary routing, translation or storage. -* How are events transported (Logs Only, Logs / Span Event, etc) -* The semantic conventions to follow for defining "known" events - * Reserved (known) prefix's (either as the domain or name prefix) (possible known prefixes: `otel.`, `k8s.`, `azure.`, `aws.`, `ecs.`, `browser.`, `mobile.`, etc) all other "unknown" domains should/can be considered as "custom" by venders / backends. - * How / where are these are defined in semantic conventions (.yml) - * Updating tooling to properly handle the conventions - * Note: This group is not responsible for definition the semantic conventions of All domain specific events, only "how" those events will be represented / transported as an "event". -* Define when an event should be used vs a `Span` or `LogRecord` - -We have been working on the definition already as part of the Client / RUM Sig and prototypes current exist in JavaScript in the web sandbox repo using `event.data` as the transport mechanism for the "Payload" of the event. - -* JS prototype of setting data https://github.com/open-telemetry/opentelemetry-sandbox-web-js/blob/auto-instrumentation-poc/pkgs/api-events/src/types/Event.ts#L34 -* Swift setData() API https://github.com/open-telemetry/opentelemetry-swift/blob/main/Sources/OpenTelemetrySdk/Logs/LogRecordBuilderSdk.swift#L66 - -### Staffing / Help Wanted -Who is currently planning to work on the project? If a project requires specialized domain expertise, please list it here. If a project is missing a critical mass of people in order to begin work, please clarify. +* Refine / stabilize event data model describing what an event is, the semantic meaning of event fields, and how they are sent over the network. +* Pave the way for defining event semantic conventions, allowing their schemas to be described in YAML and incorporated into build-tools. +* Define select event semantic conventions, establishing patterns for future event semantic conventions to follow. +* Refine / stabilize event API and any associated features in the SDK. #### Required staffing @@ -46,40 +30,44 @@ Who is currently planning to work on the project? If a project requires speciali * Need: engineers willing to write prototypes in at least one more language other than JavaScript. Language should be fairly different from JavaScript. * Need: maintainers or approvers from those languages committed to reviewing the prototypes. -@MSNev Nev Wylie - FTE project lead / browser domain expert -@martinkuba Martin Kuba - Domain expert and Maintainer / approver for JS -@scheler Santosh Cheler - Domain expert -@dennisme Matthew Dennison - Golang sdk -@patrickhousley Patrick Housley - Event domain expert -@breedx-splk Jason Plumb - Event domain expert +Project lead(s): -### Meeting Times +* @MSNev (JavaScript) -__Once a project is started, the working group should meet regularly for discussion. These meeting times should be posted on the OpenTelemetry public calendar.__ +Sponsoring TC Members: -TBD +* @tigrannajaryan +* @jack-berg -### Timeline +Contributing Engnieers: -As several items are already underway, here is the optimistic (Ideal) timelines +* @martinkuba (JavaScript) +* @scheler +* @patrickhousley +* @breedx-splk -By End of 2023 +Implementation Engineers: +* @dennisme (Golang) -* Define the shape of an event (attributes that represent an event) -* General of the semantic conventions (known/reserved domains) -* Location of domain specific semantic conventions -* Accepted definition of Event API / SDK -* Resolved whether Span Events will / can also represent an Event (Not necessarily "how", just a go/no-go call) -* How Application / Custom Events will be supported -* Initial Domain specific events using the Event API/SDK in multiple languages (this is already underway) +Implementation Maintainers / Approvers: -By end of June 2024 +* @MSNev +* @martinkuba +* @scheler + +### Meeting Times + +__Once a project is started, the working group should meet regularly for discussion. These meeting times should be posted on the OpenTelemetry public calendar.__ + +TBD + +### Timeline -* Updated tooling for semantic conventions, supporting generation for domain specific events -* Multiple implementations of Event API / SDK -* Mark the Event API/SDK as Stable +By end of 2023 -Dissolve this specific working group. +* Refine data model (By end of 2023) +* Accommodate events in semantic conventions +* Refine / stabilize API & SDKs ### Linked Issues and PRs From 1ed025d368263abf700d523dc9c8252d5bb915b1 Mon Sep 17 00:00:00 2001 From: Nev Wylie <54870357+MSNev@users.noreply.github.com> Date: Wed, 11 Oct 2023 17:34:59 -0700 Subject: [PATCH 3/5] Remove unnecessary bullet points --- projects/event-api.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/projects/event-api.md b/projects/event-api.md index c3051f25..4e99672b 100644 --- a/projects/event-api.md +++ b/projects/event-api.md @@ -2,9 +2,6 @@ The Client / RUM Sig is looking to finalize, complete and resolve the outstanding issues / PR's that exist around the Event API / SDK and the Semantic Conventions that defines what an "event" is. -* Defined, identifying an `event` -* Created (API / SDK) - ### Project Board Once approved by TC, a project should be managed using a GitHub project board. This project board should be pre-populated with issues that cover all known deliverables, organized by timeline milestones. From 95255b7b7a4dd4ebadc0f28d5d53074c76737355 Mon Sep 17 00:00:00 2001 From: Nev Wylie <54870357+MSNev@users.noreply.github.com> Date: Thu, 12 Oct 2023 15:38:48 -0700 Subject: [PATCH 4/5] More Updates --- projects/event-api.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/projects/event-api.md b/projects/event-api.md index 4e99672b..15cfcb5e 100644 --- a/projects/event-api.md +++ b/projects/event-api.md @@ -4,10 +4,6 @@ The Client / RUM Sig is looking to finalize, complete and resolve the outstandin ### Project Board -Once approved by TC, a project should be managed using a GitHub project board. This project board should be pre-populated with issues that cover all known deliverables, organized by timeline milestones. - -A [Technical Committee](https://github.com/open-telemetry/community/blob/main/community-members.md#technical-committee) (TC) member associated with the project can create the board, along with a new project-specific GitHub label to automatically associate issues and PRs with the project. The project lead and all other relevant project members should have edit access to the board. - Project Board: https://github.com/orgs/open-telemetry/projects/65 ### Deliverables @@ -21,7 +17,6 @@ Resolve the outstanding Event Issues / PR's which will define #### Required staffing -* Need: TC members (At least two sponsoring TC members.) * Need: Scheduled meeting where TC members and domain experts can attend * Need: more domain experts willing to define the OTel Event standard * Need: engineers willing to write prototypes in at least one more language other than JavaScript. Language should be fairly different from JavaScript. From 5c1a24b810ef81fcf35b56071f5540e420ed3ea6 Mon Sep 17 00:00:00 2001 From: Nev Wylie <54870357+MSNev@users.noreply.github.com> Date: Tue, 24 Oct 2023 09:34:13 -0700 Subject: [PATCH 5/5] Set meeting time --- projects/event-api.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/projects/event-api.md b/projects/event-api.md index 15cfcb5e..4748b327 100644 --- a/projects/event-api.md +++ b/projects/event-api.md @@ -17,7 +17,6 @@ Resolve the outstanding Event Issues / PR's which will define #### Required staffing -* Need: Scheduled meeting where TC members and domain experts can attend * Need: more domain experts willing to define the OTel Event standard * Need: engineers willing to write prototypes in at least one more language other than JavaScript. Language should be fairly different from JavaScript. * Need: maintainers or approvers from those languages committed to reviewing the prototypes. @@ -49,9 +48,7 @@ Implementation Maintainers / Approvers: ### Meeting Times -__Once a project is started, the working group should meet regularly for discussion. These meeting times should be posted on the OpenTelemetry public calendar.__ - -TBD +SIG meeting times: Friday 10am - 11am PT ### Timeline