<!--- Hugo front matter used to generate the website version of this page:
linkTitle: Spans
--->

# Semantic conventions for CloudEvents spans

**Status**: [Development][DocumentStatus]

<!-- prettier-ignore-start -->

<!-- toc -->

- [Definitions](#definitions)
- [Conventions](#conventions)
- [Span attributes](#span-attributes)

<!-- tocstop -->

<!-- prettier-ignore-end -->

## Definitions

From the
[CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#overview):

> CloudEvents is a specification for describing event data in common formats
> to provide interoperability across services, platforms and systems.

For more information on the concepts, terminology and background of CloudEvents
consult the
[CloudEvents Primer](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/primer.md)
document.

## Conventions

CloudEvent-specific instrumentations SHOULD follow the span structure described in
the [Semantic Conventions for Messaging Spans](../messaging/messaging-spans.md).

If CloudEvents are instrumented independently of the above conventions,
instrumentations can rely on the
[CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/extensions/distributed-tracing.md)
as means to propagate the trace context.

## Span attributes

Additionally, instrumentations may record the following CloudEvent-specific
attributes on spans created from the conventions described above.

<!-- prettier-ignore-start -->
<!-- semconv cloudevents -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->

| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`cloudevents.event_id`](/docs/registry/attributes/cloudevents.md) | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
| [`cloudevents.event_source`](/docs/registry/attributes/cloudevents.md) | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
| [`cloudevents.event_spec_version`](/docs/registry/attributes/cloudevents.md) | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses. | `1.0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
| [`cloudevents.event_subject`](/docs/registry/attributes/cloudevents.md) | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
| [`cloudevents.event_type`](/docs/registry/attributes/cloudevents.md) | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/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` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |

<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
<!-- prettier-ignore-end -->

[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status