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.

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

Introduce new semantic conventions for CloudEvents #1978

Merged
merged 38 commits into from
Mar 10, 2022
Merged
Show file tree
Hide file tree
Changes from 25 commits
Commits
Show all changes
38 commits
Select commit Hold shift + click to select a range
1040881
Introduce semantic conventions for CloudEvents
joaopgrassi Sep 29, 2021
0223450
Update changelog
joaopgrassi Sep 29, 2021
f82fef8
Change wording to reflect the scope of this document
joaopgrassi Oct 4, 2021
86e4e4e
PR suggestions
joaopgrassi Oct 5, 2021
a1051c3
Remove section of not covered scenarios
joaopgrassi Oct 5, 2021
6d3cf0a
Fix lint errors
joaopgrassi Oct 5, 2021
0d7cdec
Move changelog into unreleased section
arminru Oct 15, 2021
a37ac6e
Adding spans to cloudevents spec (#17)
lmolkova Oct 22, 2021
8b362c5
Update TOC
joaopgrassi Oct 22, 2021
1a30c69
Update CloudEvents spec based on meeting discussion (#18)
lmolkova Nov 10, 2021
b513e29
Update specification/trace/semantic_conventions/cloudevents.md
joaopgrassi Nov 11, 2021
5fb9b49
Merge remote-tracking branch 'upstream/main' into semconv-cloudevents
joaopgrassi Nov 18, 2021
bbdc4f6
Clarify paragraph around cloud events libraries
joaopgrassi Nov 18, 2021
ce87cf0
Change a bit paragraph around cloud events libraries
joaopgrassi Nov 18, 2021
8e94701
Merge branch 'main' into semconv-cloudevents
joaopgrassi Nov 23, 2021
0cf35f4
Merge branch 'main' into semconv-cloudevents
joaopgrassi Nov 30, 2021
8c0cb2a
Merge remote-tracking branch 'upstream/main' into semconv-cloudevents
joaopgrassi Dec 20, 2021
95523cf
PR suggestions
joaopgrassi Dec 20, 2021
be229c8
Remove instrumentation section
joaopgrassi Dec 28, 2021
5d6ac5c
Merge branch 'main' into semconv-cloudevents
joaopgrassi Jan 13, 2022
9835f3a
Merge branch 'main' into semconv-cloudevents
joaopgrassi Jan 14, 2022
01a0dac
Merge branch 'main' into semconv-cloudevents
joaopgrassi Jan 25, 2022
bd684c5
Merge remote-tracking branch 'upstream/main' into semconv-cloudevents
joaopgrassi Jan 27, 2022
87ca073
Merge remote-tracking branch 'upstream/main' into semconv-cloudevents
joaopgrassi Feb 7, 2022
24c8ec0
Merge branch 'main' into semconv-cloudevents
arminru Feb 8, 2022
7128a5c
Mark required attributes
joaopgrassi Feb 16, 2022
b17e28f
Add clarification about CloudEvents
joaopgrassi Feb 16, 2022
dc6a944
Improve wording
joaopgrassi Feb 16, 2022
56426fe
Move reasoning + diagrams from comments to the document
joaopgrassi Feb 25, 2022
c7f2272
Merge remote-tracking branch 'upstream/main' into semconv-cloudevents
joaopgrassi Feb 25, 2022
2063130
Merge remote-tracking branch 'upstream/main' into semconv-cloudevents
joaopgrassi Mar 7, 2022
ca0da3d
Apply suggestions from code review
joaopgrassi Mar 10, 2022
704059f
Update links to point to the new CloudEvents spec
joaopgrassi Mar 10, 2022
7ec8648
Address PR comments
joaopgrassi Mar 10, 2022
7cf0a88
Improve diagram spaces a bit
joaopgrassi Mar 10, 2022
5d2585d
Improve diagram spaces a bit
joaopgrassi Mar 10, 2022
714543a
Address PR comments
joaopgrassi Mar 10, 2022
eaa8ff6
Merge branch 'main' into semconv-cloudevents
arminru Mar 10, 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
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,8 @@ release.
conventions. ([#2272](https://github.com/open-telemetry/opentelemetry-specification/pull/2272))
- Add opentracing.ref_type semantic convention.
([#2297](https://github.com/open-telemetry/opentelemetry-specification/pull/2297))
- Add semantic conventions for [CloudEvents](https://cloudevents.io).
([#1978](https://github.com/open-telemetry/opentelemetry-specification/pull/1978))

### Compatibility

Expand Down
33 changes: 33 additions & 0 deletions semantic_conventions/trace/cloudevents.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
groups:
- id: cloudevents
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved
prefix: cloudevents
brief: >
This document defines attributes for CloudEvents.
CloudEvents is a specification on how to define event data in a standard way.
These attributes can be attached to spans when performing operations with CloudEvents, regardless of the protocol being used.
attributes:
- id: event_id
type: string
brief: >
The [event_id](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#id) uniquely identifies the event.
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved
examples: ['123e4567-e89b-12d3-a456-426614174000', '0001']
- id: event_source
type: string
brief: >
The [source](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#source-1) identifies the context in which an event happened.
examples: ['https://github.com/cloudevents', '/cloudevents/spec/pull/123', 'my-service' ]
- id: event_spec_version
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved
type: string
brief: >
The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#specversion) which the event uses.
examples: '1.0'
- id: event_type
type: string
brief: >
The [event_type](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#type) contains a value describing the type of event related to the originating occurrence.
examples: ['com.github.pull_request.opened', 'com.example.object.deleted.v2']
- id: event_subject
type: string
brief: >
The [subject](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#subject) of the event in the context of the event producer (identified by source).
examples: 'mynewfile.jpg'
76 changes: 76 additions & 0 deletions specification/trace/semantic_conventions/cloudevents.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# CloudEvents
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved

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

This specification defines semantic conventions for [CloudEvents](https://cloudevents.io/).
It covers creation, processing and context propagation between producer and consumer.
It does not cover transport aspects of publishing and receiving cloud events.

## Overview

To be individually traceable, each CloudEvent has to have its own trace context.
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved
The trace context is populated in the event using the
[CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.1/extensions/distributed-tracing.md).

Once the trace context is set on the event, it MUST not be modified.

<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->

<!-- toc -->

- [Spans](#spans)
* [Creation](#creation)
* [Processing](#processing)
- [Attributes](#attributes)

<!-- tocstop -->

## Spans

### Creation

Instrumentation SHOULD create a new span and populate the
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved
[CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.1/extensions/distributed-tracing.md)
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved
on the event. This applies when:

- A CloudEvent is created by the instrumented library.
It may be impossible or impractical to create the Span during event
creation (e.g. inside the constructor or in a factory method),
so instrumentation MAY create the Span later, when passing the event to the transport layer.
- A CloudEvent is created outside of the instrumented library
(e.g. directly constructed by the application owner, without calling a constructor or factory method),
and passed without the Distributed Tracing Extension populated.

In case a CloudEvent is passed to the instrumented library with the
Distributed Tracing Extension already populated, instrumentation MUST NOT create
a span and MUST NOT modify the Distributed Tracing Extension on the event.

**Span name:** `CloudEvents Create <event_type>`

**Span kind:** PRODUCER

### Processing

When an instrumented library supports processing of a single CloudEvent,
instrumentation SHOULD create a new span to trace it.

Instrumentation SHOULD set the remote trace context from the
Distributed Tracing Extension as a link on the processing span.
arminru marked this conversation as resolved.
Show resolved Hide resolved

**Span name:** `CloudEvents Process <event_type>`

**Span kind:** CONSUMER

## Attributes

The following attributes are applicable to creation and processing Spans.

<!-- semconv cloudevents -->
| Attribute | Type | Description | Examples | Required |
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved
|---|---|---|---|---|
| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` | No |
| `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | No |
| `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#specversion) which the event uses. | `1.0` | No |
| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | No |
| `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | No |
<!-- endsemconv -->