From d9b36e86ed9abb6d9942067a1fc33824953ac763 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Tue, 12 Jul 2022 08:56:19 -0700 Subject: [PATCH 1/4] draft of navigation and resource browser events --- .../semantic_conventions/events/README.md | 7 ++++ .../events/browser/README.md | 9 +++++ .../events/browser/navigation.md | 32 +++++++++++++++++ .../events/browser/resource.md | 35 +++++++++++++++++++ .../semantic_conventions/events/events.md | 15 ++++++++ 5 files changed, 98 insertions(+) create mode 100644 specification/logs/semantic_conventions/events/README.md create mode 100644 specification/logs/semantic_conventions/events/browser/README.md create mode 100644 specification/logs/semantic_conventions/events/browser/navigation.md create mode 100644 specification/logs/semantic_conventions/events/browser/resource.md create mode 100644 specification/logs/semantic_conventions/events/events.md diff --git a/specification/logs/semantic_conventions/events/README.md b/specification/logs/semantic_conventions/events/README.md new file mode 100644 index 00000000000..4dec653cb34 --- /dev/null +++ b/specification/logs/semantic_conventions/events/README.md @@ -0,0 +1,7 @@ +# Events semantic conventions + +Events in OpenTelemetry are a subset of logs with specific set of semantic conventions. + +Each events MUST follow the [`events.*`](./events.md) semantic conventions, and it must follow semantic conventions specific for the type of event + +Each event has a name (`event.name`) attribute, which uniquely identifies the type of the event. In addition \ No newline at end of file diff --git a/specification/logs/semantic_conventions/events/browser/README.md b/specification/logs/semantic_conventions/events/browser/README.md new file mode 100644 index 00000000000..6506cd67dbd --- /dev/null +++ b/specification/logs/semantic_conventions/events/browser/README.md @@ -0,0 +1,9 @@ +# Browser events semantic conventions + +All browser events MUST have the `event.domain` attribute set to `browser`. + +| Event name | Description | +|---|---| +| [`navigation`](./navigation.md) | Represents a page navigation event with values from the Navigation Timing API | +| [`resource`](./resource.md) | Represents a resource with values from the Resource Timing API | + \ No newline at end of file diff --git a/specification/logs/semantic_conventions/events/browser/navigation.md b/specification/logs/semantic_conventions/events/browser/navigation.md new file mode 100644 index 00000000000..d188df566fb --- /dev/null +++ b/specification/logs/semantic_conventions/events/browser/navigation.md @@ -0,0 +1,32 @@ +# Navigation + +**Status**: [Experimental](../../../../document-status.md) + +**type:** `navigation` + +**Description**: Represents a browser navigation event. + + +| Attribute | Type | Value | Requirement Level | +|---|---|---|---|---| +| `event.name` | string | `navigation` | Required | +| `event.domain | string | `browser` | Required | + + +Additional attributes are mapped from the (Navigation Timing API)[https://www.w3.org/TR/navigation-timing-2/#sec-PerformanceNavigationTiming]. + +This list is not exhaustive and is listed as an example. All numeric and string values thar are provided by the Navigation Timing API SHOULD be included. + + +| Attribute | Type | Example | Requirement Level | +|---|---|---|---|---| +| `unloadEventStart` | numeric | 0 | Optional | +| `unloadEventEnd` | numeric | 0 | Optional | +| `domInteractive` | numeric | 0 | Optional | +| `domContentLoadedEventStart` | numeric | 0 | Optional | +| `domContentLoadedEventStart` | numeric | 0 | Optional | +| `domComplete` | numeric | 0 | Optional | +| `loadEventStart` | numeric | 0 | Optional | +| `loadEventEnd` | numeric | 0 | Optional | +| `type` | string | `navigate`; `reload`; `back_forward` | Optional | +| `redirectCount` | numeric | 0 | Optional | diff --git a/specification/logs/semantic_conventions/events/browser/resource.md b/specification/logs/semantic_conventions/events/browser/resource.md new file mode 100644 index 00000000000..d6040f1e23b --- /dev/null +++ b/specification/logs/semantic_conventions/events/browser/resource.md @@ -0,0 +1,35 @@ +# Navigation + +**Status**: [Experimental](../../../../document-status.md) + +**type:** `resource` + +**Description**: Represents a resource observed by the browser. + + +| Attribute | Type | Value | Requirement Level | +|---|---|---|---|---| +| `event.name` | string | `resource` | Required | +| `event.domain | string | `browser` | Required | + + +Additional attributes are mapped from the (Resource Timing API)[https://www.w3.org/TR/resource-timing-2/#sec-performanceresourcetiming]. + +This list is not exhaustive and is listed as an example. All numeric and string values thar are provided by the Resource Timing API SHOULD be included. + +| Attribute | Type | Example | Requirement Level | +|---|---|---|---|---| +| `redirectStart` | numeric | 0 | Optional | +| `redirectEnd` | numeric | 0 | Optional | +| `fetchStart` | numeric | 0 | Optional | +| `domainLookupStart` | numeric | 0 | Optional | +| `domainLookupEnd` | numeric | 0 | Optional | +| `connectStart` | numeric | 0 | Optional | +| `connectEnd` | numeric | 0 | Optional | +| `secureConnectionStart` | numeric | 0 | Optional | +| `requestStart` | numeric | 0 | Optional | +| `responseStart` | numeric | 0 | Optional | +| `responseEnd` | numeric | 0 | Optional | +| `transferSize` | numeric | 0 | Optional | +| `encodedBodySize` | numeric | 0 | Optional | +| `decodedBodySize` | numeric | 0 | Optional | diff --git a/specification/logs/semantic_conventions/events/events.md b/specification/logs/semantic_conventions/events/events.md new file mode 100644 index 00000000000..67412f32d34 --- /dev/null +++ b/specification/logs/semantic_conventions/events/events.md @@ -0,0 +1,15 @@ +# Event + +**Status**: [Experimental](../../../document-status.md) + +**type:** `event` + +**Description**: All events are described by these attributes. + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `event.name` | string | The event name that uniquely identifies the type of the event within the domain. | `exception`; `interaction` | Required | +| `event.domain | string | Identifies the group of related events. Each event within a domain MUST have a unique value for the event.name attribute. | `browser`; `mobile` | Recommended | +| `event.data` | any | Some events/domains may choose to send event attributes as an object or serialized string. | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36` | Optional | + From 1ccbe28b58c6c4ee74014fd43e6f61d0c125d556 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Tue, 12 Jul 2022 08:59:31 -0700 Subject: [PATCH 2/4] fixing tables --- .../logs/semantic_conventions/events/browser/navigation.md | 4 ++-- .../logs/semantic_conventions/events/browser/resource.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/logs/semantic_conventions/events/browser/navigation.md b/specification/logs/semantic_conventions/events/browser/navigation.md index d188df566fb..fc5661abefc 100644 --- a/specification/logs/semantic_conventions/events/browser/navigation.md +++ b/specification/logs/semantic_conventions/events/browser/navigation.md @@ -8,7 +8,7 @@ | Attribute | Type | Value | Requirement Level | -|---|---|---|---|---| +|---|---|---|---| | `event.name` | string | `navigation` | Required | | `event.domain | string | `browser` | Required | @@ -19,7 +19,7 @@ This list is not exhaustive and is listed as an example. All numeric and string | Attribute | Type | Example | Requirement Level | -|---|---|---|---|---| +|---|---|---|---| | `unloadEventStart` | numeric | 0 | Optional | | `unloadEventEnd` | numeric | 0 | Optional | | `domInteractive` | numeric | 0 | Optional | diff --git a/specification/logs/semantic_conventions/events/browser/resource.md b/specification/logs/semantic_conventions/events/browser/resource.md index d6040f1e23b..85b3a66d3b2 100644 --- a/specification/logs/semantic_conventions/events/browser/resource.md +++ b/specification/logs/semantic_conventions/events/browser/resource.md @@ -8,7 +8,7 @@ | Attribute | Type | Value | Requirement Level | -|---|---|---|---|---| +|---|---|---|---| | `event.name` | string | `resource` | Required | | `event.domain | string | `browser` | Required | @@ -18,7 +18,7 @@ Additional attributes are mapped from the (Resource Timing API)[https://www.w3.o This list is not exhaustive and is listed as an example. All numeric and string values thar are provided by the Resource Timing API SHOULD be included. | Attribute | Type | Example | Requirement Level | -|---|---|---|---|---| +|---|---|---|---| | `redirectStart` | numeric | 0 | Optional | | `redirectEnd` | numeric | 0 | Optional | | `fetchStart` | numeric | 0 | Optional | From 558a144efcec94571f0c3b3b09d2d28f26f04a22 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Tue, 12 Jul 2022 15:32:27 -0700 Subject: [PATCH 3/4] formatting changes, examples, updated requirement level --- .../events/browser/navigation.md | 25 +++++++------- .../events/browser/resource.md | 33 ++++++++++--------- .../semantic_conventions/events/events.md | 4 +-- 3 files changed, 32 insertions(+), 30 deletions(-) diff --git a/specification/logs/semantic_conventions/events/browser/navigation.md b/specification/logs/semantic_conventions/events/browser/navigation.md index fc5661abefc..3418adb4145 100644 --- a/specification/logs/semantic_conventions/events/browser/navigation.md +++ b/specification/logs/semantic_conventions/events/browser/navigation.md @@ -10,23 +10,24 @@ | Attribute | Type | Value | Requirement Level | |---|---|---|---| | `event.name` | string | `navigation` | Required | -| `event.domain | string | `browser` | Required | +| `event.domain` | string | `browser` | Required | -Additional attributes are mapped from the (Navigation Timing API)[https://www.w3.org/TR/navigation-timing-2/#sec-PerformanceNavigationTiming]. +Additional attributes are mapped from the [Navigation Timing API](https://www.w3.org/TR/navigation-timing-2/#sec-PerformanceNavigationTiming). This list is not exhaustive and is listed as an example. All numeric and string values thar are provided by the Navigation Timing API SHOULD be included. | Attribute | Type | Example | Requirement Level | |---|---|---|---| -| `unloadEventStart` | numeric | 0 | Optional | -| `unloadEventEnd` | numeric | 0 | Optional | -| `domInteractive` | numeric | 0 | Optional | -| `domContentLoadedEventStart` | numeric | 0 | Optional | -| `domContentLoadedEventStart` | numeric | 0 | Optional | -| `domComplete` | numeric | 0 | Optional | -| `loadEventStart` | numeric | 0 | Optional | -| `loadEventEnd` | numeric | 0 | Optional | -| `type` | string | `navigate`; `reload`; `back_forward` | Optional | -| `redirectCount` | numeric | 0 | Optional | +| `name` | string | `https://example.com/a/b` | Recommended | +| `unloadEventStart` | double | 0 | Recommended | +| `unloadEventEnd` | double | 0 | Recommended | +| `domInteractive` | double | 1002.34 | Recommended | +| `domContentLoadedEventStart` | double | 1423.54 | Recommended | +| `domContentLoadedEventEnd` | double | 1428.51 | Recommended | +| `domComplete` | double | 1512.43 | Recommended | +| `loadEventStart` | double | 1589.23 | Recommended | +| `loadEventEnd` | double | 1599.21 | Recommended | +| `type` | string | `navigate`; `reload`; `back_forward` | Recommended | +| `redirectCount` | int | 0 | Recommended | diff --git a/specification/logs/semantic_conventions/events/browser/resource.md b/specification/logs/semantic_conventions/events/browser/resource.md index 85b3a66d3b2..14be80077ff 100644 --- a/specification/logs/semantic_conventions/events/browser/resource.md +++ b/specification/logs/semantic_conventions/events/browser/resource.md @@ -10,26 +10,27 @@ | Attribute | Type | Value | Requirement Level | |---|---|---|---| | `event.name` | string | `resource` | Required | -| `event.domain | string | `browser` | Required | +| `event.domain` | string | `browser` | Required | -Additional attributes are mapped from the (Resource Timing API)[https://www.w3.org/TR/resource-timing-2/#sec-performanceresourcetiming]. +Additional attributes are mapped from the [Resource Timing API](https://www.w3.org/TR/resource-timing-2/#sec-performanceresourcetiming). This list is not exhaustive and is listed as an example. All numeric and string values thar are provided by the Resource Timing API SHOULD be included. | Attribute | Type | Example | Requirement Level | |---|---|---|---| -| `redirectStart` | numeric | 0 | Optional | -| `redirectEnd` | numeric | 0 | Optional | -| `fetchStart` | numeric | 0 | Optional | -| `domainLookupStart` | numeric | 0 | Optional | -| `domainLookupEnd` | numeric | 0 | Optional | -| `connectStart` | numeric | 0 | Optional | -| `connectEnd` | numeric | 0 | Optional | -| `secureConnectionStart` | numeric | 0 | Optional | -| `requestStart` | numeric | 0 | Optional | -| `responseStart` | numeric | 0 | Optional | -| `responseEnd` | numeric | 0 | Optional | -| `transferSize` | numeric | 0 | Optional | -| `encodedBodySize` | numeric | 0 | Optional | -| `decodedBodySize` | numeric | 0 | Optional | +| `name` | string | `https://example.com/a/b/` | Recommended | +| `redirectStart` | double | 0 | Recommended | +| `redirectEnd` | double | 0 | Recommended | +| `fetchStart` | double | 27.80000112 | Recommended | +| `domainLookupStart` | double | 33.5 | Recommended | +| `domainLookupEnd` | double | 60.5999 | Recommended | +| `connectStart` | double | 60.5999 | Recommended | +| `connectEnd` | double | 113.7 | Recommended | +| `secureConnectionStart` | double | 72.8 | Recommended | +| `requestStart` | double | 114.3 | Recommended | +| `responseStart` | double | 738.8 | Recommended | +| `responseEnd` | double | 790.599 | Recommended | +| `transferSize` | double | 71967 | Recommended | +| `encodedBodySize` | double | 71667 | Recommended | +| `decodedBodySize` | double | 364537 | Recommended | diff --git a/specification/logs/semantic_conventions/events/events.md b/specification/logs/semantic_conventions/events/events.md index 67412f32d34..25377319e2f 100644 --- a/specification/logs/semantic_conventions/events/events.md +++ b/specification/logs/semantic_conventions/events/events.md @@ -10,6 +10,6 @@ | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `event.name` | string | The event name that uniquely identifies the type of the event within the domain. | `exception`; `interaction` | Required | -| `event.domain | string | Identifies the group of related events. Each event within a domain MUST have a unique value for the event.name attribute. | `browser`; `mobile` | Recommended | -| `event.data` | any | Some events/domains may choose to send event attributes as an object or serialized string. | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36` | Optional | +| `event.domain` | string | Identifies the group of related events. Each event within a domain MUST have a unique value for the event.name attribute. | `browser`; `mobile` | Recommended | +| `event.data` | any | | Recommended | From fd7017e9df13a17cb745c1e0b21ed7584069eec2 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Wed, 13 Jul 2022 07:45:20 -0700 Subject: [PATCH 4/4] more clarification --- specification/logs/semantic_conventions/events/README.md | 4 ++-- .../logs/semantic_conventions/events/browser/navigation.md | 2 ++ .../logs/semantic_conventions/events/browser/resource.md | 2 ++ specification/logs/semantic_conventions/events/events.md | 5 ++++- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/specification/logs/semantic_conventions/events/README.md b/specification/logs/semantic_conventions/events/README.md index 4dec653cb34..976ea10160c 100644 --- a/specification/logs/semantic_conventions/events/README.md +++ b/specification/logs/semantic_conventions/events/README.md @@ -2,6 +2,6 @@ Events in OpenTelemetry are a subset of logs with specific set of semantic conventions. -Each events MUST follow the [`events.*`](./events.md) semantic conventions, and it must follow semantic conventions specific for the type of event +Each event MUST follow the [`events.*`](./events.md) semantic conventions, and it must follow semantic conventions specific for the type of event. -Each event has a name (`event.name`) attribute, which uniquely identifies the type of the event. In addition \ No newline at end of file +Each event is uniquely identified by the combination of name (`event.name` attribute) and domain (`event.domain` attribute). Each subfolder in this folder represents a domain. Individual files in the subfolders represent semantic conventions specific to individual events. diff --git a/specification/logs/semantic_conventions/events/browser/navigation.md b/specification/logs/semantic_conventions/events/browser/navigation.md index 3418adb4145..da3b22423ec 100644 --- a/specification/logs/semantic_conventions/events/browser/navigation.md +++ b/specification/logs/semantic_conventions/events/browser/navigation.md @@ -6,6 +6,8 @@ **Description**: Represents a browser navigation event. +The following attributes MUST be set with these predefined values: + | Attribute | Type | Value | Requirement Level | |---|---|---|---| diff --git a/specification/logs/semantic_conventions/events/browser/resource.md b/specification/logs/semantic_conventions/events/browser/resource.md index 14be80077ff..955070e44d1 100644 --- a/specification/logs/semantic_conventions/events/browser/resource.md +++ b/specification/logs/semantic_conventions/events/browser/resource.md @@ -6,6 +6,8 @@ **Description**: Represents a resource observed by the browser. +The following attributes MUST be set with these predefined values: + | Attribute | Type | Value | Requirement Level | |---|---|---|---| diff --git a/specification/logs/semantic_conventions/events/events.md b/specification/logs/semantic_conventions/events/events.md index 25377319e2f..dc4ce6676bf 100644 --- a/specification/logs/semantic_conventions/events/events.md +++ b/specification/logs/semantic_conventions/events/events.md @@ -11,5 +11,8 @@ |---|---|---|---|---| | `event.name` | string | The event name that uniquely identifies the type of the event within the domain. | `exception`; `interaction` | Required | | `event.domain` | string | Identifies the group of related events. Each event within a domain MUST have a unique value for the event.name attribute. | `browser`; `mobile` | Recommended | -| `event.data` | any | | Recommended | +| `event.data` | any | It is recommended that event attributes are sent as a nested object value in this attribute. [1] | Recommended | + + +