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

Semantic conventions for browser navigation/resource events #1

Closed
wants to merge 4 commits into from
Closed

Semantic conventions for browser navigation/resource events #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d9b36e8
draft of navigation and resource browser events
Jul 12, 2022
1ccbe28
fixing tables
Jul 12, 2022
558a144
formatting changes, examples, updated requirement level
Jul 12, 2022
fd7017e
more clarification
Jul 13, 2022
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
7 changes: 7 additions & 0 deletions specification/logs/semantic_conventions/events/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Events semantic conventions

Events in OpenTelemetry are a subset of logs with specific set of semantic conventions.

Each event MUST follow the [`events.*`](./events.md) semantic conventions, and it must follow semantic conventions specific for the type of event.

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.
9 changes: 9 additions & 0 deletions specification/logs/semantic_conventions/events/browser/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 |

35 changes: 35 additions & 0 deletions specification/logs/semantic_conventions/events/browser/navigation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Navigation

**Status**: [Experimental](../../../../document-status.md)

**type:** `navigation`

**Description**: Represents a browser navigation event.

The following attributes MUST be set with these predefined values:

<!-- semconv browser -->
| Attribute | Type | Value | Requirement Level |
|---|---|---|---|
| `event.name` | string | `navigation` | Required |
| `event.domain` | string | `browser` | Required |
<!-- endsemconv -->

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.
Copy link

Choose a reason for hiding this comment

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

We should call out that this should be included the event.data attribute.



| Attribute | Type | Example | Requirement Level |
|---|---|---|---|
| `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 |
38 changes: 38 additions & 0 deletions specification/logs/semantic_conventions/events/browser/resource.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Navigation

**Status**: [Experimental](../../../../document-status.md)

**type:** `resource`

**Description**: Represents a resource observed by the browser.

The following attributes MUST be set with these predefined values:

<!-- semconv browser -->
| Attribute | Type | Value | Requirement Level |
|---|---|---|---|
| `event.name` | string | `resource` | Required |
| `event.domain` | string | `browser` | Required |
<!-- endsemconv -->

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.
Copy link

Choose a reason for hiding this comment

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

We should call out that this should be included the event.data attribute.

Copy link
Owner Author

Choose a reason for hiding this comment

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

Should all events always add their attributes in event.data? If yes, then I think we should add it to the spec for the event.* attributes, which is currently proposed in open-telemetry#2676.

Copy link

Choose a reason for hiding this comment

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

My thoughts are yes, they should always be added.

Copy link

Choose a reason for hiding this comment

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

Its also a case that as part of the "Nested Attribute" support I included wording about effectively exporters needing to use a strategy to handle when they receive nested attributes, which includes the default (already mentioned as an option) using JSON.stringify()


| Attribute | Type | Example | Requirement Level |
|---|---|---|---|
| `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 |
18 changes: 18 additions & 0 deletions specification/logs/semantic_conventions/events/events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Event

**Status**: [Experimental](../../../document-status.md)

**type:** `event`

**Description**: All events are described by these attributes.

<!-- semconv browser -->
| 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 | It is recommended that event attributes are sent as a nested object value in this attribute. [1] | Recommended |
Copy link

Choose a reason for hiding this comment

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

Because of the way that JSON will support nested attributes (causing an explosion), perhaps we should also support having this as a JSON encoded string?? As this could then also be used for a span.event as it's looking VERY likely that it will be a loooong time (if ever) before we could update span events to support nesting (at least at this point)

But lets leave the JSON string out for now -- just calling this out as a fallback position.

<!-- endsemconv -->