# Semantic conventions for CloudEvents spans

LLMS index: [llms.txt](/llms.txt)

---

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

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


<!-- 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 -->

**Attributes:**

| Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`cloudevents.event_id`](/docs/specs/semconv/registry/attributes/cloudevents.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | 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` |
| [`cloudevents.event_source`](/docs/specs/semconv/registry/attributes/cloudevents.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | 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` |
| [`cloudevents.event_spec_version`](/docs/specs/semconv/registry/attributes/cloudevents.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | 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` |
| [`cloudevents.event_subject`](/docs/specs/semconv/registry/attributes/cloudevents.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | 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` |
| [`cloudevents.event_type`](/docs/specs/semconv/registry/attributes/cloudevents.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | 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` |

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

[DocumentStatus]: /docs/specs/otel/document-status