Skip to content

Commit

Permalink
Render events with bodies (#1464)
Browse files Browse the repository at this point in the history
  • Loading branch information
@lmolkova
lmolkova authored Oct 18, 2024
1 parent 25f7419 commit ffa4e8e
Show file tree
Hide file tree
Showing 24 changed files with 276 additions and 186 deletions.
50 changes: 26 additions & 24 deletions docs/azure/events.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,48 +7,50 @@ Resource Log events.

## Azure Resource Log

### Attributes

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

**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)

The event name MUST be `az.resource.log`.

Describes Azure Resource Log event, see [Azure Resource Log Top-level Schema](https://learn.microsoft.com/azure/azure-monitor/essentials/resource-logs-schema#top-level-common-schema) for more details.

| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`az.service_request_id`](/docs/attributes-registry/azure.md) | string | The unique identifier of the service request. It's generated by the Azure service and returned with the response. | `00000000-0000-0000-0000-000000000000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`cloud.resource_id`](/docs/attributes-registry/cloud.md) | string | The [Fully Qualified Azure Resource ID](https://docs.microsoft.com/rest/api/resources/resources/get-by-id) the log is emitted for. | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions/<SUBSCRIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`event.name`](/docs/attributes-registry/event.md) | string | Identifies the class / type of event. [1] | `browser.mouse.click`; `device.app.lifecycle` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

**[1]:** Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). Notably, event names are namespaced to avoid collisions and provide a clean separation of semantics for events in separate domains like browser, mobile, and kubernetes.
**Body fields:**

| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| `category` | string | The Azure category of the log entry. | `AuditEvent`; `GatewayLogs`; `ApplicationGatewayAccessLog` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `correlation.id` | string | The correlation ID of the log entry. | `607964b6-41a5-4e24-a5db-db7aab3b9b34` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `duration` | int | The duration of the operations in milliseconds. | `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `identity` | undefined | "A JSON blob that describes the identity of the user or application that performed the operation." [1] | | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `operation.name` | string | The name of the operation. | `SecretGet`; `Microsoft.ApiManagement/GatewayLogs`; `ApplicationGatewayAccess` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `operation.version` | string | The version of the operation. | `1.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `properties` | undefined | The properties provided in the Azure Resource Log. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `result.description` | string | The description of the result. | `The operation was successful`; `The operation failed` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `result.signature` | string | The substatus of associated with the logged event. | `OK` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `result.type` | string | The status associated with the logged event. | `Succeeded`; `Failed`; `Started` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `tenant.id` | string | The tenant ID of the Active Directory tenant that this event is tied to. | `00000000-0000-0000-0000-000000000000` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

**[1]:** Typically, this field includes the authorization and claims or JWT token from Active Directory.

> [!Warning]
> This field contains sensitive (PII) information.
**[2]:** if the event is tied to an Active Directory tenant.

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

### Body Fields

<!-- manually added table until body fields can be autogenerated -->
| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| `category` | string | The Azure category of the log entry. | `AuditEvent`, `GatewayLogs`, `ApplicationGatewayAccessLog` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `correlation.id` | string | The correlation ID of the log entry. | `607964b6-41a5-4e24-a5db-db7aab3b9b34` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `duration` | int | The duration of the operations in milliseconds. | `1000` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `identity` | string | A JSON blob that describes the identity of the user or application that performed the operation. | `someone` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `operation.name` | string | The name of the operation. | `SecretGet`, `Microsoft.ApiManagement/GatewayLogs`, `ApplicationGatewayAccess` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `operation.version` | string | The version of the operation. | `1.0` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `properties` | keyvaluelist | The properties provided in the Azure Resource Log. | <code>{<br/>&nbsp;&nbsp;"statusCode": "Created",<br/>&nbsp;&nbsp;"serviceRequestId": "50d5cddb-8ca0-47ad-9b80-6cde2207f97c"<br/>}</code> | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `result.type` | string | The status associated with the logged event. | `Started`, `In Progress`, `Succeeded`, `Failed`, `Active`, `Resolved` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `result.signature` | string | The substatus of associated with the logged event. | `OK` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `result.description` | string | The description of the result. | `The operation was successful`, `The operation failed` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `tenant.id` | string | The tenant ID of the Active Directory tenant that this event is tied to. | `607964b6-41a5-4e24-a5db-db7aab3b9b34` | `Conditionally Required`: if the event is tied to an Active Directory tenant. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
<!-- end of manually added table -->

See [Azure Resource Log definition](/model/azure/logs.yaml) for the details.

[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
11 changes: 6 additions & 5 deletions docs/exceptions/exceptions-spans.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ exceptions associated with spans.
<!-- toc -->

- [Recording an Exception](#recording-an-exception)
- [Attributes](#attributes)
- [Exception event](#exception-event)
- [Stacktrace Representation](#stacktrace-representation)

<!-- tocstop -->
Expand All @@ -38,10 +38,7 @@ try {
}
```

## Attributes

The table below indicates which attributes should be added to the `Event` and
their types.
## Exception event

<!-- semconv trace-exception -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
Expand All @@ -50,8 +47,12 @@ their types.
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->

**Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen)

The event name MUST be `exception`.

This event describes a single exception.

| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`exception.message`](/docs/attributes-registry/exception.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | `Conditionally Required` [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
Expand Down
8 changes: 6 additions & 2 deletions docs/feature-flags/feature-flags-logs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ section of the trace semantic convention for feature flag evaluations.
<!-- toc -->

- [Recording an Evaluation](#recording-an-evaluation)
- [Attributes](#attributes)
- [Evaluation event](#evaluation-event)

<!-- tocstop -->

Expand All @@ -32,7 +32,7 @@ Feature flag evaluations SHOULD be recorded as attributes on the
operations. Evaluations MAY be recorded on "logs" or "events" depending on the
context.

## Attributes
## Evaluation event

The table below indicates which attributes should be added to the
[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/data-model.md#log-and-event-record-definition) and their types.
Expand All @@ -44,8 +44,12 @@ The table below indicates which attributes should be added to the
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->

**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)

The event name MUST be `feature_flag`.

This event describes feature flag evaluation representation on a Log Record.

| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier of the feature flag. | `logo-color` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
Expand Down
7 changes: 7 additions & 0 deletions docs/feature-flags/feature-flags-spans.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ To record an evaluation outside of a transaction context, consider
- [Motivation](#motivation)
- [Overview](#overview)
- [Convention](#convention)
- [Evaluation event](#evaluation-event)

<!-- tocstop -->

Expand All @@ -41,15 +42,21 @@ It's intended to be vendor neutral and provide flexibility for current and futur

A flag evaluation SHOULD be recorded as an Event on the span during which it occurred.

### Evaluation event

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

**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)

The event name MUST be `feature_flag`.

This event describes feature flag evaluation.

| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
Expand Down
52 changes: 23 additions & 29 deletions docs/mobile/events.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,25 +9,16 @@ events on mobile platforms. All mobile events MUST use a namespace of
<!-- toc -->

- [Lifecycle instrumentation](#lifecycle-instrumentation)
- [Event details](#event-details)
- [Device app lifecycle event](#device-app-lifecycle-event)

<!-- tocstop -->

## Lifecycle instrumentation

This section defines how to apply semantic conventions when instrumenting
application lifecycle. This event is meant to be used in conjunction with
`os.name` [resource semantic convention](/docs/resource/os.md) to identify the
mobile operating system (e.g. Android, iOS).
application lifecycle.

The following table describes the payload fields that MUST
be used to describe the state of the application at the time of the event.

The `android.state` and `ios.state` fields are mutually exclusive and MUST
NOT be used together, each field MUST be used with its corresponding
`os.name` [resource semantic convention](/docs/resource/os.md) value.

### Event details
### Device app lifecycle event

<!-- semconv device.app.lifecycle -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
Expand All @@ -36,45 +27,48 @@ NOT be used together, each field MUST be used with its corresponding
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->

**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)

The event name MUST be `device.app.lifecycle`.

<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
This event represents an occurrence of a lifecycle transition on Android or iOS platform.

The event body fields MUST be used to describe the state of the application at the time of the event.
This event is meant to be used in conjunction with `os.name` [resource semantic convention](/docs/resource/os.md) to identify the mobile operating system (e.g. Android, iOS).
The `android.state` and `ios.state` fields are mutually exclusive and MUST NOT be used together, each field MUST be used with its corresponding `os.name` value.

<!-- Manually adding the markdown table until the body definition is available in the build tools -->
| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
**Body fields:**

| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| `android.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `created` | `Conditionally Required`: if and only if `os.name` is `android` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `ios.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [2] | `active` | `Conditionally Required`: if and only if `os.name` is `ios` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `android.state` | enum | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `created` | `Conditionally Required` if and only if `os.name` is `android` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `ios.state` | enum | This attribute represents the state the application has transitioned into at the occurrence of the event. [2] | `active` | `Conditionally Required` if and only if `os.name` is `ios` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

**[1]:** The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived.

**[2]:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived.

**Additional attribute requirements:** At least one of the following sets of attributes is required:

* `ios.state`
* `android.state`

`android.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

| Value | Description | Stability |
|---|---|---|
| `created` | Any time before Activity.onResume() or, if the app has no Activity, Context.startService() has been called in the app for the first time. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `background` | Any time after Activity.onPause() or, if the app has no Activity, Context.stopService() has been called when the app was in the foreground state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `created` | Any time before Activity.onResume() or, if the app has no Activity, Context.startService() has been called in the app for the first time. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `foreground` | Any time after Activity.onResume() or, if the app has no Activity, Context.startService() has been called when the app was in either the created or background states. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

`ios.state` MUST be one of the following:
`ios.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

| Value | Description | Stability |
|---|---|---|
| `active` | The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `inactive` | The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `background` | The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `foreground` | The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `inactive` | The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `terminate` | The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
<!-- end of manually added table -->

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

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

0 comments on commit ffa4e8e

Please sign in to comment.