From 30006538d01f773f7046ea1d028af719a7e9d1d7 Mon Sep 17 00:00:00 2001 From: James Thompson Date: Wed, 2 Jul 2025 14:39:12 +1000 Subject: [PATCH 1/5] create an event registry #2382 Signed-off-by: James Thompson --- docs/registry/events/README.md | 112 +++++ docs/registry/events/app.md | 48 +++ docs/registry/events/az.md | 34 ++ docs/registry/events/azure.md | 55 +++ docs/registry/events/browser.md | 45 ++ docs/registry/events/device.md | 53 +++ docs/registry/events/exception.md | 29 ++ docs/registry/events/feature-flag.md | 91 ++++ docs/registry/events/gen-ai.md | 402 ++++++++++++++++++ docs/registry/events/rpc.md | 38 ++ docs/registry/events/session.md | 44 ++ .../registry/markdown/event_namespace.md.j2 | 47 ++ .../registry/markdown/event_readme.md.j2 | 41 ++ templates/registry/markdown/weaver.yaml | 8 + 14 files changed, 1047 insertions(+) create mode 100644 docs/registry/events/README.md create mode 100644 docs/registry/events/app.md create mode 100644 docs/registry/events/az.md create mode 100644 docs/registry/events/azure.md create mode 100644 docs/registry/events/browser.md create mode 100644 docs/registry/events/device.md create mode 100644 docs/registry/events/exception.md create mode 100644 docs/registry/events/feature-flag.md create mode 100644 docs/registry/events/gen-ai.md create mode 100644 docs/registry/events/rpc.md create mode 100644 docs/registry/events/session.md create mode 100644 templates/registry/markdown/event_namespace.md.j2 create mode 100644 templates/registry/markdown/event_readme.md.j2 diff --git a/docs/registry/events/README.md b/docs/registry/events/README.md new file mode 100644 index 0000000000..1da425ab78 --- /dev/null +++ b/docs/registry/events/README.md @@ -0,0 +1,112 @@ + + + + + +# Event registry + +The event registry is the catalog of available Events. + +> [!WARNING] +> +> The following registry overview is a work in progress. + +Currently, the following namespaces exist: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NamespaceEventStability
App
app.screen.clickDevelopment
app.widget.clickDevelopment
Az
az.resource.logDeprecated
Azure
azure.resource.logDevelopment
Browser
browser.web_vitalDevelopment
Device
device.app.lifecycleDevelopment
Exception
exceptionStable
Feature Flag
feature_flag.evaluationRelease Candidate
Gen AI
gen_ai.assistant.messageDevelopment
gen_ai.choiceDevelopment
gen_ai.system.messageDevelopment
gen_ai.tool.messageDevelopment
gen_ai.user.messageDevelopment
RPC
rpc.messageDevelopment
Session
session.endDevelopment
session.startDevelopment
diff --git a/docs/registry/events/app.md b/docs/registry/events/app.md new file mode 100644 index 0000000000..8f65f0a161 --- /dev/null +++ b/docs/registry/events/app.md @@ -0,0 +1,48 @@ + + + + + +# App + +## App Screen Click + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `app.screen.click` + +**Summary:** This event represents an instantaneous click on the screen of an application. + + +**Description:** The `app.screen.click` event can be used to indicate that a user has clicked or tapped on the screen portion of an application. Clicks outside of an application's active area SHOULD NOT generate this event. This event does not differentiate between touch/mouse down and touch/mouse up. Implementations SHOULD give preference to generating this event at the time the click is complete, typically on touch release or mouse up. The location of the click event MUST be provided in absolute screen pixels. + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`app.screen.coordinate.x`](/docs/registry/attributes/app.md) | int | The x (horizontal) coordinate of a screen coordinate, in screen pixels. | `0`; `131` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`app.screen.coordinate.y`](/docs/registry/attributes/app.md) | int | The y (vertical) component of a screen coordinate, in screen pixels. | `12`; `99` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | + +## App Widget Click + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `app.widget.click` + +**Summary:** This event indicates that an application widget has been clicked. + + +**Description:** Use this event to indicate that visual application component has been clicked, typically through a user's manual interaction. + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`app.widget.id`](/docs/registry/attributes/app.md) | string | An identifier that uniquely differentiates this widget from other widgets in the same application. [1] | `f9bc787d-ff05-48ad-90e1-fca1d46130b3`; `submit_order_1829` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`app.screen.coordinate.x`](/docs/registry/attributes/app.md) | int | The x (horizontal) coordinate of a screen coordinate, in screen pixels. | `0`; `131` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`app.screen.coordinate.y`](/docs/registry/attributes/app.md) | int | The y (vertical) component of a screen coordinate, in screen pixels. | `12`; `99` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`app.widget.name`](/docs/registry/attributes/app.md) | string | The name of an application widget. [2] | `submit`; `attack`; `Clear Cart` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `app.widget.id`:** A widget is an application component, typically an on-screen visual GUI element. + +**[2] `app.widget.name`:** A widget is an application component, typically an on-screen visual GUI element. + + diff --git a/docs/registry/events/az.md b/docs/registry/events/az.md new file mode 100644 index 0000000000..6a9a161484 --- /dev/null +++ b/docs/registry/events/az.md @@ -0,0 +1,34 @@ + + + + + +# Az + +## Az Resource Log + +**Status:** ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `azure.resource.log`. + +**Event Name:** `az.resource.log` + +**Summary:** Deprecated. Use `azure.resource.log` instead. + + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`az.service_request_id`](/docs/registry/attributes/azure.md) | string | Deprecated, use `azure.service.request.id` instead. | `00000000-0000-0000-0000-000000000000` | `Recommended` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `azure.service.request.id`. | +| [`cloud.resource_id`](/docs/registry/attributes/cloud.md) | string | The [Fully Qualified Azure Resource ID](https://learn.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//resourceGroups//providers/Microsoft.Web/sites//functions/` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +### Body fields: + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**requirement:** `Recommended` + + + +:warning: Body fields will be moved to complex attributes once the +semantic convention tooling supports complex attributes +(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). + + diff --git a/docs/registry/events/azure.md b/docs/registry/events/azure.md new file mode 100644 index 0000000000..a624bc911d --- /dev/null +++ b/docs/registry/events/azure.md @@ -0,0 +1,55 @@ + + + + + +# Azure + +## Azure Resource Log + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `azure.resource.log` + +**Summary:** 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. + + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`azure.service.request.id`](/docs/registry/attributes/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` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`cloud.resource_id`](/docs/registry/attributes/cloud.md) | string | The [Fully Qualified Azure Resource ID](https://learn.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//resourceGroups//providers/Microsoft.Web/sites//functions/` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +### Body fields: + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**requirement:** `Recommended` + + + +:warning: Body fields will be moved to complex attributes once the +semantic convention tooling supports complex attributes +(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). +| 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` | ![Development](https://img.shields.io/badge/-development-blue) | +| `correlation.id` | string | The correlation ID of the log entry. | `607964b6-41a5-4e24-a5db-db7aab3b9b34` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `duration` | int | The duration of the operations in milliseconds. | `1000` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `identity` | undefined | "A JSON blob that describes the identity of the user or application that performed the operation." [1] | | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +| `operation.name` | string | The name of the operation. | `SecretGet`; `Microsoft.ApiManagement/GatewayLogs`; `ApplicationGatewayAccess` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `operation.version` | string | The version of the operation. | `1.0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `properties` | undefined | The properties provided in the Azure Resource Log. | | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `result.description` | string | The description of the result. | `The operation was successful`; `The operation failed` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `result.signature` | string | The substatus of associated with the logged event. | `OK` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `result.type` | string | The status associated with the logged event. | `Succeeded`; `Failed`; `Started` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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] | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1]:** Typically, this field includes the authorization and claims or JWT token from Active Directory. + +> [!Warning] +> This field contains sensitive (PII) information. + +**[2] `tenant.id`:** if the event is tied to an Active Directory tenant. + + + diff --git a/docs/registry/events/browser.md b/docs/registry/events/browser.md new file mode 100644 index 0000000000..48405c85be --- /dev/null +++ b/docs/registry/events/browser.md @@ -0,0 +1,45 @@ + + + + + +# Browser + +## Browser Web Vital + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `browser.web_vital` + +**Summary:** This event describes the website performance metrics introduced by Google, See [web vitals](https://web.dev/vitals). + + +### Body fields: + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**requirement:** `Required` + + + +:warning: Body fields will be moved to complex attributes once the +semantic convention tooling supports complex attributes +(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `delta` | double | The delta between the current value and the last-reported value. See [delta](https://github.com/GoogleChrome/web-vitals?tab=readme-ov-file#report-only-the-delta-of-changes). | `0.2` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| `id` | string | A unique ID representing this particular metric instance. | `v3-1677874579383-6381583661209` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| `name` | enum | Name of the web vital. | `cls` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| `value` | double | Value of the web vital. | `1.0` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | + +`name` 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 | +|---|---|---| +| `cls` | Cumulative Layout Shift. See [cls](https://web.dev/articles/cls). | ![Development](https://img.shields.io/badge/-development-blue) | +| `fid` | First Input Delay. See [fid](https://web.dev/articles/fid). | ![Development](https://img.shields.io/badge/-development-blue) | +| `inp` | Interation to Next Paint. See [inp](https://web.dev/articles/inp). | ![Development](https://img.shields.io/badge/-development-blue) | +| `lcp` | Largest Contentful Paint. See [lcp](https://web.dev/articles/lcp). | ![Development](https://img.shields.io/badge/-development-blue) | + + + diff --git a/docs/registry/events/device.md b/docs/registry/events/device.md new file mode 100644 index 0000000000..5f9fc0e5a9 --- /dev/null +++ b/docs/registry/events/device.md @@ -0,0 +1,53 @@ + + + + + +# Device + +## Device App Lifecycle + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `device.app.lifecycle` + +**Summary:** This event represents an occurrence of a lifecycle transition on Android or iOS platform. + + +**Description:** 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.app.state` and `ios.app.state` fields are mutually exclusive and MUST NOT be used together, each field MUST be used with its corresponding `os.name` value. + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`android.app.state`](/docs/registry/attributes/android.md) | string | This attribute represents the state of the application. [1] | `created` | `Conditionally Required` if and only if `os.name` is `android` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`ios.app.state`](/docs/registry/attributes/ios.md) | string | This attribute represents the state of the application. [2] | `active`; `inactive`; `background` | `Conditionally Required` if and only if `os.name` is `ios` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `android.app.state`:** 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] `ios.app.state`:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate), and from which the `OS terminology` column values are derived. + +--- + +`android.app.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 | +|---|---|---| +| `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. | ![Development](https://img.shields.io/badge/-development-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. | ![Development](https://img.shields.io/badge/-development-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. | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`ios.app.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`. | ![Development](https://img.shields.io/badge/-development-blue) | +| `background` | The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`. | ![Development](https://img.shields.io/badge/-development-blue) | +| `foreground` | The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`. | ![Development](https://img.shields.io/badge/-development-blue) | +| `inactive` | The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. | ![Development](https://img.shields.io/badge/-development-blue) | +| `terminate` | The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. | ![Development](https://img.shields.io/badge/-development-blue) | + + diff --git a/docs/registry/events/exception.md b/docs/registry/events/exception.md new file mode 100644 index 0000000000..e765d650ef --- /dev/null +++ b/docs/registry/events/exception.md @@ -0,0 +1,29 @@ + + + + + +# Exception + +## Exception + +**Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) + +**Event Name:** `exception` + +**Summary:** This event describes a single exception. + + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`exception.message`](/docs/registry/attributes/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) | +| [`exception.type`](/docs/registry/attributes/exception.md) | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`exception.escaped`](/docs/registry/attributes/exception.md) | boolean | Indicates that the exception is escaping the scope of the span. | | `Recommended` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
It's no longer recommended to record exceptions that are handled and do not escape the scope of a span. | +| [`exception.stacktrace`](/docs/registry/attributes/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise. + +**[2] `exception.type`:** Required if `exception.message` is not set, recommended otherwise. + + diff --git a/docs/registry/events/feature-flag.md b/docs/registry/events/feature-flag.md new file mode 100644 index 0000000000..749a460137 --- /dev/null +++ b/docs/registry/events/feature-flag.md @@ -0,0 +1,91 @@ + + + + + +# Feature Flag + +## Feature Flag Evaluation + +**Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) + +**Event Name:** `feature_flag.evaluation` + +**Summary:** Defines feature flag evaluation as an event. + + +**Description:** A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag value is evaluated, which may happen many times over the course of an application lifecycle. For example, a website A/B testing different animations may evaluate a flag each time a button is clicked. A `feature_flag.evaluation` event is emitted on each evaluation even if the result is the same. + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`feature_flag.key`](/docs/registry/attributes/feature-flag.md) | string | The lookup key of the feature flag. | `logo-color` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`error.type`](/docs/registry/attributes/error.md) | string | Describes a class of error the operation ended with. [1] | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`feature_flag.result.value`](/docs/registry/attributes/feature-flag.md) | any | The evaluated value of the feature flag. [3] | `#ff0000`; `true`; `3` | `Conditionally Required` [4] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`feature_flag.result.variant`](/docs/registry/attributes/feature-flag.md) | string | A semantic identifier for an evaluated flag value. [5] | `red`; `true`; `on` | `Conditionally Required` [6] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`error.message`](/docs/registry/attributes/error.md) | string | A message providing more detail about an error in human-readable form. [7] | `Unexpected input type: string`; `The user has exceeded their storage quota` | `Recommended` [8] | ![Development](https://img.shields.io/badge/-development-blue) | +| [`feature_flag.context.id`](/docs/registry/attributes/feature-flag.md) | string | The unique identifier for the flag evaluation context. For example, the targeting key. | `5157782b-2203-4c80-a857-dbbd5e7761db` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`feature_flag.provider.name`](/docs/registry/attributes/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`feature_flag.result.reason`](/docs/registry/attributes/feature-flag.md) | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`feature_flag.set.id`](/docs/registry/attributes/feature-flag.md) | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) to which the feature flag belongs. | `proj-1`; `ab98sgs`; `service1/dev` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`feature_flag.version`](/docs/registry/attributes/feature-flag.md) | string | The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. | `1`; `01ABCDEF` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | + +**[1] `error.type`:** If one of these values applies, then it MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `flag_not_found` | The flag could not be found. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `invalid_context` | The evaluation context does not meet provider requirements. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `parse_error` | An error was encountered parsing data, such as a flag configuration. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `provider_fatal` | The provider has entered an irrecoverable error state. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `provider_not_ready` | The value was resolved before the provider was initialized. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `targeting_key_missing` | The provider requires a targeting key and one was not provided in the evaluation context. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `type_mismatch` | The type of the flag value does not match the expected type. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `general` | The error was for a reason not enumerated above. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | + +**[2] `error.type`:** If and only if an error occurred during flag evaluation. + +**[3] `feature_flag.result.value`:** With some feature flag providers, feature flag results can be quite large or contain private or sensitive details. +Because of this, `feature_flag.result.variant` is often the preferred attribute if it is available. + +It may be desirable to redact or otherwise limit the size and scope of `feature_flag.result.value` if possible. +Because the evaluated flag value is unstructured and may be any type, it is left to the instrumentation author to determine how best to achieve this. + +**[4] `feature_flag.result.value`:** If and only if feature flag provider does not supply variant or equivalent concept. Otherwise, `feature_flag.result.value` should be treated as opt-in. + +**[5] `feature_flag.result.variant`:** A semantic identifier, commonly referred to as a variant, provides a means +for referring to a value without including the value itself. This can +provide additional context for understanding the meaning behind a value. +For example, the variant `red` maybe be used for the value `#c05543`. + +**[6] `feature_flag.result.variant`:** If feature flag provider supplies a variant or equivalent concept. + +**[7] `error.message`:** Should not simply duplicate the value of `error.type`, but should provide more context. For example, if `error.type` is `invalid_context` the `error.message` may enumerate which context keys are missing or invalid. + +**[8] `error.message`:** If and only if an error occurred during flag evaluation and `error.type` does not sufficiently describe the error. + +--- + +`error.type` 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 | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +--- + +`feature_flag.result.reason` 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 | +|---|---|---| +| `cached` | The resolved value was retrieved from cache. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `default` | The resolved value fell back to a pre-configured value (no dynamic evaluation occurred or dynamic evaluation yielded no result). | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `disabled` | The resolved value was the result of the flag being disabled in the management system. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `error` | The resolved value was the result of an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `split` | The resolved value was the result of pseudorandom assignment. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `stale` | The resolved value is non-authoritative or possibly out of date | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `static` | The resolved value is static (no dynamic evaluation). | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `targeting_match` | The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `unknown` | The reason for the resolved value could not be determined. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | + + diff --git a/docs/registry/events/gen-ai.md b/docs/registry/events/gen-ai.md new file mode 100644 index 0000000000..2808b0f371 --- /dev/null +++ b/docs/registry/events/gen-ai.md @@ -0,0 +1,402 @@ + + + + + +# Gen AI + +## Gen AI Assistant Message + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `gen_ai.assistant.message` + +**Summary:** This event describes the assistant message passed to GenAI system. + + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.system`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +Multiple systems, including Azure OpenAI and Gemini, are accessible by OpenAI client +libraries. In such cases, the `gen_ai.system` is set to `openai` based on the +instrumentation's best knowledge, instead of the actual system. The `server.address` +attribute may help identify the actual system in use for `openai`. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +--- + +`gen_ai.system` 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 | +|---|---|---| +| `anthropic` | Anthropic | ![Development](https://img.shields.io/badge/-development-blue) | +| `aws.bedrock` | AWS Bedrock | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.openai` | Azure OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | +| `cohere` | Cohere | ![Development](https://img.shields.io/badge/-development-blue) | +| `deepseek` | DeepSeek | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gemini` | Gemini [2] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai` | Any Google generative AI endpoint [3] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.vertex_ai` | Vertex AI [4] | ![Development](https://img.shields.io/badge/-development-blue) | +| `groq` | Groq | ![Development](https://img.shields.io/badge/-development-blue) | +| `ibm.watsonx.ai` | IBM Watsonx AI | ![Development](https://img.shields.io/badge/-development-blue) | +| `mistral_ai` | Mistral AI | ![Development](https://img.shields.io/badge/-development-blue) | +| `openai` | OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | +| `perplexity` | Perplexity | ![Development](https://img.shields.io/badge/-development-blue) | +| `xai` | xAI | ![Development](https://img.shields.io/badge/-development-blue) | + +**[2]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'. + +**[3]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'. + +**[4]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'. +### Body fields: + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**requirement:** `Opt-In` + + + +:warning: Body fields will be moved to complex attributes once the +semantic convention tooling supports complex attributes +(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `content` | undefined | The contents of the tool message. | `The weather in Paris is rainy and overcast, with temperatures around 57°F` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +| `role` | string | The actual role of the message author as passed in the message. | `assistant`; `bot` | `Conditionally Required` if available and not equal to `assistant`. | ![Development](https://img.shields.io/badge/-development-blue) | +| `tool_calls`: | map[] | The tool calls generated by the model, such as function calls. | | `Conditionally Required` if available | ![Development](https://img.shields.io/badge/-development-blue) | +|   `function`: | map | The function call. | | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +|     `arguments` | undefined | The arguments of the function as provided in the LLM response. [1] | `{\"location\": \"Paris\"}` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +|     `name` | string | The name of the function. | `get_weather` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +|   `id` | string | The id of the tool call. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +|   `type` | enum | The type of the tool. | `function` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1]:** Models usually return arguments as a JSON string. In this case, it's RECOMMENDED to provide arguments as is without attempting to deserialize them. +Semantic conventions for individual systems MAY specify a different type for arguments field. + +`type` 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 | +|---|---|---| +| `function` | Function | ![Development](https://img.shields.io/badge/-development-blue) | + + +## Gen AI Choice + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `gen_ai.choice` + +**Summary:** This event describes the Gen AI response message. + + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.system`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [5] | `openai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[5] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +Multiple systems, including Azure OpenAI and Gemini, are accessible by OpenAI client +libraries. In such cases, the `gen_ai.system` is set to `openai` based on the +instrumentation's best knowledge, instead of the actual system. The `server.address` +attribute may help identify the actual system in use for `openai`. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +--- + +`gen_ai.system` 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 | +|---|---|---| +| `anthropic` | Anthropic | ![Development](https://img.shields.io/badge/-development-blue) | +| `aws.bedrock` | AWS Bedrock | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.openai` | Azure OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | +| `cohere` | Cohere | ![Development](https://img.shields.io/badge/-development-blue) | +| `deepseek` | DeepSeek | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gemini` | Gemini [6] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai` | Any Google generative AI endpoint [7] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.vertex_ai` | Vertex AI [8] | ![Development](https://img.shields.io/badge/-development-blue) | +| `groq` | Groq | ![Development](https://img.shields.io/badge/-development-blue) | +| `ibm.watsonx.ai` | IBM Watsonx AI | ![Development](https://img.shields.io/badge/-development-blue) | +| `mistral_ai` | Mistral AI | ![Development](https://img.shields.io/badge/-development-blue) | +| `openai` | OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | +| `perplexity` | Perplexity | ![Development](https://img.shields.io/badge/-development-blue) | +| `xai` | xAI | ![Development](https://img.shields.io/badge/-development-blue) | + +**[6]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'. + +**[7]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'. + +**[8]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'. +### Body fields: + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**requirement:** `Opt-In` + + + +:warning: Body fields will be moved to complex attributes once the +semantic convention tooling supports complex attributes +(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `finish_reason` | enum | The reason the model stopped generating tokens. | `stop`; `tool_calls`; `content_filter` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| `index` | int | The index of the choice in the list of choices. | `0`; `1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| `message`: | map | GenAI response message. | | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +|   `content` | undefined | The contents of the assistant message. | `The weather in Paris is rainy and overcast, with temperatures around 57°F` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +|   `role` | string | The actual role of the message author as passed in the message. | `assistant`; `bot` | `Conditionally Required` if available and not equal to `assistant`. | ![Development](https://img.shields.io/badge/-development-blue) | +| `tool_calls`: | map[] | The tool calls generated by the model, such as function calls. | | `Conditionally Required` if available | ![Development](https://img.shields.io/badge/-development-blue) | +|   `function`: | map | The function that the model called. | | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +|     `arguments` | undefined | The arguments of the function as provided in the LLM response. [2] | `{\"location\": \"Paris\"}` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +|     `name` | string | The name of the function. | `get_weather` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +|   `id` | string | The id of the tool call. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +|   `type` | enum | The type of the tool. | `function` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[2]:** Models usually return arguments as a JSON string. In this case, it's RECOMMENDED to provide arguments as is without attempting to deserialize them. +Semantic conventions for individual systems MAY specify a different type for arguments field. + +`finish_reason` 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 | +|---|---|---| +| `content_filter` | Content Filter | ![Development](https://img.shields.io/badge/-development-blue) | +| `error` | Error | ![Development](https://img.shields.io/badge/-development-blue) | +| `length` | Length | ![Development](https://img.shields.io/badge/-development-blue) | +| `stop` | Stop | ![Development](https://img.shields.io/badge/-development-blue) | +| `tool_calls` | Tool Calls | ![Development](https://img.shields.io/badge/-development-blue) | + +`type` 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 | +|---|---|---| +| `function` | Function | ![Development](https://img.shields.io/badge/-development-blue) | + + +## Gen AI System Message + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `gen_ai.system.message` + +**Summary:** This event describes the system instructions passed to the GenAI model. + + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.system`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [9] | `openai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[9] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +Multiple systems, including Azure OpenAI and Gemini, are accessible by OpenAI client +libraries. In such cases, the `gen_ai.system` is set to `openai` based on the +instrumentation's best knowledge, instead of the actual system. The `server.address` +attribute may help identify the actual system in use for `openai`. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +--- + +`gen_ai.system` 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 | +|---|---|---| +| `anthropic` | Anthropic | ![Development](https://img.shields.io/badge/-development-blue) | +| `aws.bedrock` | AWS Bedrock | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.openai` | Azure OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | +| `cohere` | Cohere | ![Development](https://img.shields.io/badge/-development-blue) | +| `deepseek` | DeepSeek | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gemini` | Gemini [10] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai` | Any Google generative AI endpoint [11] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.vertex_ai` | Vertex AI [12] | ![Development](https://img.shields.io/badge/-development-blue) | +| `groq` | Groq | ![Development](https://img.shields.io/badge/-development-blue) | +| `ibm.watsonx.ai` | IBM Watsonx AI | ![Development](https://img.shields.io/badge/-development-blue) | +| `mistral_ai` | Mistral AI | ![Development](https://img.shields.io/badge/-development-blue) | +| `openai` | OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | +| `perplexity` | Perplexity | ![Development](https://img.shields.io/badge/-development-blue) | +| `xai` | xAI | ![Development](https://img.shields.io/badge/-development-blue) | + +**[10]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'. + +**[11]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'. + +**[12]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'. +### Body fields: + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**requirement:** `Opt-In` + + + +:warning: Body fields will be moved to complex attributes once the +semantic convention tooling supports complex attributes +(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `content` | undefined | The contents of the system message. | `You're a helpful bot` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +| `role` | string | The actual role of the message author as passed in the message. | `system`; `instruction` | `Conditionally Required` if available and not equal to `system`. | ![Development](https://img.shields.io/badge/-development-blue) | + + +## Gen AI Tool Message + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `gen_ai.tool.message` + +**Summary:** This event describes the response from a tool or function call passed to the GenAI model. + + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.system`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [13] | `openai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[13] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +Multiple systems, including Azure OpenAI and Gemini, are accessible by OpenAI client +libraries. In such cases, the `gen_ai.system` is set to `openai` based on the +instrumentation's best knowledge, instead of the actual system. The `server.address` +attribute may help identify the actual system in use for `openai`. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +--- + +`gen_ai.system` 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 | +|---|---|---| +| `anthropic` | Anthropic | ![Development](https://img.shields.io/badge/-development-blue) | +| `aws.bedrock` | AWS Bedrock | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.openai` | Azure OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | +| `cohere` | Cohere | ![Development](https://img.shields.io/badge/-development-blue) | +| `deepseek` | DeepSeek | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gemini` | Gemini [14] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai` | Any Google generative AI endpoint [15] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.vertex_ai` | Vertex AI [16] | ![Development](https://img.shields.io/badge/-development-blue) | +| `groq` | Groq | ![Development](https://img.shields.io/badge/-development-blue) | +| `ibm.watsonx.ai` | IBM Watsonx AI | ![Development](https://img.shields.io/badge/-development-blue) | +| `mistral_ai` | Mistral AI | ![Development](https://img.shields.io/badge/-development-blue) | +| `openai` | OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | +| `perplexity` | Perplexity | ![Development](https://img.shields.io/badge/-development-blue) | +| `xai` | xAI | ![Development](https://img.shields.io/badge/-development-blue) | + +**[14]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'. + +**[15]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'. + +**[16]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'. +### Body fields: + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**requirement:** `Opt-In` + + + +:warning: Body fields will be moved to complex attributes once the +semantic convention tooling supports complex attributes +(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `content` | undefined | The contents of the tool message. | `rainy, 57°F` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +| `id` | string | Tool call id that this message is responding to. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| `role` | string | The actual role of the message author as passed in the message. | `tool`; `function` | `Conditionally Required` if available and not equal to `tool`. | ![Development](https://img.shields.io/badge/-development-blue) | + + +## Gen AI User Message + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `gen_ai.user.message` + +**Summary:** This event describes the user message passed to the GenAI model. + + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.system`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [17] | `openai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[17] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +Multiple systems, including Azure OpenAI and Gemini, are accessible by OpenAI client +libraries. In such cases, the `gen_ai.system` is set to `openai` based on the +instrumentation's best knowledge, instead of the actual system. The `server.address` +attribute may help identify the actual system in use for `openai`. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +--- + +`gen_ai.system` 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 | +|---|---|---| +| `anthropic` | Anthropic | ![Development](https://img.shields.io/badge/-development-blue) | +| `aws.bedrock` | AWS Bedrock | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.openai` | Azure OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | +| `cohere` | Cohere | ![Development](https://img.shields.io/badge/-development-blue) | +| `deepseek` | DeepSeek | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gemini` | Gemini [18] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai` | Any Google generative AI endpoint [19] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.vertex_ai` | Vertex AI [20] | ![Development](https://img.shields.io/badge/-development-blue) | +| `groq` | Groq | ![Development](https://img.shields.io/badge/-development-blue) | +| `ibm.watsonx.ai` | IBM Watsonx AI | ![Development](https://img.shields.io/badge/-development-blue) | +| `mistral_ai` | Mistral AI | ![Development](https://img.shields.io/badge/-development-blue) | +| `openai` | OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | +| `perplexity` | Perplexity | ![Development](https://img.shields.io/badge/-development-blue) | +| `xai` | xAI | ![Development](https://img.shields.io/badge/-development-blue) | + +**[18]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'. + +**[19]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'. + +**[20]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'. +### Body fields: + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**requirement:** `Opt-In` + + + +:warning: Body fields will be moved to complex attributes once the +semantic convention tooling supports complex attributes +(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `content` | undefined | The contents of the user message. | `What's the weather in Paris?` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +| `role` | string | The actual role of the message author as passed in the message. | `user`; `customer` | `Conditionally Required` if available and not equal to `user`. | ![Development](https://img.shields.io/badge/-development-blue) | + + + diff --git a/docs/registry/events/rpc.md b/docs/registry/events/rpc.md new file mode 100644 index 0000000000..72dc61a0d7 --- /dev/null +++ b/docs/registry/events/rpc.md @@ -0,0 +1,38 @@ + + + + + +# RPC + +## RPC Message + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `rpc.message` + +**Summary:** Describes a message sent or received within the context of an RPC call. + + +**Description:** In the lifetime of an RPC stream, an event for each message sent/received on client and server spans SHOULD be created. In case of unary calls only one sent and one received message will be recorded for both client and server spans. + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`rpc.message.compressed_size`](/docs/registry/attributes/rpc.md) | int | Compressed size of the message in bytes. | | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`rpc.message.id`](/docs/registry/attributes/rpc.md) | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`rpc.message.type`](/docs/registry/attributes/rpc.md) | string | Whether this is a received or sent message. | `SENT`; `RECEIVED` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`rpc.message.uncompressed_size`](/docs/registry/attributes/rpc.md) | int | Uncompressed size of the message in bytes. | | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `rpc.message.id`:** This way we guarantee that the values will be consistent between different implementations. + +--- + +`rpc.message.type` 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 | +|---|---|---| +| `RECEIVED` | received | ![Development](https://img.shields.io/badge/-development-blue) | +| `SENT` | sent | ![Development](https://img.shields.io/badge/-development-blue) | + + diff --git a/docs/registry/events/session.md b/docs/registry/events/session.md new file mode 100644 index 0000000000..a50f6a688b --- /dev/null +++ b/docs/registry/events/session.md @@ -0,0 +1,44 @@ + + + + + +# Session + +## Session End + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `session.end` + +**Summary:** Indicates that a session has ended. + + +**Description:** For instrumentation that tracks user behavior during user sessions, a `session.end` event SHOULD be emitted every time a session ends. When a session ends and continues as a new session, this event SHOULD be emitted prior to the `session.start` event. + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`session.id`](/docs/registry/attributes/session.md) | string | The ID of the session being ended. | `00112233-4455-6677-8899-aabbccddeeff` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | + +## Session Start + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `session.start` + +**Summary:** Indicates that a new session has been started, optionally linking to the prior session. + + +**Description:** For instrumentation that tracks user behavior during user sessions, a `session.start` event MUST be emitted every time a session is created. When a new session is created as a continuation of a prior session, the `session.previous_id` SHOULD be included in the event. The values of `session.id` and `session.previous_id` MUST be different. +When the `session.start` event contains both `session.id` and `session.previous_id` fields, the event indicates that the previous session has ended. If the session ID in `session.previous_id` has not yet ended via explicit `session.end` event, then the consumer SHOULD treat this continuation event as semantically equivalent to `session.end(session.previous_id)` and `session.start(session.id)`. + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`session.id`](/docs/registry/attributes/session.md) | string | The ID of the new session being started. | `00112233-4455-6677-8899-aabbccddeeff` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`session.previous_id`](/docs/registry/attributes/session.md) | string | The previous `session.id` for this user, when known. | `00112233-4455-6677-8899-aabbccddeeff` | `Conditionally Required` [1] | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `session.previous_id`:** If the new session is being created as a continuation of a previous session, the `session.previous_id` SHOULD be included in the event. The `session.id` and `session.previous_id` attributes MUST have different values. + + diff --git a/templates/registry/markdown/event_namespace.md.j2 b/templates/registry/markdown/event_namespace.md.j2 new file mode 100644 index 0000000000..cb28502a16 --- /dev/null +++ b/templates/registry/markdown/event_namespace.md.j2 @@ -0,0 +1,47 @@ + + + + +{%- import 'stability.j2' as stability %} +{%- import 'requirement.j2' as requirement %} +{%- import 'attribute_table.j2' as at %} +{%- import 'body_field_table.j2' as body_table %} +{%- import 'event_macros.j2' as event %} + +# {{ ctx.id | title_case | acronym }} +{% for e in ctx.groups | sort(attribute='name') %} +## {{ e.name | title_case | acronym }} + +**Status:** {{ stability.badge(e.stability, e.deprecated) }} + +**Event Name:** `{{ e.name }}` + +**Summary:** {{ e.brief | trim }} + +{%if e.note %} +**Description:** {{ e.note | trim }} +{% endif %} + +{%- if e.attributes | length > 0 %} +### Attributes: +{{ at.generate(e.attributes, "", "/docs/registry/attributes", e.lineage.attributes) | trim }} +{%- endif %} + +{%- if e.body %} +### Body fields: + +**Status:** {{ stability.badge(e.body.stability, e.body.deprecated) }} + +**requirement:** {{ requirement.render({"level": e.body.requirement_level, "name": e.name}, notes) }} + +:warning: Body fields will be moved to complex attributes once the +semantic convention tooling supports complex attributes +(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). + +{%- if e.body.fields != undefined and e.body.fields | length > 0 %} +{{ body_table.generate(e.body.fields) }} +{%- endif %} +{%- endif %} +{% endfor %} + + diff --git a/templates/registry/markdown/event_readme.md.j2 b/templates/registry/markdown/event_readme.md.j2 new file mode 100644 index 0000000000..d4e2029355 --- /dev/null +++ b/templates/registry/markdown/event_readme.md.j2 @@ -0,0 +1,41 @@ +{%- import 'stability.j2' as stability -%} + + + + + +# Event registry + +The event registry is the catalog of available Events. + +> [!WARNING] +> +> The following registry overview is a work in progress. + +Currently, the following namespaces exist: + + + + + + + + + +{% for bundle in ctx %} + + +{%- for group in bundle.groups | sort(attribute='name') -%} + {%- set my_file_name = bundle.id | kebab_case ~ ".md#" ~ (group.name | kebab_case) -%} + + + + + +{%- endfor %} +{%- endfor %} + +
NamespaceEventStability
{{ bundle.id | title_case | acronym }}
{{ group.name }}{{ stability.htmlbadge(group.stability, group.deprecated) | trim }}
+ diff --git a/templates/registry/markdown/weaver.yaml b/templates/registry/markdown/weaver.yaml index 99c570fde1..6be52803f8 100644 --- a/templates/registry/markdown/weaver.yaml +++ b/templates/registry/markdown/weaver.yaml @@ -19,6 +19,14 @@ templates: filter: '.groups | map(select(.type == "entity")) | group_by(.name | split(".") | .[0]) | map({id: .[0].id | split(".") | .[1], groups: .})' application_mode: each file_name: 'entities/{{ ctx.id | kebab_case }}.md' + - pattern: event_readme.md.j2 + filter: '.groups | map(select(.type == "event")) | group_by(.name | split(".") | .[0]) | map({id: .[0].id | split(".") | .[1], groups: .})' + application_mode: single + file_name: 'events/README.md' + - pattern: event_namespace.md.j2 + filter: '.groups | map(select(.type == "event")) | group_by(.name | split(".") | .[0]) | map({id: .[0].id | split(".") | .[1], groups: .})' + application_mode: each + file_name: 'events/{{ ctx.id | kebab_case }}.md' acronyms: - AI - AWS From e21445d29cb65120d922a2f69078b87b7f1f7be6 Mon Sep 17 00:00:00 2001 From: James Thompson Date: Sat, 12 Jul 2025 15:48:29 +1000 Subject: [PATCH 2/5] Move to 1 page per event --- docs/registry/events/README.md | 52 +-- docs/registry/events/app/README.md | 17 + .../events/app/event-app-screen-click.md | 27 ++ .../{app.md => app/event-app-widget-click.md} | 21 +- docs/registry/events/az/README.md | 16 + .../{az.md => az/event-az-resource-log.md} | 4 +- docs/registry/events/azure/README.md | 16 + .../event-azure-resource-log.md} | 4 +- docs/registry/events/browser/README.md | 16 + .../event-browser-web-vital.md} | 4 +- docs/registry/events/device/README.md | 16 + .../event-device-app-lifecycle.md} | 4 +- docs/registry/events/exception/README.md | 16 + .../event-exception.md} | 4 +- docs/registry/events/feature-flag/README.md | 16 + .../event-feature-flag-evaluation.md} | 4 +- docs/registry/events/gen-ai.md | 402 ------------------ docs/registry/events/gen-ai/README.md | 20 + .../gen-ai/event-gen-ai-assistant-message.md | 102 +++++ .../events/gen-ai/event-gen-ai-choice.md | 115 +++++ .../gen-ai/event-gen-ai-system-message.md | 87 ++++ .../gen-ai/event-gen-ai-tool-message.md | 88 ++++ .../gen-ai/event-gen-ai-user-message.md | 87 ++++ docs/registry/events/rpc/README.md | 16 + .../{rpc.md => rpc/event-rpc-message.md} | 4 +- docs/registry/events/session/README.md | 17 + .../events/session/event-session-end.md | 26 ++ .../event-session-start.md} | 20 +- .../registry/markdown/event_details.md.j2 | 49 +++ .../registry/markdown/event_namespace.md.j2 | 43 +- .../registry/markdown/event_readme.md.j2 | 4 +- templates/registry/markdown/weaver.yaml | 13 +- 32 files changed, 829 insertions(+), 501 deletions(-) create mode 100644 docs/registry/events/app/README.md create mode 100644 docs/registry/events/app/event-app-screen-click.md rename docs/registry/events/{app.md => app/event-app-widget-click.md} (58%) create mode 100644 docs/registry/events/az/README.md rename docs/registry/events/{az.md => az/event-az-resource-log.md} (96%) create mode 100644 docs/registry/events/azure/README.md rename docs/registry/events/{azure.md => azure/event-azure-resource-log.md} (98%) create mode 100644 docs/registry/events/browser/README.md rename docs/registry/events/{browser.md => browser/event-browser-web-vital.md} (97%) create mode 100644 docs/registry/events/device/README.md rename docs/registry/events/{device.md => device/event-device-app-lifecycle.md} (98%) create mode 100644 docs/registry/events/exception/README.md rename docs/registry/events/{exception.md => exception/event-exception.md} (97%) create mode 100644 docs/registry/events/feature-flag/README.md rename docs/registry/events/{feature-flag.md => feature-flag/event-feature-flag-evaluation.md} (99%) delete mode 100644 docs/registry/events/gen-ai.md create mode 100644 docs/registry/events/gen-ai/README.md create mode 100644 docs/registry/events/gen-ai/event-gen-ai-assistant-message.md create mode 100644 docs/registry/events/gen-ai/event-gen-ai-choice.md create mode 100644 docs/registry/events/gen-ai/event-gen-ai-system-message.md create mode 100644 docs/registry/events/gen-ai/event-gen-ai-tool-message.md create mode 100644 docs/registry/events/gen-ai/event-gen-ai-user-message.md create mode 100644 docs/registry/events/rpc/README.md rename docs/registry/events/{rpc.md => rpc/event-rpc-message.md} (97%) create mode 100644 docs/registry/events/session/README.md create mode 100644 docs/registry/events/session/event-session-end.md rename docs/registry/events/{session.md => session/event-session-start.md} (70%) create mode 100644 templates/registry/markdown/event_details.md.j2 diff --git a/docs/registry/events/README.md b/docs/registry/events/README.md index 1da425ab78..a428a51cda 100644 --- a/docs/registry/events/README.md +++ b/docs/registry/events/README.md @@ -24,88 +24,88 @@ Currently, the following namespaces exist: -App +App - app.screen.click + app.screen.click Development - app.widget.click + app.widget.click Development -Az +Az - az.resource.log + az.resource.log Deprecated -Azure +Azure - azure.resource.log + azure.resource.log Development -Browser +Browser - browser.web_vital + browser.web_vital Development -Device +Device - device.app.lifecycle + device.app.lifecycle Development -Exception +Exception - exception + exception Stable -Feature Flag +Feature Flag - feature_flag.evaluation + feature_flag.evaluation Release Candidate -Gen AI +Gen AI - gen_ai.assistant.message + gen_ai.assistant.message Development - gen_ai.choice + gen_ai.choice Development - gen_ai.system.message + gen_ai.system.message Development - gen_ai.tool.message + gen_ai.tool.message Development - gen_ai.user.message + gen_ai.user.message Development -RPC +RPC - rpc.message + rpc.message Development -Session +Session - session.end + session.end Development - session.start + session.start Development diff --git a/docs/registry/events/app/README.md b/docs/registry/events/app/README.md new file mode 100644 index 0000000000..7261a33e99 --- /dev/null +++ b/docs/registry/events/app/README.md @@ -0,0 +1,17 @@ + + + + + +# App +
+Events + +| Name | Summary | Status| +| --- | --- | --- | +| [`app.screen.click`](event-app-screen-click.md) | This event represents an instantaneous click on the screen of an application. | ![Development](https://img.shields.io/badge/-development-blue) | +| [`app.widget.click`](event-app-widget-click.md) | This event indicates that an application widget has been clicked. | ![Development](https://img.shields.io/badge/-development-blue) | + +
+ + diff --git a/docs/registry/events/app/event-app-screen-click.md b/docs/registry/events/app/event-app-screen-click.md new file mode 100644 index 0000000000..0e75d85112 --- /dev/null +++ b/docs/registry/events/app/event-app-screen-click.md @@ -0,0 +1,27 @@ + + + + + +# Event App Screen Click + +## App Screen Click + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `app.screen.click` + +**Namespace:** [`app`](README.md) + +**Summary:** This event represents an instantaneous click on the screen of an application. + + +**Description:** The `app.screen.click` event can be used to indicate that a user has clicked or tapped on the screen portion of an application. Clicks outside of an application's active area SHOULD NOT generate this event. This event does not differentiate between touch/mouse down and touch/mouse up. Implementations SHOULD give preference to generating this event at the time the click is complete, typically on touch release or mouse up. The location of the click event MUST be provided in absolute screen pixels. + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`app.screen.coordinate.x`](/docs/registry/attributes/app.md) | int | The x (horizontal) coordinate of a screen coordinate, in screen pixels. | `0`; `131` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`app.screen.coordinate.y`](/docs/registry/attributes/app.md) | int | The y (vertical) component of a screen coordinate, in screen pixels. | `12`; `99` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | + + diff --git a/docs/registry/events/app.md b/docs/registry/events/app/event-app-widget-click.md similarity index 58% rename from docs/registry/events/app.md rename to docs/registry/events/app/event-app-widget-click.md index 8f65f0a161..b374715234 100644 --- a/docs/registry/events/app.md +++ b/docs/registry/events/app/event-app-widget-click.md @@ -3,24 +3,7 @@ -# App - -## App Screen Click - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -**Event Name:** `app.screen.click` - -**Summary:** This event represents an instantaneous click on the screen of an application. - - -**Description:** The `app.screen.click` event can be used to indicate that a user has clicked or tapped on the screen portion of an application. Clicks outside of an application's active area SHOULD NOT generate this event. This event does not differentiate between touch/mouse down and touch/mouse up. Implementations SHOULD give preference to generating this event at the time the click is complete, typically on touch release or mouse up. The location of the click event MUST be provided in absolute screen pixels. - -### Attributes: -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`app.screen.coordinate.x`](/docs/registry/attributes/app.md) | int | The x (horizontal) coordinate of a screen coordinate, in screen pixels. | `0`; `131` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`app.screen.coordinate.y`](/docs/registry/attributes/app.md) | int | The y (vertical) component of a screen coordinate, in screen pixels. | `12`; `99` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +# Event App Widget Click ## App Widget Click @@ -28,6 +11,8 @@ **Event Name:** `app.widget.click` +**Namespace:** [`app`](README.md) + **Summary:** This event indicates that an application widget has been clicked. diff --git a/docs/registry/events/az/README.md b/docs/registry/events/az/README.md new file mode 100644 index 0000000000..8c7cf2ce3e --- /dev/null +++ b/docs/registry/events/az/README.md @@ -0,0 +1,16 @@ + + + + + +# Az +
+Events + +| Name | Summary | Status| +| --- | --- | --- | +| [`az.resource.log`](event-az-resource-log.md) | Deprecated. Use `azure.resource.log` instead. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `azure.resource.log`. | + +
+ + diff --git a/docs/registry/events/az.md b/docs/registry/events/az/event-az-resource-log.md similarity index 96% rename from docs/registry/events/az.md rename to docs/registry/events/az/event-az-resource-log.md index 6a9a161484..8f5a82ce42 100644 --- a/docs/registry/events/az.md +++ b/docs/registry/events/az/event-az-resource-log.md @@ -3,7 +3,7 @@ -# Az +# Event Az Resource Log ## Az Resource Log @@ -11,6 +11,8 @@ **Event Name:** `az.resource.log` +**Namespace:** [`az`](README.md) + **Summary:** Deprecated. Use `azure.resource.log` instead. diff --git a/docs/registry/events/azure/README.md b/docs/registry/events/azure/README.md new file mode 100644 index 0000000000..24d044ec6f --- /dev/null +++ b/docs/registry/events/azure/README.md @@ -0,0 +1,16 @@ + + + + + +# Azure +
+Events + +| Name | Summary | Status| +| --- | --- | --- | +| [`azure.resource.log`](event-azure-resource-log.md) | 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. | ![Development](https://img.shields.io/badge/-development-blue) | + +
+ + diff --git a/docs/registry/events/azure.md b/docs/registry/events/azure/event-azure-resource-log.md similarity index 98% rename from docs/registry/events/azure.md rename to docs/registry/events/azure/event-azure-resource-log.md index a624bc911d..f3b6b39b53 100644 --- a/docs/registry/events/azure.md +++ b/docs/registry/events/azure/event-azure-resource-log.md @@ -3,7 +3,7 @@ -# Azure +# Event Azure Resource Log ## Azure Resource Log @@ -11,6 +11,8 @@ **Event Name:** `azure.resource.log` +**Namespace:** [`azure`](README.md) + **Summary:** 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. diff --git a/docs/registry/events/browser/README.md b/docs/registry/events/browser/README.md new file mode 100644 index 0000000000..6c5383e3fb --- /dev/null +++ b/docs/registry/events/browser/README.md @@ -0,0 +1,16 @@ + + + + + +# Browser +
+Events + +| Name | Summary | Status| +| --- | --- | --- | +| [`browser.web_vital`](event-browser-web-vital.md) | This event describes the website performance metrics introduced by Google, See [web vitals](https://web.dev/vitals). | ![Development](https://img.shields.io/badge/-development-blue) | + +
+ + diff --git a/docs/registry/events/browser.md b/docs/registry/events/browser/event-browser-web-vital.md similarity index 97% rename from docs/registry/events/browser.md rename to docs/registry/events/browser/event-browser-web-vital.md index 48405c85be..898e8f7d7b 100644 --- a/docs/registry/events/browser.md +++ b/docs/registry/events/browser/event-browser-web-vital.md @@ -3,7 +3,7 @@ -# Browser +# Event Browser Web Vital ## Browser Web Vital @@ -11,6 +11,8 @@ **Event Name:** `browser.web_vital` +**Namespace:** [`browser`](README.md) + **Summary:** This event describes the website performance metrics introduced by Google, See [web vitals](https://web.dev/vitals). diff --git a/docs/registry/events/device/README.md b/docs/registry/events/device/README.md new file mode 100644 index 0000000000..de6bca3089 --- /dev/null +++ b/docs/registry/events/device/README.md @@ -0,0 +1,16 @@ + + + + + +# Device +
+Events + +| Name | Summary | Status| +| --- | --- | --- | +| [`device.app.lifecycle`](event-device-app-lifecycle.md) | This event represents an occurrence of a lifecycle transition on Android or iOS platform. | ![Development](https://img.shields.io/badge/-development-blue) | + +
+ + diff --git a/docs/registry/events/device.md b/docs/registry/events/device/event-device-app-lifecycle.md similarity index 98% rename from docs/registry/events/device.md rename to docs/registry/events/device/event-device-app-lifecycle.md index 5f9fc0e5a9..28815ff8c9 100644 --- a/docs/registry/events/device.md +++ b/docs/registry/events/device/event-device-app-lifecycle.md @@ -3,7 +3,7 @@ -# Device +# Event Device App Lifecycle ## Device App Lifecycle @@ -11,6 +11,8 @@ **Event Name:** `device.app.lifecycle` +**Namespace:** [`device`](README.md) + **Summary:** This event represents an occurrence of a lifecycle transition on Android or iOS platform. diff --git a/docs/registry/events/exception/README.md b/docs/registry/events/exception/README.md new file mode 100644 index 0000000000..e4aa1a74cc --- /dev/null +++ b/docs/registry/events/exception/README.md @@ -0,0 +1,16 @@ + + + + + +# Exception +
+Events + +| Name | Summary | Status| +| --- | --- | --- | +| [`exception`](event-exception.md) | This event describes a single exception. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +
+ + diff --git a/docs/registry/events/exception.md b/docs/registry/events/exception/event-exception.md similarity index 97% rename from docs/registry/events/exception.md rename to docs/registry/events/exception/event-exception.md index e765d650ef..fbd1e988bb 100644 --- a/docs/registry/events/exception.md +++ b/docs/registry/events/exception/event-exception.md @@ -3,7 +3,7 @@ -# Exception +# Event Exception ## Exception @@ -11,6 +11,8 @@ **Event Name:** `exception` +**Namespace:** [`exception`](README.md) + **Summary:** This event describes a single exception. diff --git a/docs/registry/events/feature-flag/README.md b/docs/registry/events/feature-flag/README.md new file mode 100644 index 0000000000..75cb7408dc --- /dev/null +++ b/docs/registry/events/feature-flag/README.md @@ -0,0 +1,16 @@ + + + + + +# Feature Flag +
+Events + +| Name | Summary | Status| +| --- | --- | --- | +| [`feature_flag.evaluation`](event-feature-flag-evaluation.md) | Defines feature flag evaluation as an event. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | + +
+ + diff --git a/docs/registry/events/feature-flag.md b/docs/registry/events/feature-flag/event-feature-flag-evaluation.md similarity index 99% rename from docs/registry/events/feature-flag.md rename to docs/registry/events/feature-flag/event-feature-flag-evaluation.md index 749a460137..8239dd2f11 100644 --- a/docs/registry/events/feature-flag.md +++ b/docs/registry/events/feature-flag/event-feature-flag-evaluation.md @@ -3,7 +3,7 @@ -# Feature Flag +# Event Feature Flag Evaluation ## Feature Flag Evaluation @@ -11,6 +11,8 @@ **Event Name:** `feature_flag.evaluation` +**Namespace:** [`feature_flag`](README.md) + **Summary:** Defines feature flag evaluation as an event. diff --git a/docs/registry/events/gen-ai.md b/docs/registry/events/gen-ai.md deleted file mode 100644 index 2808b0f371..0000000000 --- a/docs/registry/events/gen-ai.md +++ /dev/null @@ -1,402 +0,0 @@ - - - - - -# Gen AI - -## Gen AI Assistant Message - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -**Event Name:** `gen_ai.assistant.message` - -**Summary:** This event describes the assistant message passed to GenAI system. - - -### Attributes: -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`gen_ai.system`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified -by `gen_ai.request.model` and `gen_ai.response.model` attributes. - -The actual GenAI product may differ from the one identified by the client. -Multiple systems, including Azure OpenAI and Gemini, are accessible by OpenAI client -libraries. In such cases, the `gen_ai.system` is set to `openai` based on the -instrumentation's best knowledge, instead of the actual system. The `server.address` -attribute may help identify the actual system in use for `openai`. - -For custom model, a custom friendly name SHOULD be used. -If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. - ---- - -`gen_ai.system` 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 | -|---|---|---| -| `anthropic` | Anthropic | ![Development](https://img.shields.io/badge/-development-blue) | -| `aws.bedrock` | AWS Bedrock | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.openai` | Azure OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | -| `cohere` | Cohere | ![Development](https://img.shields.io/badge/-development-blue) | -| `deepseek` | DeepSeek | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gemini` | Gemini [2] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gen_ai` | Any Google generative AI endpoint [3] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.vertex_ai` | Vertex AI [4] | ![Development](https://img.shields.io/badge/-development-blue) | -| `groq` | Groq | ![Development](https://img.shields.io/badge/-development-blue) | -| `ibm.watsonx.ai` | IBM Watsonx AI | ![Development](https://img.shields.io/badge/-development-blue) | -| `mistral_ai` | Mistral AI | ![Development](https://img.shields.io/badge/-development-blue) | -| `openai` | OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | -| `perplexity` | Perplexity | ![Development](https://img.shields.io/badge/-development-blue) | -| `xai` | xAI | ![Development](https://img.shields.io/badge/-development-blue) | - -**[2]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'. - -**[3]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'. - -**[4]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'. -### Body fields: - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -**requirement:** `Opt-In` - - - -:warning: Body fields will be moved to complex attributes once the -semantic convention tooling supports complex attributes -(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| `content` | undefined | The contents of the tool message. | `The weather in Paris is rainy and overcast, with temperatures around 57°F` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -| `role` | string | The actual role of the message author as passed in the message. | `assistant`; `bot` | `Conditionally Required` if available and not equal to `assistant`. | ![Development](https://img.shields.io/badge/-development-blue) | -| `tool_calls`: | map[] | The tool calls generated by the model, such as function calls. | | `Conditionally Required` if available | ![Development](https://img.shields.io/badge/-development-blue) | -|   `function`: | map | The function call. | | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -|     `arguments` | undefined | The arguments of the function as provided in the LLM response. [1] | `{\"location\": \"Paris\"}` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -|     `name` | string | The name of the function. | `get_weather` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -|   `id` | string | The id of the tool call. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -|   `type` | enum | The type of the tool. | `function` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1]:** Models usually return arguments as a JSON string. In this case, it's RECOMMENDED to provide arguments as is without attempting to deserialize them. -Semantic conventions for individual systems MAY specify a different type for arguments field. - -`type` 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 | -|---|---|---| -| `function` | Function | ![Development](https://img.shields.io/badge/-development-blue) | - - -## Gen AI Choice - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -**Event Name:** `gen_ai.choice` - -**Summary:** This event describes the Gen AI response message. - - -### Attributes: -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`gen_ai.system`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [5] | `openai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[5] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified -by `gen_ai.request.model` and `gen_ai.response.model` attributes. - -The actual GenAI product may differ from the one identified by the client. -Multiple systems, including Azure OpenAI and Gemini, are accessible by OpenAI client -libraries. In such cases, the `gen_ai.system` is set to `openai` based on the -instrumentation's best knowledge, instead of the actual system. The `server.address` -attribute may help identify the actual system in use for `openai`. - -For custom model, a custom friendly name SHOULD be used. -If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. - ---- - -`gen_ai.system` 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 | -|---|---|---| -| `anthropic` | Anthropic | ![Development](https://img.shields.io/badge/-development-blue) | -| `aws.bedrock` | AWS Bedrock | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.openai` | Azure OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | -| `cohere` | Cohere | ![Development](https://img.shields.io/badge/-development-blue) | -| `deepseek` | DeepSeek | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gemini` | Gemini [6] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gen_ai` | Any Google generative AI endpoint [7] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.vertex_ai` | Vertex AI [8] | ![Development](https://img.shields.io/badge/-development-blue) | -| `groq` | Groq | ![Development](https://img.shields.io/badge/-development-blue) | -| `ibm.watsonx.ai` | IBM Watsonx AI | ![Development](https://img.shields.io/badge/-development-blue) | -| `mistral_ai` | Mistral AI | ![Development](https://img.shields.io/badge/-development-blue) | -| `openai` | OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | -| `perplexity` | Perplexity | ![Development](https://img.shields.io/badge/-development-blue) | -| `xai` | xAI | ![Development](https://img.shields.io/badge/-development-blue) | - -**[6]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'. - -**[7]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'. - -**[8]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'. -### Body fields: - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -**requirement:** `Opt-In` - - - -:warning: Body fields will be moved to complex attributes once the -semantic convention tooling supports complex attributes -(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| `finish_reason` | enum | The reason the model stopped generating tokens. | `stop`; `tool_calls`; `content_filter` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -| `index` | int | The index of the choice in the list of choices. | `0`; `1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -| `message`: | map | GenAI response message. | | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -|   `content` | undefined | The contents of the assistant message. | `The weather in Paris is rainy and overcast, with temperatures around 57°F` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -|   `role` | string | The actual role of the message author as passed in the message. | `assistant`; `bot` | `Conditionally Required` if available and not equal to `assistant`. | ![Development](https://img.shields.io/badge/-development-blue) | -| `tool_calls`: | map[] | The tool calls generated by the model, such as function calls. | | `Conditionally Required` if available | ![Development](https://img.shields.io/badge/-development-blue) | -|   `function`: | map | The function that the model called. | | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -|     `arguments` | undefined | The arguments of the function as provided in the LLM response. [2] | `{\"location\": \"Paris\"}` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -|     `name` | string | The name of the function. | `get_weather` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -|   `id` | string | The id of the tool call. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -|   `type` | enum | The type of the tool. | `function` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[2]:** Models usually return arguments as a JSON string. In this case, it's RECOMMENDED to provide arguments as is without attempting to deserialize them. -Semantic conventions for individual systems MAY specify a different type for arguments field. - -`finish_reason` 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 | -|---|---|---| -| `content_filter` | Content Filter | ![Development](https://img.shields.io/badge/-development-blue) | -| `error` | Error | ![Development](https://img.shields.io/badge/-development-blue) | -| `length` | Length | ![Development](https://img.shields.io/badge/-development-blue) | -| `stop` | Stop | ![Development](https://img.shields.io/badge/-development-blue) | -| `tool_calls` | Tool Calls | ![Development](https://img.shields.io/badge/-development-blue) | - -`type` 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 | -|---|---|---| -| `function` | Function | ![Development](https://img.shields.io/badge/-development-blue) | - - -## Gen AI System Message - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -**Event Name:** `gen_ai.system.message` - -**Summary:** This event describes the system instructions passed to the GenAI model. - - -### Attributes: -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`gen_ai.system`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [9] | `openai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[9] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified -by `gen_ai.request.model` and `gen_ai.response.model` attributes. - -The actual GenAI product may differ from the one identified by the client. -Multiple systems, including Azure OpenAI and Gemini, are accessible by OpenAI client -libraries. In such cases, the `gen_ai.system` is set to `openai` based on the -instrumentation's best knowledge, instead of the actual system. The `server.address` -attribute may help identify the actual system in use for `openai`. - -For custom model, a custom friendly name SHOULD be used. -If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. - ---- - -`gen_ai.system` 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 | -|---|---|---| -| `anthropic` | Anthropic | ![Development](https://img.shields.io/badge/-development-blue) | -| `aws.bedrock` | AWS Bedrock | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.openai` | Azure OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | -| `cohere` | Cohere | ![Development](https://img.shields.io/badge/-development-blue) | -| `deepseek` | DeepSeek | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gemini` | Gemini [10] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gen_ai` | Any Google generative AI endpoint [11] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.vertex_ai` | Vertex AI [12] | ![Development](https://img.shields.io/badge/-development-blue) | -| `groq` | Groq | ![Development](https://img.shields.io/badge/-development-blue) | -| `ibm.watsonx.ai` | IBM Watsonx AI | ![Development](https://img.shields.io/badge/-development-blue) | -| `mistral_ai` | Mistral AI | ![Development](https://img.shields.io/badge/-development-blue) | -| `openai` | OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | -| `perplexity` | Perplexity | ![Development](https://img.shields.io/badge/-development-blue) | -| `xai` | xAI | ![Development](https://img.shields.io/badge/-development-blue) | - -**[10]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'. - -**[11]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'. - -**[12]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'. -### Body fields: - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -**requirement:** `Opt-In` - - - -:warning: Body fields will be moved to complex attributes once the -semantic convention tooling supports complex attributes -(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| `content` | undefined | The contents of the system message. | `You're a helpful bot` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -| `role` | string | The actual role of the message author as passed in the message. | `system`; `instruction` | `Conditionally Required` if available and not equal to `system`. | ![Development](https://img.shields.io/badge/-development-blue) | - - -## Gen AI Tool Message - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -**Event Name:** `gen_ai.tool.message` - -**Summary:** This event describes the response from a tool or function call passed to the GenAI model. - - -### Attributes: -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`gen_ai.system`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [13] | `openai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[13] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified -by `gen_ai.request.model` and `gen_ai.response.model` attributes. - -The actual GenAI product may differ from the one identified by the client. -Multiple systems, including Azure OpenAI and Gemini, are accessible by OpenAI client -libraries. In such cases, the `gen_ai.system` is set to `openai` based on the -instrumentation's best knowledge, instead of the actual system. The `server.address` -attribute may help identify the actual system in use for `openai`. - -For custom model, a custom friendly name SHOULD be used. -If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. - ---- - -`gen_ai.system` 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 | -|---|---|---| -| `anthropic` | Anthropic | ![Development](https://img.shields.io/badge/-development-blue) | -| `aws.bedrock` | AWS Bedrock | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.openai` | Azure OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | -| `cohere` | Cohere | ![Development](https://img.shields.io/badge/-development-blue) | -| `deepseek` | DeepSeek | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gemini` | Gemini [14] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gen_ai` | Any Google generative AI endpoint [15] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.vertex_ai` | Vertex AI [16] | ![Development](https://img.shields.io/badge/-development-blue) | -| `groq` | Groq | ![Development](https://img.shields.io/badge/-development-blue) | -| `ibm.watsonx.ai` | IBM Watsonx AI | ![Development](https://img.shields.io/badge/-development-blue) | -| `mistral_ai` | Mistral AI | ![Development](https://img.shields.io/badge/-development-blue) | -| `openai` | OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | -| `perplexity` | Perplexity | ![Development](https://img.shields.io/badge/-development-blue) | -| `xai` | xAI | ![Development](https://img.shields.io/badge/-development-blue) | - -**[14]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'. - -**[15]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'. - -**[16]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'. -### Body fields: - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -**requirement:** `Opt-In` - - - -:warning: Body fields will be moved to complex attributes once the -semantic convention tooling supports complex attributes -(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| `content` | undefined | The contents of the tool message. | `rainy, 57°F` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -| `id` | string | Tool call id that this message is responding to. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -| `role` | string | The actual role of the message author as passed in the message. | `tool`; `function` | `Conditionally Required` if available and not equal to `tool`. | ![Development](https://img.shields.io/badge/-development-blue) | - - -## Gen AI User Message - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -**Event Name:** `gen_ai.user.message` - -**Summary:** This event describes the user message passed to the GenAI model. - - -### Attributes: -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`gen_ai.system`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [17] | `openai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[17] `gen_ai.system`:** The `gen_ai.system` describes a family of GenAI models with specific model identified -by `gen_ai.request.model` and `gen_ai.response.model` attributes. - -The actual GenAI product may differ from the one identified by the client. -Multiple systems, including Azure OpenAI and Gemini, are accessible by OpenAI client -libraries. In such cases, the `gen_ai.system` is set to `openai` based on the -instrumentation's best knowledge, instead of the actual system. The `server.address` -attribute may help identify the actual system in use for `openai`. - -For custom model, a custom friendly name SHOULD be used. -If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. - ---- - -`gen_ai.system` 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 | -|---|---|---| -| `anthropic` | Anthropic | ![Development](https://img.shields.io/badge/-development-blue) | -| `aws.bedrock` | AWS Bedrock | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.openai` | Azure OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | -| `cohere` | Cohere | ![Development](https://img.shields.io/badge/-development-blue) | -| `deepseek` | DeepSeek | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gemini` | Gemini [18] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gen_ai` | Any Google generative AI endpoint [19] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.vertex_ai` | Vertex AI [20] | ![Development](https://img.shields.io/badge/-development-blue) | -| `groq` | Groq | ![Development](https://img.shields.io/badge/-development-blue) | -| `ibm.watsonx.ai` | IBM Watsonx AI | ![Development](https://img.shields.io/badge/-development-blue) | -| `mistral_ai` | Mistral AI | ![Development](https://img.shields.io/badge/-development-blue) | -| `openai` | OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | -| `perplexity` | Perplexity | ![Development](https://img.shields.io/badge/-development-blue) | -| `xai` | xAI | ![Development](https://img.shields.io/badge/-development-blue) | - -**[18]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'. - -**[19]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'. - -**[20]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'. -### Body fields: - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -**requirement:** `Opt-In` - - - -:warning: Body fields will be moved to complex attributes once the -semantic convention tooling supports complex attributes -(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| `content` | undefined | The contents of the user message. | `What's the weather in Paris?` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -| `role` | string | The actual role of the message author as passed in the message. | `user`; `customer` | `Conditionally Required` if available and not equal to `user`. | ![Development](https://img.shields.io/badge/-development-blue) | - - - diff --git a/docs/registry/events/gen-ai/README.md b/docs/registry/events/gen-ai/README.md new file mode 100644 index 0000000000..18ed3549ff --- /dev/null +++ b/docs/registry/events/gen-ai/README.md @@ -0,0 +1,20 @@ + + + + + +# Gen AI +
+Events + +| Name | Summary | Status| +| --- | --- | --- | +| [`gen_ai.assistant.message`](event-gen-ai-assistant-message.md) | This event describes the assistant message passed to GenAI system. | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.choice`](event-gen-ai-choice.md) | This event describes the Gen AI response message. | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.system.message`](event-gen-ai-system-message.md) | This event describes the system instructions passed to the GenAI model. | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.tool.message`](event-gen-ai-tool-message.md) | This event describes the response from a tool or function call passed to the GenAI model. | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.user.message`](event-gen-ai-user-message.md) | This event describes the user message passed to the GenAI model. | ![Development](https://img.shields.io/badge/-development-blue) | + +
+ + diff --git a/docs/registry/events/gen-ai/event-gen-ai-assistant-message.md b/docs/registry/events/gen-ai/event-gen-ai-assistant-message.md new file mode 100644 index 0000000000..eba1eea1b9 --- /dev/null +++ b/docs/registry/events/gen-ai/event-gen-ai-assistant-message.md @@ -0,0 +1,102 @@ + + + + + +# Event Gen AI Assistant Message + +## Gen AI Assistant Message + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `gen_ai.assistant.message` + +**Namespace:** [`gen_ai`](README.md) + +**Summary:** This event describes the assistant message passed to GenAI system. + + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI provider as identified by the client or server instrumentation. [1] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `gen_ai.provider.name`:** The attribute SHOULD be set based on the instrumentation's best +knowledge and may differ from the actual model provider. + +Multiple providers, including Azure OpenAI, Gemini, and AI hosting platforms +are accessible using the OpenAI REST API and corresponding client libraries, +but may proxy or host models from different providers. + +The `gen_ai.request.model`, `gen_ai.response.model`, and `server.address` +attributes may help identify the actual system in use. + +The `gen_ai.provider.name` attribute acts as a discriminator that +identifies the GenAI telemetry format flavor specific to that provider +within GenAI semantic conventions. +It SHOULD be set consistently with provider-specific attributes and signals. +For example, GenAI spans, metrics, and events related to AWS Bedrock +should have the `gen_ai.provider.name` set to `aws.bedrock` and include +applicable `aws.bedrock.*` attributes and are not expected to include +`openai.*` attributes. + +--- + +`gen_ai.provider.name` 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 | +|---|---|---| +| `anthropic` | [Anthropic](https://www.anthropic.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `aws.bedrock` | [AWS Bedrock](https://aws.amazon.com/bedrock) | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.openai` | [Azure OpenAI](https://azure.microsoft.com/products/ai-services/openai-service/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `cohere` | [Cohere](https://cohere.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `deepseek` | [DeepSeek](https://www.deepseek.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gemini` | [Gemini](https://cloud.google.com/products/gemini) [2] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai` | Any Google generative AI endpoint [3] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [4] | ![Development](https://img.shields.io/badge/-development-blue) | +| `groq` | [Groq](https://groq.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) | ![Development](https://img.shields.io/badge/-development-blue) | +| `mistral_ai` | [Mistral AI](https://mistral.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `openai` | [OpenAI](https://openai.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `perplexity` | [Perplexity](https://www.perplexity.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `x_ai` | [xAI](https://x.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | + +**[2]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. + +**[3]:** May be used when specific backend is unknown. + +**[4]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. +### Body fields: + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**requirement:** `Opt-In` + + + +:warning: Body fields will be moved to complex attributes once the +semantic convention tooling supports complex attributes +(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `content` | undefined | The contents of the tool message. | `The weather in Paris is rainy and overcast, with temperatures around 57°F` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +| `role` | string | The actual role of the message author as passed in the message. | `assistant`; `bot` | `Conditionally Required` if available and not equal to `assistant`. | ![Development](https://img.shields.io/badge/-development-blue) | +| `tool_calls`: | map[] | The tool calls generated by the model, such as function calls. | | `Conditionally Required` if available | ![Development](https://img.shields.io/badge/-development-blue) | +|   `function`: | map | The function call. | | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +|     `arguments` | undefined | The arguments of the function as provided in the LLM response. [1] | `{\"location\": \"Paris\"}` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +|     `name` | string | The name of the function. | `get_weather` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +|   `id` | string | The id of the tool call. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +|   `type` | enum | The type of the tool. | `function` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1]:** Models usually return arguments as a JSON string. In this case, it's RECOMMENDED to provide arguments as is without attempting to deserialize them. +Semantic conventions for individual systems MAY specify a different type for arguments field. + +`type` 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 | +|---|---|---| +| `function` | Function | ![Development](https://img.shields.io/badge/-development-blue) | + + + diff --git a/docs/registry/events/gen-ai/event-gen-ai-choice.md b/docs/registry/events/gen-ai/event-gen-ai-choice.md new file mode 100644 index 0000000000..ebbc35d112 --- /dev/null +++ b/docs/registry/events/gen-ai/event-gen-ai-choice.md @@ -0,0 +1,115 @@ + + + + + +# Event Gen AI Choice + +## Gen AI Choice + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `gen_ai.choice` + +**Namespace:** [`gen_ai`](README.md) + +**Summary:** This event describes the Gen AI response message. + + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI provider as identified by the client or server instrumentation. [1] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `gen_ai.provider.name`:** The attribute SHOULD be set based on the instrumentation's best +knowledge and may differ from the actual model provider. + +Multiple providers, including Azure OpenAI, Gemini, and AI hosting platforms +are accessible using the OpenAI REST API and corresponding client libraries, +but may proxy or host models from different providers. + +The `gen_ai.request.model`, `gen_ai.response.model`, and `server.address` +attributes may help identify the actual system in use. + +The `gen_ai.provider.name` attribute acts as a discriminator that +identifies the GenAI telemetry format flavor specific to that provider +within GenAI semantic conventions. +It SHOULD be set consistently with provider-specific attributes and signals. +For example, GenAI spans, metrics, and events related to AWS Bedrock +should have the `gen_ai.provider.name` set to `aws.bedrock` and include +applicable `aws.bedrock.*` attributes and are not expected to include +`openai.*` attributes. + +--- + +`gen_ai.provider.name` 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 | +|---|---|---| +| `anthropic` | [Anthropic](https://www.anthropic.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `aws.bedrock` | [AWS Bedrock](https://aws.amazon.com/bedrock) | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.openai` | [Azure OpenAI](https://azure.microsoft.com/products/ai-services/openai-service/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `cohere` | [Cohere](https://cohere.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `deepseek` | [DeepSeek](https://www.deepseek.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gemini` | [Gemini](https://cloud.google.com/products/gemini) [2] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai` | Any Google generative AI endpoint [3] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [4] | ![Development](https://img.shields.io/badge/-development-blue) | +| `groq` | [Groq](https://groq.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) | ![Development](https://img.shields.io/badge/-development-blue) | +| `mistral_ai` | [Mistral AI](https://mistral.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `openai` | [OpenAI](https://openai.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `perplexity` | [Perplexity](https://www.perplexity.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `x_ai` | [xAI](https://x.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | + +**[2]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. + +**[3]:** May be used when specific backend is unknown. + +**[4]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. +### Body fields: + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**requirement:** `Opt-In` + + + +:warning: Body fields will be moved to complex attributes once the +semantic convention tooling supports complex attributes +(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `finish_reason` | enum | The reason the model stopped generating tokens. | `stop`; `tool_calls`; `content_filter` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| `index` | int | The index of the choice in the list of choices. | `0`; `1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| `message`: | map | GenAI response message. | | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +|   `content` | undefined | The contents of the assistant message. | `The weather in Paris is rainy and overcast, with temperatures around 57°F` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +|   `role` | string | The actual role of the message author as passed in the message. | `assistant`; `bot` | `Conditionally Required` if available and not equal to `assistant`. | ![Development](https://img.shields.io/badge/-development-blue) | +| `tool_calls`: | map[] | The tool calls generated by the model, such as function calls. | | `Conditionally Required` if available | ![Development](https://img.shields.io/badge/-development-blue) | +|   `function`: | map | The function that the model called. | | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +|     `arguments` | undefined | The arguments of the function as provided in the LLM response. [1] | `{\"location\": \"Paris\"}` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +|     `name` | string | The name of the function. | `get_weather` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +|   `id` | string | The id of the tool call. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +|   `type` | enum | The type of the tool. | `function` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1]:** Models usually return arguments as a JSON string. In this case, it's RECOMMENDED to provide arguments as is without attempting to deserialize them. +Semantic conventions for individual systems MAY specify a different type for arguments field. + +`finish_reason` 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 | +|---|---|---| +| `content_filter` | Content Filter | ![Development](https://img.shields.io/badge/-development-blue) | +| `error` | Error | ![Development](https://img.shields.io/badge/-development-blue) | +| `length` | Length | ![Development](https://img.shields.io/badge/-development-blue) | +| `stop` | Stop | ![Development](https://img.shields.io/badge/-development-blue) | +| `tool_calls` | Tool Calls | ![Development](https://img.shields.io/badge/-development-blue) | + +`type` 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 | +|---|---|---| +| `function` | Function | ![Development](https://img.shields.io/badge/-development-blue) | + + + diff --git a/docs/registry/events/gen-ai/event-gen-ai-system-message.md b/docs/registry/events/gen-ai/event-gen-ai-system-message.md new file mode 100644 index 0000000000..75fdab4865 --- /dev/null +++ b/docs/registry/events/gen-ai/event-gen-ai-system-message.md @@ -0,0 +1,87 @@ + + + + + +# Event Gen AI System Message + +## Gen AI System Message + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `gen_ai.system.message` + +**Namespace:** [`gen_ai`](README.md) + +**Summary:** This event describes the system instructions passed to the GenAI model. + + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI provider as identified by the client or server instrumentation. [1] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `gen_ai.provider.name`:** The attribute SHOULD be set based on the instrumentation's best +knowledge and may differ from the actual model provider. + +Multiple providers, including Azure OpenAI, Gemini, and AI hosting platforms +are accessible using the OpenAI REST API and corresponding client libraries, +but may proxy or host models from different providers. + +The `gen_ai.request.model`, `gen_ai.response.model`, and `server.address` +attributes may help identify the actual system in use. + +The `gen_ai.provider.name` attribute acts as a discriminator that +identifies the GenAI telemetry format flavor specific to that provider +within GenAI semantic conventions. +It SHOULD be set consistently with provider-specific attributes and signals. +For example, GenAI spans, metrics, and events related to AWS Bedrock +should have the `gen_ai.provider.name` set to `aws.bedrock` and include +applicable `aws.bedrock.*` attributes and are not expected to include +`openai.*` attributes. + +--- + +`gen_ai.provider.name` 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 | +|---|---|---| +| `anthropic` | [Anthropic](https://www.anthropic.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `aws.bedrock` | [AWS Bedrock](https://aws.amazon.com/bedrock) | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.openai` | [Azure OpenAI](https://azure.microsoft.com/products/ai-services/openai-service/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `cohere` | [Cohere](https://cohere.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `deepseek` | [DeepSeek](https://www.deepseek.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gemini` | [Gemini](https://cloud.google.com/products/gemini) [2] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai` | Any Google generative AI endpoint [3] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [4] | ![Development](https://img.shields.io/badge/-development-blue) | +| `groq` | [Groq](https://groq.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) | ![Development](https://img.shields.io/badge/-development-blue) | +| `mistral_ai` | [Mistral AI](https://mistral.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `openai` | [OpenAI](https://openai.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `perplexity` | [Perplexity](https://www.perplexity.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `x_ai` | [xAI](https://x.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | + +**[2]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. + +**[3]:** May be used when specific backend is unknown. + +**[4]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. +### Body fields: + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**requirement:** `Opt-In` + + + +:warning: Body fields will be moved to complex attributes once the +semantic convention tooling supports complex attributes +(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `content` | undefined | The contents of the system message. | `You're a helpful bot` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +| `role` | string | The actual role of the message author as passed in the message. | `system`; `instruction` | `Conditionally Required` if available and not equal to `system`. | ![Development](https://img.shields.io/badge/-development-blue) | + + + diff --git a/docs/registry/events/gen-ai/event-gen-ai-tool-message.md b/docs/registry/events/gen-ai/event-gen-ai-tool-message.md new file mode 100644 index 0000000000..fca7d226e6 --- /dev/null +++ b/docs/registry/events/gen-ai/event-gen-ai-tool-message.md @@ -0,0 +1,88 @@ + + + + + +# Event Gen AI Tool Message + +## Gen AI Tool Message + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `gen_ai.tool.message` + +**Namespace:** [`gen_ai`](README.md) + +**Summary:** This event describes the response from a tool or function call passed to the GenAI model. + + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI provider as identified by the client or server instrumentation. [1] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `gen_ai.provider.name`:** The attribute SHOULD be set based on the instrumentation's best +knowledge and may differ from the actual model provider. + +Multiple providers, including Azure OpenAI, Gemini, and AI hosting platforms +are accessible using the OpenAI REST API and corresponding client libraries, +but may proxy or host models from different providers. + +The `gen_ai.request.model`, `gen_ai.response.model`, and `server.address` +attributes may help identify the actual system in use. + +The `gen_ai.provider.name` attribute acts as a discriminator that +identifies the GenAI telemetry format flavor specific to that provider +within GenAI semantic conventions. +It SHOULD be set consistently with provider-specific attributes and signals. +For example, GenAI spans, metrics, and events related to AWS Bedrock +should have the `gen_ai.provider.name` set to `aws.bedrock` and include +applicable `aws.bedrock.*` attributes and are not expected to include +`openai.*` attributes. + +--- + +`gen_ai.provider.name` 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 | +|---|---|---| +| `anthropic` | [Anthropic](https://www.anthropic.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `aws.bedrock` | [AWS Bedrock](https://aws.amazon.com/bedrock) | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.openai` | [Azure OpenAI](https://azure.microsoft.com/products/ai-services/openai-service/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `cohere` | [Cohere](https://cohere.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `deepseek` | [DeepSeek](https://www.deepseek.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gemini` | [Gemini](https://cloud.google.com/products/gemini) [2] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai` | Any Google generative AI endpoint [3] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [4] | ![Development](https://img.shields.io/badge/-development-blue) | +| `groq` | [Groq](https://groq.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) | ![Development](https://img.shields.io/badge/-development-blue) | +| `mistral_ai` | [Mistral AI](https://mistral.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `openai` | [OpenAI](https://openai.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `perplexity` | [Perplexity](https://www.perplexity.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `x_ai` | [xAI](https://x.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | + +**[2]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. + +**[3]:** May be used when specific backend is unknown. + +**[4]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. +### Body fields: + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**requirement:** `Opt-In` + + + +:warning: Body fields will be moved to complex attributes once the +semantic convention tooling supports complex attributes +(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `content` | undefined | The contents of the tool message. | `rainy, 57°F` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +| `id` | string | Tool call id that this message is responding to. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| `role` | string | The actual role of the message author as passed in the message. | `tool`; `function` | `Conditionally Required` if available and not equal to `tool`. | ![Development](https://img.shields.io/badge/-development-blue) | + + + diff --git a/docs/registry/events/gen-ai/event-gen-ai-user-message.md b/docs/registry/events/gen-ai/event-gen-ai-user-message.md new file mode 100644 index 0000000000..8a05af32ab --- /dev/null +++ b/docs/registry/events/gen-ai/event-gen-ai-user-message.md @@ -0,0 +1,87 @@ + + + + + +# Event Gen AI User Message + +## Gen AI User Message + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `gen_ai.user.message` + +**Namespace:** [`gen_ai`](README.md) + +**Summary:** This event describes the user message passed to the GenAI model. + + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI provider as identified by the client or server instrumentation. [1] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `gen_ai.provider.name`:** The attribute SHOULD be set based on the instrumentation's best +knowledge and may differ from the actual model provider. + +Multiple providers, including Azure OpenAI, Gemini, and AI hosting platforms +are accessible using the OpenAI REST API and corresponding client libraries, +but may proxy or host models from different providers. + +The `gen_ai.request.model`, `gen_ai.response.model`, and `server.address` +attributes may help identify the actual system in use. + +The `gen_ai.provider.name` attribute acts as a discriminator that +identifies the GenAI telemetry format flavor specific to that provider +within GenAI semantic conventions. +It SHOULD be set consistently with provider-specific attributes and signals. +For example, GenAI spans, metrics, and events related to AWS Bedrock +should have the `gen_ai.provider.name` set to `aws.bedrock` and include +applicable `aws.bedrock.*` attributes and are not expected to include +`openai.*` attributes. + +--- + +`gen_ai.provider.name` 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 | +|---|---|---| +| `anthropic` | [Anthropic](https://www.anthropic.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `aws.bedrock` | [AWS Bedrock](https://aws.amazon.com/bedrock) | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.openai` | [Azure OpenAI](https://azure.microsoft.com/products/ai-services/openai-service/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `cohere` | [Cohere](https://cohere.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `deepseek` | [DeepSeek](https://www.deepseek.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gemini` | [Gemini](https://cloud.google.com/products/gemini) [2] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai` | Any Google generative AI endpoint [3] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [4] | ![Development](https://img.shields.io/badge/-development-blue) | +| `groq` | [Groq](https://groq.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) | ![Development](https://img.shields.io/badge/-development-blue) | +| `mistral_ai` | [Mistral AI](https://mistral.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `openai` | [OpenAI](https://openai.com/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `perplexity` | [Perplexity](https://www.perplexity.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `x_ai` | [xAI](https://x.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | + +**[2]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. + +**[3]:** May be used when specific backend is unknown. + +**[4]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. +### Body fields: + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**requirement:** `Opt-In` + + + +:warning: Body fields will be moved to complex attributes once the +semantic convention tooling supports complex attributes +(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `content` | undefined | The contents of the user message. | `What's the weather in Paris?` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +| `role` | string | The actual role of the message author as passed in the message. | `user`; `customer` | `Conditionally Required` if available and not equal to `user`. | ![Development](https://img.shields.io/badge/-development-blue) | + + + diff --git a/docs/registry/events/rpc/README.md b/docs/registry/events/rpc/README.md new file mode 100644 index 0000000000..595f2c1d59 --- /dev/null +++ b/docs/registry/events/rpc/README.md @@ -0,0 +1,16 @@ + + + + + +# RPC +
+Events + +| Name | Summary | Status| +| --- | --- | --- | +| [`rpc.message`](event-rpc-message.md) | Describes a message sent or received within the context of an RPC call. | ![Development](https://img.shields.io/badge/-development-blue) | + +
+ + diff --git a/docs/registry/events/rpc.md b/docs/registry/events/rpc/event-rpc-message.md similarity index 97% rename from docs/registry/events/rpc.md rename to docs/registry/events/rpc/event-rpc-message.md index 72dc61a0d7..3ddf35b603 100644 --- a/docs/registry/events/rpc.md +++ b/docs/registry/events/rpc/event-rpc-message.md @@ -3,7 +3,7 @@ -# RPC +# Event RPC Message ## RPC Message @@ -11,6 +11,8 @@ **Event Name:** `rpc.message` +**Namespace:** [`rpc`](README.md) + **Summary:** Describes a message sent or received within the context of an RPC call. diff --git a/docs/registry/events/session/README.md b/docs/registry/events/session/README.md new file mode 100644 index 0000000000..80681714f4 --- /dev/null +++ b/docs/registry/events/session/README.md @@ -0,0 +1,17 @@ + + + + + +# Session +
+Events + +| Name | Summary | Status| +| --- | --- | --- | +| [`session.end`](event-session-end.md) | Indicates that a session has ended. | ![Development](https://img.shields.io/badge/-development-blue) | +| [`session.start`](event-session-start.md) | Indicates that a new session has been started, optionally linking to the prior session. | ![Development](https://img.shields.io/badge/-development-blue) | + +
+ + diff --git a/docs/registry/events/session/event-session-end.md b/docs/registry/events/session/event-session-end.md new file mode 100644 index 0000000000..5a764d01a3 --- /dev/null +++ b/docs/registry/events/session/event-session-end.md @@ -0,0 +1,26 @@ + + + + + +# Event Session End + +## Session End + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**Event Name:** `session.end` + +**Namespace:** [`session`](README.md) + +**Summary:** Indicates that a session has ended. + + +**Description:** For instrumentation that tracks user behavior during user sessions, a `session.end` event SHOULD be emitted every time a session ends. When a session ends and continues as a new session, this event SHOULD be emitted prior to the `session.start` event. + +### Attributes: +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`session.id`](/docs/registry/attributes/session.md) | string | The ID of the session being ended. | `00112233-4455-6677-8899-aabbccddeeff` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | + + diff --git a/docs/registry/events/session.md b/docs/registry/events/session/event-session-start.md similarity index 70% rename from docs/registry/events/session.md rename to docs/registry/events/session/event-session-start.md index a50f6a688b..fb95a26bc1 100644 --- a/docs/registry/events/session.md +++ b/docs/registry/events/session/event-session-start.md @@ -3,23 +3,7 @@ -# Session - -## Session End - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -**Event Name:** `session.end` - -**Summary:** Indicates that a session has ended. - - -**Description:** For instrumentation that tracks user behavior during user sessions, a `session.end` event SHOULD be emitted every time a session ends. When a session ends and continues as a new session, this event SHOULD be emitted prior to the `session.start` event. - -### Attributes: -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`session.id`](/docs/registry/attributes/session.md) | string | The ID of the session being ended. | `00112233-4455-6677-8899-aabbccddeeff` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +# Event Session Start ## Session Start @@ -27,6 +11,8 @@ **Event Name:** `session.start` +**Namespace:** [`session`](README.md) + **Summary:** Indicates that a new session has been started, optionally linking to the prior session. diff --git a/templates/registry/markdown/event_details.md.j2 b/templates/registry/markdown/event_details.md.j2 new file mode 100644 index 0000000000..0353a3df7f --- /dev/null +++ b/templates/registry/markdown/event_details.md.j2 @@ -0,0 +1,49 @@ + + + + +{%- import 'stability.j2' as stability %} +{%- import 'requirement.j2' as requirement %} +{%- import 'attribute_table.j2' as at %} +{%- import 'body_field_table.j2' as body_table %} +{%- import 'event_macros.j2' as event %} + +# {{ ctx.id | title_case | acronym }} +{% for e in ctx.groups | sort(attribute='name') %} +## {{ e.name | title_case | acronym }} + +**Status:** {{ stability.badge(e.stability, e.deprecated) }} + +**Event Name:** `{{ e.name }}` + +**Namespace:** [`{{ ctx.namespace }}`](README.md) + +**Summary:** {{ e.brief | trim }} + +{%if e.note %} +**Description:** {{ e.note | trim }} +{% endif %} + +{%- if e.attributes | length > 0 %} +### Attributes: +{{ at.generate(e.attributes, "", "/docs/registry/attributes", e.lineage.attributes) | trim }} +{%- endif %} + +{%- if e.body %} +### Body fields: + +**Status:** {{ stability.badge(e.body.stability, e.body.deprecated) }} + +**requirement:** {{ requirement.render({"level": e.body.requirement_level, "name": e.name}, notes) }} + +:warning: Body fields will be moved to complex attributes once the +semantic convention tooling supports complex attributes +(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). + +{%- if e.body.fields != undefined and e.body.fields | length > 0 %} +{{ body_table.generate(e.body.fields) }} +{%- endif %} +{%- endif %} +{% endfor %} + + diff --git a/templates/registry/markdown/event_namespace.md.j2 b/templates/registry/markdown/event_namespace.md.j2 index cb28502a16..db84ab8e3c 100644 --- a/templates/registry/markdown/event_namespace.md.j2 +++ b/templates/registry/markdown/event_namespace.md.j2 @@ -8,40 +8,29 @@ {%- import 'body_field_table.j2' as body_table %} {%- import 'event_macros.j2' as event %} -# {{ ctx.id | title_case | acronym }} -{% for e in ctx.groups | sort(attribute='name') %} -## {{ e.name | title_case | acronym }} +# {{ ctx.namespace | title_case | acronym }} -**Status:** {{ stability.badge(e.stability, e.deprecated) }} +{%- if ctx.entities | length > 0 %} +
+Entities -**Event Name:** `{{ e.name }}` +| Name | Summary | Status| +| --- | --- | --- |{% for e in ctx.entities | sort(attribute='name') %} +| [`{{ e.name }}`]({{e.id | kebab_case}}.md) | {{ e.brief | trim }} | {{ stability.badge(e.stability, e.deprecated) }} |{% endfor %} -**Summary:** {{ e.brief | trim }} - -{%if e.note %} -**Description:** {{ e.note | trim }} -{% endif %} - -{%- if e.attributes | length > 0 %} -### Attributes: -{{ at.generate(e.attributes, "", "/docs/registry/attributes", e.lineage.attributes) | trim }} +
{%- endif %} -{%- if e.body %} -### Body fields: - -**Status:** {{ stability.badge(e.body.stability, e.body.deprecated) }} +{%- if ctx.events | length > 0 %} +
+Events -**requirement:** {{ requirement.render({"level": e.body.requirement_level, "name": e.name}, notes) }} +| Name | Summary | Status| +| --- | --- | --- |{% for e in ctx.events | sort(attribute='name') %} +| [`{{ e.name }}`]({{e.id | kebab_case}}.md) | {{ e.brief | trim }} | {{ stability.badge(e.stability, e.deprecated) }} |{% endfor %} -:warning: Body fields will be moved to complex attributes once the -semantic convention tooling supports complex attributes -(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). - -{%- if e.body.fields != undefined and e.body.fields | length > 0 %} -{{ body_table.generate(e.body.fields) }} -{%- endif %} +
{%- endif %} -{% endfor %} + diff --git a/templates/registry/markdown/event_readme.md.j2 b/templates/registry/markdown/event_readme.md.j2 index d4e2029355..1e86e8504b 100644 --- a/templates/registry/markdown/event_readme.md.j2 +++ b/templates/registry/markdown/event_readme.md.j2 @@ -25,10 +25,10 @@ Currently, the following namespaces exist: {% for bundle in ctx %} -{{ bundle.id | title_case | acronym }} +{{ bundle.id | title_case | acronym }} {%- for group in bundle.groups | sort(attribute='name') -%} - {%- set my_file_name = bundle.id | kebab_case ~ ".md#" ~ (group.name | kebab_case) -%} + {%- set my_file_name = bundle.id | kebab_case ~ "/" ~ (group.id | kebab_case) ~ ".md" -%} {{ group.name }} diff --git a/templates/registry/markdown/weaver.yaml b/templates/registry/markdown/weaver.yaml index 6be52803f8..21261c117f 100644 --- a/templates/registry/markdown/weaver.yaml +++ b/templates/registry/markdown/weaver.yaml @@ -24,9 +24,18 @@ templates: application_mode: single file_name: 'events/README.md' - pattern: event_namespace.md.j2 - filter: '.groups | map(select(.type == "event")) | group_by(.name | split(".") | .[0]) | map({id: .[0].id | split(".") | .[1], groups: .})' + filter: '.groups | map(select(.type | startswith("event"))) | group_by(.name | split(".") | .[0]) | map({ + id: .[0].id, + groups: ., + entities: [], + events: . | map(select(.type == "event")), + namespace: .[0].id | split(".") | .[1]})' + application_mode: each + file_name: 'events/{{ ctx.namespace | kebab_case }}//README.md' + - pattern: event_details.md.j2 + filter: '.groups | map(select(.type == "event")) | group_by(.name) | map({id: .[0].id, groups: ., namespace: .[0].id | split(".") | .[1]})' application_mode: each - file_name: 'events/{{ ctx.id | kebab_case }}.md' + file_name: 'events/{{ctx.namespace | kebab_case }}/{{ ctx.id | kebab_case }}.md' acronyms: - AI - AWS From 996f8048218b11fae524e720b1ccd858266c6318 Mon Sep 17 00:00:00 2001 From: James Thompson Date: Tue, 15 Jul 2025 11:13:28 +1000 Subject: [PATCH 3/5] Implementation of semconv meeting feedback --- docs/registry/events/README.md | 112 ------------------ docs/registry/events/app/README.md | 17 --- docs/registry/events/az/README.md | 16 --- docs/registry/events/azure/README.md | 16 --- docs/registry/events/browser/README.md | 16 --- docs/registry/events/device/README.md | 16 --- docs/registry/events/exception/README.md | 16 --- docs/registry/events/feature-flag/README.md | 16 --- docs/registry/events/gen-ai/README.md | 20 ---- docs/registry/events/rpc/README.md | 16 --- docs/registry/events/session/README.md | 17 --- .../app/event-app-screen-click.md | 2 +- .../app/event-app-widget-click.md | 2 +- .../az/event-az-resource-log.md | 2 +- .../azure/event-azure-resource-log.md | 2 +- .../browser/event-browser-web-vital.md | 2 +- .../device/event-device-app-lifecycle.md | 2 +- .../exception/event-exception.md | 2 +- .../event-feature-flag-evaluation.md | 2 +- .../gen-ai/event-gen-ai-assistant-message.md | 2 +- .../gen-ai/event-gen-ai-choice.md | 2 +- .../gen-ai/event-gen-ai-system-message.md | 2 +- .../gen-ai/event-gen-ai-tool-message.md | 2 +- .../gen-ai/event-gen-ai-user-message.md | 2 +- .../rpc/event-rpc-message.md | 2 +- .../session/event-session-end.md | 2 +- .../session/event-session-start.md | 2 +- .../registry/markdown/event_details.md.j2 | 2 +- .../registry/markdown/event_namespace.md.j2 | 36 ------ templates/registry/markdown/weaver.yaml | 15 +-- 30 files changed, 18 insertions(+), 345 deletions(-) delete mode 100644 docs/registry/events/README.md delete mode 100644 docs/registry/events/app/README.md delete mode 100644 docs/registry/events/az/README.md delete mode 100644 docs/registry/events/azure/README.md delete mode 100644 docs/registry/events/browser/README.md delete mode 100644 docs/registry/events/device/README.md delete mode 100644 docs/registry/events/exception/README.md delete mode 100644 docs/registry/events/feature-flag/README.md delete mode 100644 docs/registry/events/gen-ai/README.md delete mode 100644 docs/registry/events/rpc/README.md delete mode 100644 docs/registry/events/session/README.md rename docs/registry/{events => namespaces}/app/event-app-screen-click.md (98%) rename docs/registry/{events => namespaces}/app/event-app-widget-click.md (98%) rename docs/registry/{events => namespaces}/az/event-az-resource-log.md (98%) rename docs/registry/{events => namespaces}/azure/event-azure-resource-log.md (99%) rename docs/registry/{events => namespaces}/browser/event-browser-web-vital.md (98%) rename docs/registry/{events => namespaces}/device/event-device-app-lifecycle.md (99%) rename docs/registry/{events => namespaces}/exception/event-exception.md (98%) rename docs/registry/{events => namespaces}/feature-flag/event-feature-flag-evaluation.md (99%) rename docs/registry/{events => namespaces}/gen-ai/event-gen-ai-assistant-message.md (99%) rename docs/registry/{events => namespaces}/gen-ai/event-gen-ai-choice.md (99%) rename docs/registry/{events => namespaces}/gen-ai/event-gen-ai-system-message.md (99%) rename docs/registry/{events => namespaces}/gen-ai/event-gen-ai-tool-message.md (99%) rename docs/registry/{events => namespaces}/gen-ai/event-gen-ai-user-message.md (99%) rename docs/registry/{events => namespaces}/rpc/event-rpc-message.md (98%) rename docs/registry/{events => namespaces}/session/event-session-end.md (96%) rename docs/registry/{events => namespaces}/session/event-session-start.md (98%) delete mode 100644 templates/registry/markdown/event_namespace.md.j2 diff --git a/docs/registry/events/README.md b/docs/registry/events/README.md deleted file mode 100644 index a428a51cda..0000000000 --- a/docs/registry/events/README.md +++ /dev/null @@ -1,112 +0,0 @@ - - - - - -# Event registry - -The event registry is the catalog of available Events. - -> [!WARNING] -> -> The following registry overview is a work in progress. - -Currently, the following namespaces exist: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NamespaceEventStability
App
app.screen.clickDevelopment
app.widget.clickDevelopment
Az
az.resource.logDeprecated
Azure
azure.resource.logDevelopment
Browser
browser.web_vitalDevelopment
Device
device.app.lifecycleDevelopment
Exception
exceptionStable
Feature Flag
feature_flag.evaluationRelease Candidate
Gen AI
gen_ai.assistant.messageDevelopment
gen_ai.choiceDevelopment
gen_ai.system.messageDevelopment
gen_ai.tool.messageDevelopment
gen_ai.user.messageDevelopment
RPC
rpc.messageDevelopment
Session
session.endDevelopment
session.startDevelopment
diff --git a/docs/registry/events/app/README.md b/docs/registry/events/app/README.md deleted file mode 100644 index 7261a33e99..0000000000 --- a/docs/registry/events/app/README.md +++ /dev/null @@ -1,17 +0,0 @@ - - - - - -# App -
-Events - -| Name | Summary | Status| -| --- | --- | --- | -| [`app.screen.click`](event-app-screen-click.md) | This event represents an instantaneous click on the screen of an application. | ![Development](https://img.shields.io/badge/-development-blue) | -| [`app.widget.click`](event-app-widget-click.md) | This event indicates that an application widget has been clicked. | ![Development](https://img.shields.io/badge/-development-blue) | - -
- - diff --git a/docs/registry/events/az/README.md b/docs/registry/events/az/README.md deleted file mode 100644 index 8c7cf2ce3e..0000000000 --- a/docs/registry/events/az/README.md +++ /dev/null @@ -1,16 +0,0 @@ - - - - - -# Az -
-Events - -| Name | Summary | Status| -| --- | --- | --- | -| [`az.resource.log`](event-az-resource-log.md) | Deprecated. Use `azure.resource.log` instead. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `azure.resource.log`. | - -
- - diff --git a/docs/registry/events/azure/README.md b/docs/registry/events/azure/README.md deleted file mode 100644 index 24d044ec6f..0000000000 --- a/docs/registry/events/azure/README.md +++ /dev/null @@ -1,16 +0,0 @@ - - - - - -# Azure -
-Events - -| Name | Summary | Status| -| --- | --- | --- | -| [`azure.resource.log`](event-azure-resource-log.md) | 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. | ![Development](https://img.shields.io/badge/-development-blue) | - -
- - diff --git a/docs/registry/events/browser/README.md b/docs/registry/events/browser/README.md deleted file mode 100644 index 6c5383e3fb..0000000000 --- a/docs/registry/events/browser/README.md +++ /dev/null @@ -1,16 +0,0 @@ - - - - - -# Browser -
-Events - -| Name | Summary | Status| -| --- | --- | --- | -| [`browser.web_vital`](event-browser-web-vital.md) | This event describes the website performance metrics introduced by Google, See [web vitals](https://web.dev/vitals). | ![Development](https://img.shields.io/badge/-development-blue) | - -
- - diff --git a/docs/registry/events/device/README.md b/docs/registry/events/device/README.md deleted file mode 100644 index de6bca3089..0000000000 --- a/docs/registry/events/device/README.md +++ /dev/null @@ -1,16 +0,0 @@ - - - - - -# Device -
-Events - -| Name | Summary | Status| -| --- | --- | --- | -| [`device.app.lifecycle`](event-device-app-lifecycle.md) | This event represents an occurrence of a lifecycle transition on Android or iOS platform. | ![Development](https://img.shields.io/badge/-development-blue) | - -
- - diff --git a/docs/registry/events/exception/README.md b/docs/registry/events/exception/README.md deleted file mode 100644 index e4aa1a74cc..0000000000 --- a/docs/registry/events/exception/README.md +++ /dev/null @@ -1,16 +0,0 @@ - - - - - -# Exception -
-Events - -| Name | Summary | Status| -| --- | --- | --- | -| [`exception`](event-exception.md) | This event describes a single exception. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - -
- - diff --git a/docs/registry/events/feature-flag/README.md b/docs/registry/events/feature-flag/README.md deleted file mode 100644 index 75cb7408dc..0000000000 --- a/docs/registry/events/feature-flag/README.md +++ /dev/null @@ -1,16 +0,0 @@ - - - - - -# Feature Flag -
-Events - -| Name | Summary | Status| -| --- | --- | --- | -| [`feature_flag.evaluation`](event-feature-flag-evaluation.md) | Defines feature flag evaluation as an event. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | - -
- - diff --git a/docs/registry/events/gen-ai/README.md b/docs/registry/events/gen-ai/README.md deleted file mode 100644 index 18ed3549ff..0000000000 --- a/docs/registry/events/gen-ai/README.md +++ /dev/null @@ -1,20 +0,0 @@ - - - - - -# Gen AI -
-Events - -| Name | Summary | Status| -| --- | --- | --- | -| [`gen_ai.assistant.message`](event-gen-ai-assistant-message.md) | This event describes the assistant message passed to GenAI system. | ![Development](https://img.shields.io/badge/-development-blue) | -| [`gen_ai.choice`](event-gen-ai-choice.md) | This event describes the Gen AI response message. | ![Development](https://img.shields.io/badge/-development-blue) | -| [`gen_ai.system.message`](event-gen-ai-system-message.md) | This event describes the system instructions passed to the GenAI model. | ![Development](https://img.shields.io/badge/-development-blue) | -| [`gen_ai.tool.message`](event-gen-ai-tool-message.md) | This event describes the response from a tool or function call passed to the GenAI model. | ![Development](https://img.shields.io/badge/-development-blue) | -| [`gen_ai.user.message`](event-gen-ai-user-message.md) | This event describes the user message passed to the GenAI model. | ![Development](https://img.shields.io/badge/-development-blue) | - -
- - diff --git a/docs/registry/events/rpc/README.md b/docs/registry/events/rpc/README.md deleted file mode 100644 index 595f2c1d59..0000000000 --- a/docs/registry/events/rpc/README.md +++ /dev/null @@ -1,16 +0,0 @@ - - - - - -# RPC -
-Events - -| Name | Summary | Status| -| --- | --- | --- | -| [`rpc.message`](event-rpc-message.md) | Describes a message sent or received within the context of an RPC call. | ![Development](https://img.shields.io/badge/-development-blue) | - -
- - diff --git a/docs/registry/events/session/README.md b/docs/registry/events/session/README.md deleted file mode 100644 index 80681714f4..0000000000 --- a/docs/registry/events/session/README.md +++ /dev/null @@ -1,17 +0,0 @@ - - - - - -# Session -
-Events - -| Name | Summary | Status| -| --- | --- | --- | -| [`session.end`](event-session-end.md) | Indicates that a session has ended. | ![Development](https://img.shields.io/badge/-development-blue) | -| [`session.start`](event-session-start.md) | Indicates that a new session has been started, optionally linking to the prior session. | ![Development](https://img.shields.io/badge/-development-blue) | - -
- - diff --git a/docs/registry/events/app/event-app-screen-click.md b/docs/registry/namespaces/app/event-app-screen-click.md similarity index 98% rename from docs/registry/events/app/event-app-screen-click.md rename to docs/registry/namespaces/app/event-app-screen-click.md index 0e75d85112..1cc4add437 100644 --- a/docs/registry/events/app/event-app-screen-click.md +++ b/docs/registry/namespaces/app/event-app-screen-click.md @@ -11,7 +11,7 @@ **Event Name:** `app.screen.click` -**Namespace:** [`app`](README.md) + **Summary:** This event represents an instantaneous click on the screen of an application. diff --git a/docs/registry/events/app/event-app-widget-click.md b/docs/registry/namespaces/app/event-app-widget-click.md similarity index 98% rename from docs/registry/events/app/event-app-widget-click.md rename to docs/registry/namespaces/app/event-app-widget-click.md index b374715234..4f8e8a0c11 100644 --- a/docs/registry/events/app/event-app-widget-click.md +++ b/docs/registry/namespaces/app/event-app-widget-click.md @@ -11,7 +11,7 @@ **Event Name:** `app.widget.click` -**Namespace:** [`app`](README.md) + **Summary:** This event indicates that an application widget has been clicked. diff --git a/docs/registry/events/az/event-az-resource-log.md b/docs/registry/namespaces/az/event-az-resource-log.md similarity index 98% rename from docs/registry/events/az/event-az-resource-log.md rename to docs/registry/namespaces/az/event-az-resource-log.md index 8f5a82ce42..0f05539a8e 100644 --- a/docs/registry/events/az/event-az-resource-log.md +++ b/docs/registry/namespaces/az/event-az-resource-log.md @@ -11,7 +11,7 @@ **Event Name:** `az.resource.log` -**Namespace:** [`az`](README.md) + **Summary:** Deprecated. Use `azure.resource.log` instead. diff --git a/docs/registry/events/azure/event-azure-resource-log.md b/docs/registry/namespaces/azure/event-azure-resource-log.md similarity index 99% rename from docs/registry/events/azure/event-azure-resource-log.md rename to docs/registry/namespaces/azure/event-azure-resource-log.md index f3b6b39b53..e2392f49f3 100644 --- a/docs/registry/events/azure/event-azure-resource-log.md +++ b/docs/registry/namespaces/azure/event-azure-resource-log.md @@ -11,7 +11,7 @@ **Event Name:** `azure.resource.log` -**Namespace:** [`azure`](README.md) + **Summary:** 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. diff --git a/docs/registry/events/browser/event-browser-web-vital.md b/docs/registry/namespaces/browser/event-browser-web-vital.md similarity index 98% rename from docs/registry/events/browser/event-browser-web-vital.md rename to docs/registry/namespaces/browser/event-browser-web-vital.md index 898e8f7d7b..529f59deda 100644 --- a/docs/registry/events/browser/event-browser-web-vital.md +++ b/docs/registry/namespaces/browser/event-browser-web-vital.md @@ -11,7 +11,7 @@ **Event Name:** `browser.web_vital` -**Namespace:** [`browser`](README.md) + **Summary:** This event describes the website performance metrics introduced by Google, See [web vitals](https://web.dev/vitals). diff --git a/docs/registry/events/device/event-device-app-lifecycle.md b/docs/registry/namespaces/device/event-device-app-lifecycle.md similarity index 99% rename from docs/registry/events/device/event-device-app-lifecycle.md rename to docs/registry/namespaces/device/event-device-app-lifecycle.md index 28815ff8c9..517ffaa3fd 100644 --- a/docs/registry/events/device/event-device-app-lifecycle.md +++ b/docs/registry/namespaces/device/event-device-app-lifecycle.md @@ -11,7 +11,7 @@ **Event Name:** `device.app.lifecycle` -**Namespace:** [`device`](README.md) + **Summary:** This event represents an occurrence of a lifecycle transition on Android or iOS platform. diff --git a/docs/registry/events/exception/event-exception.md b/docs/registry/namespaces/exception/event-exception.md similarity index 98% rename from docs/registry/events/exception/event-exception.md rename to docs/registry/namespaces/exception/event-exception.md index fbd1e988bb..760a954430 100644 --- a/docs/registry/events/exception/event-exception.md +++ b/docs/registry/namespaces/exception/event-exception.md @@ -11,7 +11,7 @@ **Event Name:** `exception` -**Namespace:** [`exception`](README.md) + **Summary:** This event describes a single exception. diff --git a/docs/registry/events/feature-flag/event-feature-flag-evaluation.md b/docs/registry/namespaces/feature-flag/event-feature-flag-evaluation.md similarity index 99% rename from docs/registry/events/feature-flag/event-feature-flag-evaluation.md rename to docs/registry/namespaces/feature-flag/event-feature-flag-evaluation.md index 8239dd2f11..83b97f1c7f 100644 --- a/docs/registry/events/feature-flag/event-feature-flag-evaluation.md +++ b/docs/registry/namespaces/feature-flag/event-feature-flag-evaluation.md @@ -11,7 +11,7 @@ **Event Name:** `feature_flag.evaluation` -**Namespace:** [`feature_flag`](README.md) + **Summary:** Defines feature flag evaluation as an event. diff --git a/docs/registry/events/gen-ai/event-gen-ai-assistant-message.md b/docs/registry/namespaces/gen-ai/event-gen-ai-assistant-message.md similarity index 99% rename from docs/registry/events/gen-ai/event-gen-ai-assistant-message.md rename to docs/registry/namespaces/gen-ai/event-gen-ai-assistant-message.md index eba1eea1b9..d682300c31 100644 --- a/docs/registry/events/gen-ai/event-gen-ai-assistant-message.md +++ b/docs/registry/namespaces/gen-ai/event-gen-ai-assistant-message.md @@ -11,7 +11,7 @@ **Event Name:** `gen_ai.assistant.message` -**Namespace:** [`gen_ai`](README.md) + **Summary:** This event describes the assistant message passed to GenAI system. diff --git a/docs/registry/events/gen-ai/event-gen-ai-choice.md b/docs/registry/namespaces/gen-ai/event-gen-ai-choice.md similarity index 99% rename from docs/registry/events/gen-ai/event-gen-ai-choice.md rename to docs/registry/namespaces/gen-ai/event-gen-ai-choice.md index ebbc35d112..f8d06c608f 100644 --- a/docs/registry/events/gen-ai/event-gen-ai-choice.md +++ b/docs/registry/namespaces/gen-ai/event-gen-ai-choice.md @@ -11,7 +11,7 @@ **Event Name:** `gen_ai.choice` -**Namespace:** [`gen_ai`](README.md) + **Summary:** This event describes the Gen AI response message. diff --git a/docs/registry/events/gen-ai/event-gen-ai-system-message.md b/docs/registry/namespaces/gen-ai/event-gen-ai-system-message.md similarity index 99% rename from docs/registry/events/gen-ai/event-gen-ai-system-message.md rename to docs/registry/namespaces/gen-ai/event-gen-ai-system-message.md index 75fdab4865..b1742b8e43 100644 --- a/docs/registry/events/gen-ai/event-gen-ai-system-message.md +++ b/docs/registry/namespaces/gen-ai/event-gen-ai-system-message.md @@ -11,7 +11,7 @@ **Event Name:** `gen_ai.system.message` -**Namespace:** [`gen_ai`](README.md) + **Summary:** This event describes the system instructions passed to the GenAI model. diff --git a/docs/registry/events/gen-ai/event-gen-ai-tool-message.md b/docs/registry/namespaces/gen-ai/event-gen-ai-tool-message.md similarity index 99% rename from docs/registry/events/gen-ai/event-gen-ai-tool-message.md rename to docs/registry/namespaces/gen-ai/event-gen-ai-tool-message.md index fca7d226e6..987ffc81c6 100644 --- a/docs/registry/events/gen-ai/event-gen-ai-tool-message.md +++ b/docs/registry/namespaces/gen-ai/event-gen-ai-tool-message.md @@ -11,7 +11,7 @@ **Event Name:** `gen_ai.tool.message` -**Namespace:** [`gen_ai`](README.md) + **Summary:** This event describes the response from a tool or function call passed to the GenAI model. diff --git a/docs/registry/events/gen-ai/event-gen-ai-user-message.md b/docs/registry/namespaces/gen-ai/event-gen-ai-user-message.md similarity index 99% rename from docs/registry/events/gen-ai/event-gen-ai-user-message.md rename to docs/registry/namespaces/gen-ai/event-gen-ai-user-message.md index 8a05af32ab..ad01ce79ad 100644 --- a/docs/registry/events/gen-ai/event-gen-ai-user-message.md +++ b/docs/registry/namespaces/gen-ai/event-gen-ai-user-message.md @@ -11,7 +11,7 @@ **Event Name:** `gen_ai.user.message` -**Namespace:** [`gen_ai`](README.md) + **Summary:** This event describes the user message passed to the GenAI model. diff --git a/docs/registry/events/rpc/event-rpc-message.md b/docs/registry/namespaces/rpc/event-rpc-message.md similarity index 98% rename from docs/registry/events/rpc/event-rpc-message.md rename to docs/registry/namespaces/rpc/event-rpc-message.md index 3ddf35b603..46f8387f87 100644 --- a/docs/registry/events/rpc/event-rpc-message.md +++ b/docs/registry/namespaces/rpc/event-rpc-message.md @@ -11,7 +11,7 @@ **Event Name:** `rpc.message` -**Namespace:** [`rpc`](README.md) + **Summary:** Describes a message sent or received within the context of an RPC call. diff --git a/docs/registry/events/session/event-session-end.md b/docs/registry/namespaces/session/event-session-end.md similarity index 96% rename from docs/registry/events/session/event-session-end.md rename to docs/registry/namespaces/session/event-session-end.md index 5a764d01a3..0cc3d2c8ee 100644 --- a/docs/registry/events/session/event-session-end.md +++ b/docs/registry/namespaces/session/event-session-end.md @@ -11,7 +11,7 @@ **Event Name:** `session.end` -**Namespace:** [`session`](README.md) + **Summary:** Indicates that a session has ended. diff --git a/docs/registry/events/session/event-session-start.md b/docs/registry/namespaces/session/event-session-start.md similarity index 98% rename from docs/registry/events/session/event-session-start.md rename to docs/registry/namespaces/session/event-session-start.md index fb95a26bc1..ba6996dfb6 100644 --- a/docs/registry/events/session/event-session-start.md +++ b/docs/registry/namespaces/session/event-session-start.md @@ -11,7 +11,7 @@ **Event Name:** `session.start` -**Namespace:** [`session`](README.md) + **Summary:** Indicates that a new session has been started, optionally linking to the prior session. diff --git a/templates/registry/markdown/event_details.md.j2 b/templates/registry/markdown/event_details.md.j2 index 0353a3df7f..7c83e59609 100644 --- a/templates/registry/markdown/event_details.md.j2 +++ b/templates/registry/markdown/event_details.md.j2 @@ -16,7 +16,7 @@ **Event Name:** `{{ e.name }}` -**Namespace:** [`{{ ctx.namespace }}`](README.md) +{# **Namespace:** [`{{ ctx.namespace }}`](README.md) #} **Summary:** {{ e.brief | trim }} diff --git a/templates/registry/markdown/event_namespace.md.j2 b/templates/registry/markdown/event_namespace.md.j2 deleted file mode 100644 index db84ab8e3c..0000000000 --- a/templates/registry/markdown/event_namespace.md.j2 +++ /dev/null @@ -1,36 +0,0 @@ - - - - -{%- import 'stability.j2' as stability %} -{%- import 'requirement.j2' as requirement %} -{%- import 'attribute_table.j2' as at %} -{%- import 'body_field_table.j2' as body_table %} -{%- import 'event_macros.j2' as event %} - -# {{ ctx.namespace | title_case | acronym }} - -{%- if ctx.entities | length > 0 %} -
-Entities - -| Name | Summary | Status| -| --- | --- | --- |{% for e in ctx.entities | sort(attribute='name') %} -| [`{{ e.name }}`]({{e.id | kebab_case}}.md) | {{ e.brief | trim }} | {{ stability.badge(e.stability, e.deprecated) }} |{% endfor %} - -
-{%- endif %} - -{%- if ctx.events | length > 0 %} -
-Events - -| Name | Summary | Status| -| --- | --- | --- |{% for e in ctx.events | sort(attribute='name') %} -| [`{{ e.name }}`]({{e.id | kebab_case}}.md) | {{ e.brief | trim }} | {{ stability.badge(e.stability, e.deprecated) }} |{% endfor %} - -
-{%- endif %} - - - diff --git a/templates/registry/markdown/weaver.yaml b/templates/registry/markdown/weaver.yaml index 21261c117f..a32c1e80ec 100644 --- a/templates/registry/markdown/weaver.yaml +++ b/templates/registry/markdown/weaver.yaml @@ -19,23 +19,10 @@ templates: filter: '.groups | map(select(.type == "entity")) | group_by(.name | split(".") | .[0]) | map({id: .[0].id | split(".") | .[1], groups: .})' application_mode: each file_name: 'entities/{{ ctx.id | kebab_case }}.md' - - pattern: event_readme.md.j2 - filter: '.groups | map(select(.type == "event")) | group_by(.name | split(".") | .[0]) | map({id: .[0].id | split(".") | .[1], groups: .})' - application_mode: single - file_name: 'events/README.md' - - pattern: event_namespace.md.j2 - filter: '.groups | map(select(.type | startswith("event"))) | group_by(.name | split(".") | .[0]) | map({ - id: .[0].id, - groups: ., - entities: [], - events: . | map(select(.type == "event")), - namespace: .[0].id | split(".") | .[1]})' - application_mode: each - file_name: 'events/{{ ctx.namespace | kebab_case }}//README.md' - pattern: event_details.md.j2 filter: '.groups | map(select(.type == "event")) | group_by(.name) | map({id: .[0].id, groups: ., namespace: .[0].id | split(".") | .[1]})' application_mode: each - file_name: 'events/{{ctx.namespace | kebab_case }}/{{ ctx.id | kebab_case }}.md' + file_name: 'namespaces/{{ctx.namespace | kebab_case }}/{{ ctx.id | kebab_case }}.md' acronyms: - AI - AWS From a9453cc936bf3fb7faa1ecbd846628c3240990ce Mon Sep 17 00:00:00 2001 From: James Thompson Date: Tue, 15 Jul 2025 13:12:15 +1000 Subject: [PATCH 4/5] Removal of events to identify gap --- docs/app/app.md | 71 +-- docs/azure/README.md | 15 +- docs/azure/events.md | 64 --- docs/browser/events.md | 54 -- docs/code/README.md | 34 +- docs/database/oracledb.md | 4 +- docs/exceptions/README.md | 2 +- docs/exceptions/exceptions-logs.md | 47 +- docs/exceptions/exceptions-spans.md | 83 ---- docs/feature-flags/feature-flags-logs.md | 103 +--- docs/gen-ai/gen-ai-events.md | 460 +----------------- docs/general/recording-errors.md | 2 +- docs/general/session.md | 77 +-- docs/general/trace.md | 3 +- docs/mobile/README.md | 16 +- docs/mobile/events.md | 80 --- docs/registry/attributes/code.md | 34 +- docs/registry/attributes/exception.md | 34 +- .../namespaces/exception/event-exception.md | 34 +- docs/rpc/rpc-spans.md | 46 +- model/code/registry.yaml | 33 +- model/database/spans.yaml | 6 +- model/exceptions/registry.yaml | 32 ++ model/rpc/spans.yaml | 2 +- .../registry/markdown/event_readme.md.j2 | 41 -- 25 files changed, 260 insertions(+), 1117 deletions(-) delete mode 100644 docs/azure/events.md delete mode 100644 docs/browser/events.md delete mode 100644 docs/exceptions/exceptions-spans.md delete mode 100644 docs/mobile/events.md delete mode 100644 templates/registry/markdown/event_readme.md.j2 diff --git a/docs/app/app.md b/docs/app/app.md index 72e6b25c01..45fb0ba7a9 100644 --- a/docs/app/app.md +++ b/docs/app/app.md @@ -9,76 +9,9 @@ linkTitle: App This document defines events related to client-side applications (e.g. web apps or mobile apps). - +## Events -- [Click Events](#click-events) - - [Event: `app.screen.click`](#event-appscreenclick) - - [Event: `app.widget.click`](#event-appwidgetclick) -- [Attributes](#attributes) - - - -## Click Events - -### Event: `app.screen.click` - - - - - - - - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -The event name MUST be `app.screen.click`. - -This event represents an instantaneous click on the screen of an application. - -The `app.screen.click` event can be used to indicate that a user has clicked or tapped on the screen portion of an application. Clicks outside of an application's active area SHOULD NOT generate this event. This event does not differentiate between touch/mouse down and touch/mouse up. Implementations SHOULD give preference to generating this event at the time the click is complete, typically on touch release or mouse up. The location of the click event MUST be provided in absolute screen pixels. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`app.screen.coordinate.x`](/docs/registry/attributes/app.md) | int | The x (horizontal) coordinate of a screen coordinate, in screen pixels. | `0`; `131` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`app.screen.coordinate.y`](/docs/registry/attributes/app.md) | int | The y (vertical) component of a screen coordinate, in screen pixels. | `12`; `99` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - - -### Event: `app.widget.click` - - - - - - - - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -The event name MUST be `app.widget.click`. - -This event indicates that an application widget has been clicked. - -Use this event to indicate that visual application component has been clicked, typically through a user's manual interaction. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`app.widget.id`](/docs/registry/attributes/app.md) | string | An identifier that uniquely differentiates this widget from other widgets in the same application. [1] | `f9bc787d-ff05-48ad-90e1-fca1d46130b3`; `submit_order_1829` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`app.screen.coordinate.x`](/docs/registry/attributes/app.md) | int | The x (horizontal) coordinate of a screen coordinate, in screen pixels. | `0`; `131` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`app.screen.coordinate.y`](/docs/registry/attributes/app.md) | int | The y (vertical) component of a screen coordinate, in screen pixels. | `12`; `99` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`app.widget.name`](/docs/registry/attributes/app.md) | string | The name of an application widget. [2] | `submit`; `attack`; `Clear Cart` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1] `app.widget.id`:** A widget is an application component, typically an on-screen visual GUI element. - -**[2] `app.widget.name`:** A widget is an application component, typically an on-screen visual GUI element. - - - - - +Is now described in the namespace registry. ## Attributes diff --git a/docs/azure/README.md b/docs/azure/README.md index 5dd9397759..b7c39af984 100644 --- a/docs/azure/README.md +++ b/docs/azure/README.md @@ -1,16 +1,9 @@ -# Semantic conventions for Azure resource logs +# Azure -**Status**: [Development][DocumentStatus] - -This document describes Azure Resource Logs, see [Azure Resource Log Top-level Schema][AzureResourceSchema]. - -Semantic conventions are defined for the following signals: - -* [Events](events.md) - -[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status -[AzureResourceSchema]: https://learn.microsoft.com/azure/azure-monitor/essentials/resource-logs-schema#top-level-common-schema +This page has moved to +[Azure](/docs/registry/namespaces/azure/event-azure-resource-log.md). diff --git a/docs/azure/events.md b/docs/azure/events.md deleted file mode 100644 index 52df5d5c69..0000000000 --- a/docs/azure/events.md +++ /dev/null @@ -1,64 +0,0 @@ - - -# Semantic conventions for Azure resource log events - -**Status**: [Development][DocumentStatus] - -This document defines semantic conventions for instrumentations that emit Azure -Resource Log events. - -## Azure Resource Log - - - - - - - - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -The event name MUST be `azure.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 | -|---|---|---|---|---|---| -| [`azure.service.request.id`](/docs/registry/attributes/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` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`cloud.resource_id`](/docs/registry/attributes/cloud.md) | string | The [Fully Qualified Azure Resource ID](https://learn.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//resourceGroups//providers/Microsoft.Web/sites//functions/` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | - -**Body fields:** - -:warning: Body fields will be moved to complex attributes once the -semantic convention tooling supports complex attributes -(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). - -| 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` | ![Development](https://img.shields.io/badge/-development-blue) | -| `correlation.id` | string | The correlation ID of the log entry. | `607964b6-41a5-4e24-a5db-db7aab3b9b34` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| `duration` | int | The duration of the operations in milliseconds. | `1000` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| `identity` | undefined | "A JSON blob that describes the identity of the user or application that performed the operation." [1] | | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -| `operation.name` | string | The name of the operation. | `SecretGet`; `Microsoft.ApiManagement/GatewayLogs`; `ApplicationGatewayAccess` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| `operation.version` | string | The version of the operation. | `1.0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| `properties` | undefined | The properties provided in the Azure Resource Log. | | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| `result.description` | string | The description of the result. | `The operation was successful`; `The operation failed` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| `result.signature` | string | The substatus of associated with the logged event. | `OK` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| `result.type` | string | The status associated with the logged event. | `Succeeded`; `Failed`; `Started` | `Recommended` | ![Development](https://img.shields.io/badge/-development-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] | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1]:** Typically, this field includes the authorization and claims or JWT token from Active Directory. - -> [!Warning] -> This field contains sensitive (PII) information. - -**[2] `tenant.id`:** if the event is tied to an Active Directory tenant. - - - - - - -[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/browser/events.md b/docs/browser/events.md deleted file mode 100644 index c1aec9abb0..0000000000 --- a/docs/browser/events.md +++ /dev/null @@ -1,54 +0,0 @@ - - -# Semantic conventions for browser events - -**Status**: [Development][DocumentStatus] - -This document defines semantic conventions for browser (web) instrumentations -that emit events. - -## WebVital Event - - - - - - - - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -The event name MUST be `browser.web_vital`. - -This event describes the website performance metrics introduced by Google, See [web vitals](https://web.dev/vitals). - -**Body fields:** - -:warning: Body fields will be moved to complex attributes once the -semantic convention tooling supports complex attributes -(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). - -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| `delta` | double | The delta between the current value and the last-reported value. See [delta](https://github.com/GoogleChrome/web-vitals?tab=readme-ov-file#report-only-the-delta-of-changes). | `0.2` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -| `id` | string | A unique ID representing this particular metric instance. | `v3-1677874579383-6381583661209` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -| `name` | enum | Name of the web vital. | `cls` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -| `value` | double | Value of the web vital. | `1.0` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | - -`name` 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 | -|---|---|---| -| `cls` | Cumulative Layout Shift. See [cls](https://web.dev/articles/cls). | ![Development](https://img.shields.io/badge/-development-blue) | -| `fid` | First Input Delay. See [fid](https://web.dev/articles/fid). | ![Development](https://img.shields.io/badge/-development-blue) | -| `inp` | Interation to Next Paint. See [inp](https://web.dev/articles/inp). | ![Development](https://img.shields.io/badge/-development-blue) | -| `lcp` | Largest Contentful Paint. See [lcp](https://web.dev/articles/lcp). | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - - -[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/code/README.md b/docs/code/README.md index 574c4b94b2..ccdf5ade78 100644 --- a/docs/code/README.md +++ b/docs/code/README.md @@ -23,7 +23,7 @@ This document defines semantic conventions for source code. | [`code.file.path`](/docs/registry/attributes/code.md) | string | The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). This attribute MUST NOT be used on the Profile signal since the data is already captured in 'message Function'. This constraint is imposed to prevent redundancy and maintain data integrity. | `/usr/local/MyApplication/content_root/app/index.php` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`code.function.name`](/docs/registry/attributes/code.md) | string | The method or function fully-qualified name without arguments. The value should fit the natural representation of the language runtime, which is also likely the same used within `code.stacktrace` attribute value. This attribute MUST NOT be used on the Profile signal since the data is already captured in 'message Function'. This constraint is imposed to prevent redundancy and maintain data integrity. [1] | `com.example.MyHttpService.serveRequest`; `GuzzleHttp\Client::transfer`; `fopen` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`code.line.number`](/docs/registry/attributes/code.md) | int | The line number in `code.file.path` best representing the operation. It SHOULD point within the code unit named in `code.function.name`. This attribute MUST NOT be used on the Profile signal since the data is already captured in 'message Line'. This constraint is imposed to prevent redundancy and maintain data integrity. | `42` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`code.stacktrace`](/docs/registry/attributes/code.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is identical to [`exception.stacktrace`](/docs/exceptions/exceptions-spans.md#stacktrace-representation). This attribute MUST NOT be used on the Profile signal since the data is already captured in 'message Location'. This constraint is imposed to prevent redundancy and maintain data integrity. | `at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`code.stacktrace`](/docs/registry/attributes/code.md) | string | A stacktrace as a string in the natural representation for the language runtime. This attribute MUST NOT be used on the Profile signal since the data is already captured in 'message Location'. This constraint is imposed to prevent redundancy and maintain data integrity. [2] | `at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `code.function.name`:** Values and format depends on each language runtime, thus it is impossible to provide an exhaustive list of examples. The values are usually the same (or prefixes of) the ones found in native stack trace representation stored in @@ -41,6 +41,38 @@ Examples: * Rust: `playground::my_module::my_cool_func` * C function: `fopen` +**[2] `code.stacktrace`:** The table below, adapted from [Google Cloud][gcp-error-reporting], includes +possible representations of stacktraces in various languages. The table is not +meant to be a recommendation for any particular language, although SIGs are free +to adopt them if they see fit. + +| Language | Format | +| ---------- | ------------------------------------------------------------------- | +| C# | the return value of [Exception.ToString()][csharp-stacktrace] | +| Elixir | the return value of [Exception.format/3][elixir-stacktrace] | +| Erlang | the return value of [`erl_error:format`][erlang-stacktrace] | +| Go | the return value of [runtime.Stack][go-stacktrace] | +| Java | the contents of [Throwable.printStackTrace()][java-stacktrace] | +| Javascript | the return value of [error.stack][js-stacktrace] as returned by V8 | +| Python | the return value of [traceback.format_exc()][python-stacktrace] | +| Ruby | the return value of [Exception.full_message][ruby-full-message] | + +Backends can use the language specified methodology for generating a stacktrace +combined with platform information from the +[telemetry sdk resource][telemetry-sdk-resource] in order to extract more fine +grained information from a stacktrace, if necessary. + +[gcp-error-reporting]: https://cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report +[java-stacktrace]: https://docs.oracle.com/javase/7/docs/api/java/lang/Throwable.html#printStackTrace%28%29 +[python-stacktrace]: https://docs.python.org/3/library/traceback.html#traceback.format_exc +[js-stacktrace]: https://v8.dev/docs/stack-trace-api +[ruby-full-message]: https://docs.ruby-lang.org/en/3.4/Exception.html#method-i-full_message +[csharp-stacktrace]: https://docs.microsoft.com/dotnet/api/system.exception.tostring +[go-stacktrace]: https://pkg.go.dev/runtime/debug#Stack +[telemetry-sdk-resource]: ../resource/README.md#telemetry-sdk +[erlang-stacktrace]: https://www.erlang.org/doc/apps/stdlib/erl_error.html#format_exception/3 +[elixir-stacktrace]: https://hexdocs.pm/elixir/1.14.3/Exception.html#format/3 + diff --git a/docs/database/oracledb.md b/docs/database/oracledb.md index 8689528d29..047b0d565f 100644 --- a/docs/database/oracledb.md +++ b/docs/database/oracledb.md @@ -89,9 +89,9 @@ section. **[12] `db.query.summary`:** if available through instrumentation hooks or if the instrumentation supports generating a query summary. -**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. +**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. -**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless explicitly configured and sanitized to exclude sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). Parameterized query text MUST also NOT be collected by default unless explicitly configured. The query parameter values themselves are opt-in, see [`db.query.parameter.`](../registry/attributes/db.md)). +**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless explicitly configured and sanitized to exclude sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). Parameterized query text MUST also NOT be collected by default unless explicitly configured. The query parameter values themselves are opt-in, see [`db.query.parameter.`](/docs/registry/attributes/db.md)). **[15] `db.stored_procedure.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. diff --git a/docs/exceptions/README.md b/docs/exceptions/README.md index 5934a07cfc..c8d78c156c 100644 --- a/docs/exceptions/README.md +++ b/docs/exceptions/README.md @@ -8,7 +8,7 @@ linkTitle: Exceptions Semantic conventions for Exceptions are defined for the following signals: -* [Exceptions on spans](exceptions-spans.md): Semantic Conventions for Exceptions associated with *spans*. +* Events: is described in the namespace registry * [Exceptions in logs](exceptions-logs.md): Semantic Conventions for Exceptions recorded in *logs*. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/exceptions/exceptions-logs.md b/docs/exceptions/exceptions-logs.md index e50ba4f761..3f3f913bab 100644 --- a/docs/exceptions/exceptions-logs.md +++ b/docs/exceptions/exceptions-logs.md @@ -10,14 +10,6 @@ This document defines semantic conventions for recording exceptions on [logs](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.46.0/specification/logs/api.md#emit-a-logrecord) emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.46.0/specification/logs/api.md#logger). - - -- [Recording an exception](#recording-an-exception) -- [Attributes](#attributes) - - [Stacktrace representation](#stacktrace-representation) - - - ## Recording an exception Exceptions SHOULD be recorded as attributes on the @@ -46,20 +38,47 @@ The table below indicates which attributes should be added to the |---|---|---|---|---|---| | [`exception.message`](/docs/registry/attributes/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) | | [`exception.type`](/docs/registry/attributes/exception.md) | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`exception.stacktrace`](/docs/registry/attributes/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`exception.stacktrace`](/docs/registry/attributes/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. [3] | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise. **[2] `exception.type`:** Required if `exception.message` is not set, recommended otherwise. +**[3] `exception.stacktrace`:** The table below, adapted from [Google Cloud][gcp-error-reporting], includes +possible representations of stacktraces in various languages. The table is not +meant to be a recommendation for any particular language, although SIGs are free +to adopt them if they see fit. + +| Language | Format | +| ---------- | ------------------------------------------------------------------- | +| C# | the return value of [Exception.ToString()][csharp-stacktrace] | +| Elixir | the return value of [Exception.format/3][elixir-stacktrace] | +| Erlang | the return value of [`erl_error:format`][erlang-stacktrace] | +| Go | the return value of [runtime.Stack][go-stacktrace] | +| Java | the contents of [Throwable.printStackTrace()][java-stacktrace] | +| Javascript | the return value of [error.stack][js-stacktrace] as returned by V8 | +| Python | the return value of [traceback.format_exc()][python-stacktrace] | +| Ruby | the return value of [Exception.full_message][ruby-full-message] | + +Backends can use the language specified methodology for generating a stacktrace +combined with platform information from the +[telemetry sdk resource][telemetry-sdk-resource] in order to extract more fine +grained information from a stacktrace, if necessary. + +[gcp-error-reporting]: https://cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report +[java-stacktrace]: https://docs.oracle.com/javase/7/docs/api/java/lang/Throwable.html#printStackTrace%28%29 +[python-stacktrace]: https://docs.python.org/3/library/traceback.html#traceback.format_exc +[js-stacktrace]: https://v8.dev/docs/stack-trace-api +[ruby-full-message]: https://docs.ruby-lang.org/en/3.4/Exception.html#method-i-full_message +[csharp-stacktrace]: https://docs.microsoft.com/dotnet/api/system.exception.tostring +[go-stacktrace]: https://pkg.go.dev/runtime/debug#Stack +[telemetry-sdk-resource]: ../resource/README.md#telemetry-sdk +[erlang-stacktrace]: https://www.erlang.org/doc/apps/stdlib/erl_error.html#format_exception/3 +[elixir-stacktrace]: https://hexdocs.pm/elixir/1.14.3/Exception.html#format/3 + -### Stacktrace representation - -Same as [Trace Semantic Conventions for Exceptions - Stacktrace -Representation](exceptions-spans.md#stacktrace-representation). - [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md deleted file mode 100644 index c39ca0ad7d..0000000000 --- a/docs/exceptions/exceptions-spans.md +++ /dev/null @@ -1,83 +0,0 @@ - - -# Semantic conventions for exceptions on spans - -**Status**: [Stable][DocumentStatus] - -This document defines semantic conventions for recording application -exceptions associated with spans. - - - -- [Exception event](#exception-event) - - [Stacktrace representation](#stacktrace-representation) - - - -## Exception event - - - - - - - - -**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/registry/attributes/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) | -| [`exception.type`](/docs/registry/attributes/exception.md) | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`exception.escaped`](/docs/registry/attributes/exception.md) | boolean | Indicates that the exception is escaping the scope of the span. | | `Recommended` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
It's no longer recommended to record exceptions that are handled and do not escape the scope of a span. | -| [`exception.stacktrace`](/docs/registry/attributes/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - -**[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise. - -**[2] `exception.type`:** Required if `exception.message` is not set, recommended otherwise. - - - - - - -### Stacktrace representation - -The table below, adapted from [Google Cloud][gcp-error-reporting], includes -possible representations of stacktraces in various languages. The table is not -meant to be a recommendation for any particular language, although SIGs are free -to adopt them if they see fit. - -| Language | Format | -| ---------- | ------------------------------------------------------------------- | -| C# | the return value of [Exception.ToString()][csharp-stacktrace] | -| Elixir | the return value of [Exception.format/3][elixir-stacktrace] | -| Erlang | the return value of [`erl_error:format`][erlang-stacktrace] | -| Go | the return value of [runtime.Stack][go-stacktrace] | -| Java | the contents of [Throwable.printStackTrace()][java-stacktrace] | -| Javascript | the return value of [error.stack][js-stacktrace] as returned by V8 | -| Python | the return value of [traceback.format_exc()][python-stacktrace] | -| Ruby | the return value of [Exception.full_message][ruby-full-message] | - -Backends can use the language specified methodology for generating a stacktrace -combined with platform information from the -[telemetry sdk resource][telemetry-sdk-resource] in order to extract more fine -grained information from a stacktrace, if necessary. - -[gcp-error-reporting]: https://cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report -[java-stacktrace]: https://docs.oracle.com/javase/7/docs/api/java/lang/Throwable.html#printStackTrace%28%29 -[python-stacktrace]: https://docs.python.org/3/library/traceback.html#traceback.format_exc -[js-stacktrace]: https://v8.dev/docs/stack-trace-api -[ruby-full-message]: https://docs.ruby-lang.org/en/3.4/Exception.html#method-i-full_message -[csharp-stacktrace]: https://docs.microsoft.com/dotnet/api/system.exception.tostring -[go-stacktrace]: https://pkg.go.dev/runtime/debug#Stack -[telemetry-sdk-resource]: ../resource/README.md#telemetry-sdk -[erlang-stacktrace]: https://www.erlang.org/doc/apps/stdlib/erl_error.html#format_exception/3 -[elixir-stacktrace]: https://hexdocs.pm/elixir/1.14.3/Exception.html#format/3 -[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 094f2f89b5..396e6040fe 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -22,13 +22,6 @@ For example, a feature could be enabled only for a specific subset of users base Since feature flags are dynamic and affect runtime behavior, it's important to collect relevant feature flag telemetry signals. This can be used to determine the impact a feature has on a request, enabling enhanced observability use cases, such as A/B testing or progressive feature releases. - - -- [Recording an evaluation](#recording-an-evaluation) -- [Evaluation event](#evaluation-event) - - - ## Recording an evaluation Feature flag evaluations SHOULD be recorded as attributes on the @@ -36,100 +29,8 @@ Feature flag evaluations SHOULD be recorded as attributes on the operations. Evaluations MAY be recorded on "logs" or "events" depending on the context. -## Evaluation event - -The table below indicates which attributes should be added to the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.46.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. - - - - - - - - -**Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) - -The event name MUST be `feature_flag.evaluation`. - -Defines feature flag evaluation as an event. - -A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag value is evaluated, which may happen many times over the course of an application lifecycle. For example, a website A/B testing different animations may evaluate a flag each time a button is clicked. A `feature_flag.evaluation` event is emitted on each evaluation even if the result is the same. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`feature_flag.key`](/docs/registry/attributes/feature-flag.md) | string | The lookup key of the feature flag. | `logo-color` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`error.type`](/docs/registry/attributes/error.md) | string | Describes a class of error the operation ended with. [1] | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`feature_flag.result.value`](/docs/registry/attributes/feature-flag.md) | any | The evaluated value of the feature flag. [3] | `#ff0000`; `true`; `3` | `Conditionally Required` [4] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`feature_flag.result.variant`](/docs/registry/attributes/feature-flag.md) | string | A semantic identifier for an evaluated flag value. [5] | `red`; `true`; `on` | `Conditionally Required` [6] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`error.message`](/docs/registry/attributes/error.md) | string | A message providing more detail about an error in human-readable form. [7] | `Unexpected input type: string`; `The user has exceeded their storage quota` | `Recommended` [8] | ![Development](https://img.shields.io/badge/-development-blue) | -| [`feature_flag.context.id`](/docs/registry/attributes/feature-flag.md) | string | The unique identifier for the flag evaluation context. For example, the targeting key. | `5157782b-2203-4c80-a857-dbbd5e7761db` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`feature_flag.provider.name`](/docs/registry/attributes/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`feature_flag.result.reason`](/docs/registry/attributes/feature-flag.md) | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`feature_flag.set.id`](/docs/registry/attributes/feature-flag.md) | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) to which the feature flag belongs. | `proj-1`; `ab98sgs`; `service1/dev` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`feature_flag.version`](/docs/registry/attributes/feature-flag.md) | string | The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. | `1`; `01ABCDEF` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | - -**[1] `error.type`:** If one of these values applies, then it MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -|---|---|---| -| `flag_not_found` | The flag could not be found. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `invalid_context` | The evaluation context does not meet provider requirements. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `parse_error` | An error was encountered parsing data, such as a flag configuration. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `provider_fatal` | The provider has entered an irrecoverable error state. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `provider_not_ready` | The value was resolved before the provider was initialized. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `targeting_key_missing` | The provider requires a targeting key and one was not provided in the evaluation context. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `type_mismatch` | The type of the flag value does not match the expected type. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `general` | The error was for a reason not enumerated above. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | - -**[2] `error.type`:** If and only if an error occurred during flag evaluation. - -**[3] `feature_flag.result.value`:** With some feature flag providers, feature flag results can be quite large or contain private or sensitive details. -Because of this, `feature_flag.result.variant` is often the preferred attribute if it is available. - -It may be desirable to redact or otherwise limit the size and scope of `feature_flag.result.value` if possible. -Because the evaluated flag value is unstructured and may be any type, it is left to the instrumentation author to determine how best to achieve this. - -**[4] `feature_flag.result.value`:** If and only if feature flag provider does not supply variant or equivalent concept. Otherwise, `feature_flag.result.value` should be treated as opt-in. - -**[5] `feature_flag.result.variant`:** A semantic identifier, commonly referred to as a variant, provides a means -for referring to a value without including the value itself. This can -provide additional context for understanding the meaning behind a value. -For example, the variant `red` maybe be used for the value `#c05543`. - -**[6] `feature_flag.result.variant`:** If feature flag provider supplies a variant or equivalent concept. - -**[7] `error.message`:** Should not simply duplicate the value of `error.type`, but should provide more context. For example, if `error.type` is `invalid_context` the `error.message` may enumerate which context keys are missing or invalid. - -**[8] `error.message`:** If and only if an error occurred during flag evaluation and `error.type` does not sufficiently describe the error. - ---- - -`error.type` 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 | -|---|---|---| -| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - ---- - -`feature_flag.result.reason` 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 | -|---|---|---| -| `cached` | The resolved value was retrieved from cache. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `default` | The resolved value fell back to a pre-configured value (no dynamic evaluation occurred or dynamic evaluation yielded no result). | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `disabled` | The resolved value was the result of the flag being disabled in the management system. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `error` | The resolved value was the result of an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `split` | The resolved value was the result of pseudorandom assignment. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `stale` | The resolved value is non-authoritative or possibly out of date | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `static` | The resolved value is static (no dynamic evaluation). | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `targeting_match` | The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `unknown` | The reason for the resolved value could not be determined. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +## Events - - - - +Is now described in the namespace registry. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md index bec087be34..8724fa17e9 100644 --- a/docs/gen-ai/gen-ai-events.md +++ b/docs/gen-ai/gen-ai-events.md @@ -8,11 +8,7 @@ linkTitle: Events -- [Event: `gen_ai.system.message`](#event-gen_aisystemmessage) -- [Event: `gen_ai.user.message`](#event-gen_aiusermessage) -- [Event: `gen_ai.assistant.message`](#event-gen_aiassistantmessage) -- [Event: `gen_ai.tool.message`](#event-gen_aitoolmessage) -- [Event: `gen_ai.choice`](#event-gen_aichoice) +- [Events](#events) - [Custom events](#custom-events) - [Examples](#examples) - [Chat completion](#chat-completion) @@ -65,459 +61,9 @@ Telemetry consumers SHOULD expect to receive unknown body fields. Instrumentations SHOULD NOT capture undocumented body fields and MUST follow the documented defaults for known fields. Instrumentations MAY offer configuration options allowing to disable events or allowing to capture all fields. -## Event: `gen_ai.system.message` +## Events - - - - - - - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -The event name MUST be `gen_ai.system.message`. - -This event describes the system instructions passed to the GenAI model. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI provider as identified by the client or server instrumentation. [1] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1] `gen_ai.provider.name`:** The attribute SHOULD be set based on the instrumentation's best -knowledge and may differ from the actual model provider. - -Multiple providers, including Azure OpenAI, Gemini, and AI hosting platforms -are accessible using the OpenAI REST API and corresponding client libraries, -but may proxy or host models from different providers. - -The `gen_ai.request.model`, `gen_ai.response.model`, and `server.address` -attributes may help identify the actual system in use. - -The `gen_ai.provider.name` attribute acts as a discriminator that -identifies the GenAI telemetry format flavor specific to that provider -within GenAI semantic conventions. -It SHOULD be set consistently with provider-specific attributes and signals. -For example, GenAI spans, metrics, and events related to AWS Bedrock -should have the `gen_ai.provider.name` set to `aws.bedrock` and include -applicable `aws.bedrock.*` attributes and are not expected to include -`openai.*` attributes. - ---- - -`gen_ai.provider.name` 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 | -|---|---|---| -| `anthropic` | [Anthropic](https://www.anthropic.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `aws.bedrock` | [AWS Bedrock](https://aws.amazon.com/bedrock) | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.openai` | [Azure OpenAI](https://azure.microsoft.com/products/ai-services/openai-service/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `cohere` | [Cohere](https://cohere.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `deepseek` | [DeepSeek](https://www.deepseek.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gemini` | [Gemini](https://cloud.google.com/products/gemini) [2] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gen_ai` | Any Google generative AI endpoint [3] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [4] | ![Development](https://img.shields.io/badge/-development-blue) | -| `groq` | [Groq](https://groq.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) | ![Development](https://img.shields.io/badge/-development-blue) | -| `mistral_ai` | [Mistral AI](https://mistral.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `openai` | [OpenAI](https://openai.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `perplexity` | [Perplexity](https://www.perplexity.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `x_ai` | [xAI](https://x.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | - -**[2]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. - -**[3]:** May be used when specific backend is unknown. - -**[4]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. - -**Body fields:** - -:warning: Body fields will be moved to complex attributes once the -semantic convention tooling supports complex attributes -(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). - -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| `content` | undefined | The contents of the system message. | `You're a helpful bot` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -| `role` | string | The actual role of the message author as passed in the message. | `system`; `instruction` | `Conditionally Required` if available and not equal to `system`. | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - - -## Event: `gen_ai.user.message` - - - - - - - - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -The event name MUST be `gen_ai.user.message`. - -This event describes the user message passed to the GenAI model. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI provider as identified by the client or server instrumentation. [1] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1] `gen_ai.provider.name`:** The attribute SHOULD be set based on the instrumentation's best -knowledge and may differ from the actual model provider. - -Multiple providers, including Azure OpenAI, Gemini, and AI hosting platforms -are accessible using the OpenAI REST API and corresponding client libraries, -but may proxy or host models from different providers. - -The `gen_ai.request.model`, `gen_ai.response.model`, and `server.address` -attributes may help identify the actual system in use. - -The `gen_ai.provider.name` attribute acts as a discriminator that -identifies the GenAI telemetry format flavor specific to that provider -within GenAI semantic conventions. -It SHOULD be set consistently with provider-specific attributes and signals. -For example, GenAI spans, metrics, and events related to AWS Bedrock -should have the `gen_ai.provider.name` set to `aws.bedrock` and include -applicable `aws.bedrock.*` attributes and are not expected to include -`openai.*` attributes. - ---- - -`gen_ai.provider.name` 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 | -|---|---|---| -| `anthropic` | [Anthropic](https://www.anthropic.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `aws.bedrock` | [AWS Bedrock](https://aws.amazon.com/bedrock) | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.openai` | [Azure OpenAI](https://azure.microsoft.com/products/ai-services/openai-service/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `cohere` | [Cohere](https://cohere.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `deepseek` | [DeepSeek](https://www.deepseek.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gemini` | [Gemini](https://cloud.google.com/products/gemini) [2] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gen_ai` | Any Google generative AI endpoint [3] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [4] | ![Development](https://img.shields.io/badge/-development-blue) | -| `groq` | [Groq](https://groq.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) | ![Development](https://img.shields.io/badge/-development-blue) | -| `mistral_ai` | [Mistral AI](https://mistral.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `openai` | [OpenAI](https://openai.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `perplexity` | [Perplexity](https://www.perplexity.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `x_ai` | [xAI](https://x.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | - -**[2]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. - -**[3]:** May be used when specific backend is unknown. - -**[4]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. - -**Body fields:** - -:warning: Body fields will be moved to complex attributes once the -semantic convention tooling supports complex attributes -(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). - -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| `content` | undefined | The contents of the user message. | `What's the weather in Paris?` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -| `role` | string | The actual role of the message author as passed in the message. | `user`; `customer` | `Conditionally Required` if available and not equal to `user`. | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - - -## Event: `gen_ai.assistant.message` - - - - - - - - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -The event name MUST be `gen_ai.assistant.message`. - -This event describes the assistant message passed to GenAI system. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI provider as identified by the client or server instrumentation. [1] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1] `gen_ai.provider.name`:** The attribute SHOULD be set based on the instrumentation's best -knowledge and may differ from the actual model provider. - -Multiple providers, including Azure OpenAI, Gemini, and AI hosting platforms -are accessible using the OpenAI REST API and corresponding client libraries, -but may proxy or host models from different providers. - -The `gen_ai.request.model`, `gen_ai.response.model`, and `server.address` -attributes may help identify the actual system in use. - -The `gen_ai.provider.name` attribute acts as a discriminator that -identifies the GenAI telemetry format flavor specific to that provider -within GenAI semantic conventions. -It SHOULD be set consistently with provider-specific attributes and signals. -For example, GenAI spans, metrics, and events related to AWS Bedrock -should have the `gen_ai.provider.name` set to `aws.bedrock` and include -applicable `aws.bedrock.*` attributes and are not expected to include -`openai.*` attributes. - ---- - -`gen_ai.provider.name` 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 | -|---|---|---| -| `anthropic` | [Anthropic](https://www.anthropic.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `aws.bedrock` | [AWS Bedrock](https://aws.amazon.com/bedrock) | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.openai` | [Azure OpenAI](https://azure.microsoft.com/products/ai-services/openai-service/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `cohere` | [Cohere](https://cohere.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `deepseek` | [DeepSeek](https://www.deepseek.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gemini` | [Gemini](https://cloud.google.com/products/gemini) [2] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gen_ai` | Any Google generative AI endpoint [3] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [4] | ![Development](https://img.shields.io/badge/-development-blue) | -| `groq` | [Groq](https://groq.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) | ![Development](https://img.shields.io/badge/-development-blue) | -| `mistral_ai` | [Mistral AI](https://mistral.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `openai` | [OpenAI](https://openai.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `perplexity` | [Perplexity](https://www.perplexity.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `x_ai` | [xAI](https://x.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | - -**[2]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. - -**[3]:** May be used when specific backend is unknown. - -**[4]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. - -**Body fields:** - -:warning: Body fields will be moved to complex attributes once the -semantic convention tooling supports complex attributes -(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). - -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| `content` | undefined | The contents of the tool message. | `The weather in Paris is rainy and overcast, with temperatures around 57°F` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -| `role` | string | The actual role of the message author as passed in the message. | `assistant`; `bot` | `Conditionally Required` if available and not equal to `assistant`. | ![Development](https://img.shields.io/badge/-development-blue) | -| `tool_calls`: | map[] | The tool calls generated by the model, such as function calls. | | `Conditionally Required` if available | ![Development](https://img.shields.io/badge/-development-blue) | -|   `function`: | map | The function call. | | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -|     `arguments` | undefined | The arguments of the function as provided in the LLM response. [1] | `{\"location\": \"Paris\"}` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -|     `name` | string | The name of the function. | `get_weather` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -|   `id` | string | The id of the tool call. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -|   `type` | enum | The type of the tool. | `function` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1]:** Models usually return arguments as a JSON string. In this case, it's RECOMMENDED to provide arguments as is without attempting to deserialize them. -Semantic conventions for individual systems MAY specify a different type for arguments field. - -`type` 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 | -|---|---|---| -| `function` | Function | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - - -## Event: `gen_ai.tool.message` - - - - - - - - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -The event name MUST be `gen_ai.tool.message`. - -This event describes the response from a tool or function call passed to the GenAI model. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI provider as identified by the client or server instrumentation. [1] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1] `gen_ai.provider.name`:** The attribute SHOULD be set based on the instrumentation's best -knowledge and may differ from the actual model provider. - -Multiple providers, including Azure OpenAI, Gemini, and AI hosting platforms -are accessible using the OpenAI REST API and corresponding client libraries, -but may proxy or host models from different providers. - -The `gen_ai.request.model`, `gen_ai.response.model`, and `server.address` -attributes may help identify the actual system in use. - -The `gen_ai.provider.name` attribute acts as a discriminator that -identifies the GenAI telemetry format flavor specific to that provider -within GenAI semantic conventions. -It SHOULD be set consistently with provider-specific attributes and signals. -For example, GenAI spans, metrics, and events related to AWS Bedrock -should have the `gen_ai.provider.name` set to `aws.bedrock` and include -applicable `aws.bedrock.*` attributes and are not expected to include -`openai.*` attributes. - ---- - -`gen_ai.provider.name` 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 | -|---|---|---| -| `anthropic` | [Anthropic](https://www.anthropic.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `aws.bedrock` | [AWS Bedrock](https://aws.amazon.com/bedrock) | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.openai` | [Azure OpenAI](https://azure.microsoft.com/products/ai-services/openai-service/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `cohere` | [Cohere](https://cohere.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `deepseek` | [DeepSeek](https://www.deepseek.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gemini` | [Gemini](https://cloud.google.com/products/gemini) [2] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gen_ai` | Any Google generative AI endpoint [3] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [4] | ![Development](https://img.shields.io/badge/-development-blue) | -| `groq` | [Groq](https://groq.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) | ![Development](https://img.shields.io/badge/-development-blue) | -| `mistral_ai` | [Mistral AI](https://mistral.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `openai` | [OpenAI](https://openai.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `perplexity` | [Perplexity](https://www.perplexity.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `x_ai` | [xAI](https://x.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | - -**[2]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. - -**[3]:** May be used when specific backend is unknown. - -**[4]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. - -**Body fields:** - -:warning: Body fields will be moved to complex attributes once the -semantic convention tooling supports complex attributes -(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). - -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| `content` | undefined | The contents of the tool message. | `rainy, 57°F` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -| `id` | string | Tool call id that this message is responding to. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -| `role` | string | The actual role of the message author as passed in the message. | `tool`; `function` | `Conditionally Required` if available and not equal to `tool`. | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - - -## Event: `gen_ai.choice` - - - - - - - - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -The event name MUST be `gen_ai.choice`. - -This event describes the Gen AI response message. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) | string | The Generative AI provider as identified by the client or server instrumentation. [1] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1] `gen_ai.provider.name`:** The attribute SHOULD be set based on the instrumentation's best -knowledge and may differ from the actual model provider. - -Multiple providers, including Azure OpenAI, Gemini, and AI hosting platforms -are accessible using the OpenAI REST API and corresponding client libraries, -but may proxy or host models from different providers. - -The `gen_ai.request.model`, `gen_ai.response.model`, and `server.address` -attributes may help identify the actual system in use. - -The `gen_ai.provider.name` attribute acts as a discriminator that -identifies the GenAI telemetry format flavor specific to that provider -within GenAI semantic conventions. -It SHOULD be set consistently with provider-specific attributes and signals. -For example, GenAI spans, metrics, and events related to AWS Bedrock -should have the `gen_ai.provider.name` set to `aws.bedrock` and include -applicable `aws.bedrock.*` attributes and are not expected to include -`openai.*` attributes. - ---- - -`gen_ai.provider.name` 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 | -|---|---|---| -| `anthropic` | [Anthropic](https://www.anthropic.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `aws.bedrock` | [AWS Bedrock](https://aws.amazon.com/bedrock) | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.inference` | Azure AI Inference | ![Development](https://img.shields.io/badge/-development-blue) | -| `azure.ai.openai` | [Azure OpenAI](https://azure.microsoft.com/products/ai-services/openai-service/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `cohere` | [Cohere](https://cohere.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `deepseek` | [DeepSeek](https://www.deepseek.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gemini` | [Gemini](https://cloud.google.com/products/gemini) [2] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gen_ai` | Any Google generative AI endpoint [3] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [4] | ![Development](https://img.shields.io/badge/-development-blue) | -| `groq` | [Groq](https://groq.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) | ![Development](https://img.shields.io/badge/-development-blue) | -| `mistral_ai` | [Mistral AI](https://mistral.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `openai` | [OpenAI](https://openai.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `perplexity` | [Perplexity](https://www.perplexity.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `x_ai` | [xAI](https://x.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | - -**[2]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. - -**[3]:** May be used when specific backend is unknown. - -**[4]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. - -**Body fields:** - -:warning: Body fields will be moved to complex attributes once the -semantic convention tooling supports complex attributes -(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). - -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| `finish_reason` | enum | The reason the model stopped generating tokens. | `stop`; `tool_calls`; `content_filter` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -| `index` | int | The index of the choice in the list of choices. | `0`; `1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -| `message`: | map | GenAI response message. | | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -|   `content` | undefined | The contents of the assistant message. | `The weather in Paris is rainy and overcast, with temperatures around 57°F` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -|   `role` | string | The actual role of the message author as passed in the message. | `assistant`; `bot` | `Conditionally Required` if available and not equal to `assistant`. | ![Development](https://img.shields.io/badge/-development-blue) | -| `tool_calls`: | map[] | The tool calls generated by the model, such as function calls. | | `Conditionally Required` if available | ![Development](https://img.shields.io/badge/-development-blue) | -|   `function`: | map | The function that the model called. | | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -|     `arguments` | undefined | The arguments of the function as provided in the LLM response. [1] | `{\"location\": \"Paris\"}` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -|     `name` | string | The name of the function. | `get_weather` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -|   `id` | string | The id of the tool call. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -|   `type` | enum | The type of the tool. | `function` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1]:** Models usually return arguments as a JSON string. In this case, it's RECOMMENDED to provide arguments as is without attempting to deserialize them. -Semantic conventions for individual systems MAY specify a different type for arguments field. - -`finish_reason` 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 | -|---|---|---| -| `content_filter` | Content Filter | ![Development](https://img.shields.io/badge/-development-blue) | -| `error` | Error | ![Development](https://img.shields.io/badge/-development-blue) | -| `length` | Length | ![Development](https://img.shields.io/badge/-development-blue) | -| `stop` | Stop | ![Development](https://img.shields.io/badge/-development-blue) | -| `tool_calls` | Tool Calls | ![Development](https://img.shields.io/badge/-development-blue) | - -`type` 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 | -|---|---|---| -| `function` | Function | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - +Is now described in the namespace registry. ## Custom events diff --git a/docs/general/recording-errors.md b/docs/general/recording-errors.md index 84f524247d..c534af64f2 100644 --- a/docs/general/recording-errors.md +++ b/docs/general/recording-errors.md @@ -84,7 +84,7 @@ include it if the operation succeeded. ## Recording exceptions When an instrumented operation fails with an exception, instrumentation SHOULD record -this exception as a [span event](/docs/exceptions/exceptions-spans.md) or a [log record](/docs/exceptions/exceptions-logs.md). +this exception as an [event](/docs/registry/namespaces/exception/event-exception.md) or a [log record](/docs/exceptions/exceptions-logs.md). It's RECOMMENDED to use the `Span.recordException` API or logging library API that takes exception instance instead of providing individual attributes. This enables the OpenTelemetry SDK to diff --git a/docs/general/session.md b/docs/general/session.md index 24cd15237e..5c92ef2393 100644 --- a/docs/general/session.md +++ b/docs/general/session.md @@ -17,83 +17,14 @@ the Logs, Events, and Spans generated during the Session's lifecycle. When a session reaches end of life, typically due to user inactivity or session timeout, a new session identifier will be assigned. The previous session identifier may be provided by the instrumentation so that telemetry -backends can link the two sessions (see [Session Start Event](#event-sessionstart) below). +backends can link the two sessions (see Session Start Event). ## Attributes - - - - - - +Is now described in the attributes registry. -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`session.id`](/docs/registry/attributes/session.md) | string | A unique id to identify a session. | `00112233-4455-6677-8899-aabbccddeeff` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`session.previous_id`](/docs/registry/attributes/session.md) | string | The previous `session.id` for this user, when known. | `00112233-4455-6677-8899-aabbccddeeff` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +## Events - - - - - -## Session Events - -### Event: `session.start` - - - - - - - - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -The event name MUST be `session.start`. - -Indicates that a new session has been started, optionally linking to the prior session. - -For instrumentation that tracks user behavior during user sessions, a `session.start` event MUST be emitted every time a session is created. When a new session is created as a continuation of a prior session, the `session.previous_id` SHOULD be included in the event. The values of `session.id` and `session.previous_id` MUST be different. -When the `session.start` event contains both `session.id` and `session.previous_id` fields, the event indicates that the previous session has ended. If the session ID in `session.previous_id` has not yet ended via explicit `session.end` event, then the consumer SHOULD treat this continuation event as semantically equivalent to `session.end(session.previous_id)` and `session.start(session.id)`. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`session.id`](/docs/registry/attributes/session.md) | string | The ID of the new session being started. | `00112233-4455-6677-8899-aabbccddeeff` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`session.previous_id`](/docs/registry/attributes/session.md) | string | The previous `session.id` for this user, when known. | `00112233-4455-6677-8899-aabbccddeeff` | `Conditionally Required` [1] | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1] `session.previous_id`:** If the new session is being created as a continuation of a previous session, the `session.previous_id` SHOULD be included in the event. The `session.id` and `session.previous_id` attributes MUST have different values. - - - - - - -### Event: `session.end` - - - - - - - - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -The event name MUST be `session.end`. - -Indicates that a session has ended. - -For instrumentation that tracks user behavior during user sessions, a `session.end` event SHOULD be emitted every time a session ends. When a session ends and continues as a new session, this event SHOULD be emitted prior to the `session.start` event. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`session.id`](/docs/registry/attributes/session.md) | string | The ID of the session being ended. | `00112233-4455-6677-8899-aabbccddeeff` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - +Is now described in the namespace registry. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/general/trace.md b/docs/general/trace.md index 96eaef4f83..5139eb1a88 100644 --- a/docs/general/trace.md +++ b/docs/general/trace.md @@ -25,7 +25,8 @@ The following semantic conventions for spans are defined: * [CloudEvents](/docs/cloudevents/README.md): Semantic Conventions for the CloudEvents spans. * [Cloud Providers](/docs/cloud-providers/README.md): Semantic Conventions for cloud providers spans. * [Database](/docs/database/database-spans.md): For SQL and NoSQL client call spans. -* [Exceptions](/docs/exceptions/exceptions-spans.md): For recording exceptions associated with a span. +* [Exceptions](/docs/registry/namespaces/exception/event-exception.md) +[Exceptions]: For recording exceptions associated with a span. * [FaaS](/docs/faas/faas-spans.md): For [Function as a Service](https://wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans. * [HTTP](/docs/http/http-spans.md): For HTTP client and server spans. * [Messaging](/docs/messaging/messaging-spans.md): For messaging systems (queues, publish/subscribe, etc.) spans. diff --git a/docs/mobile/README.md b/docs/mobile/README.md index 84bfce21c0..b3fda267b3 100644 --- a/docs/mobile/README.md +++ b/docs/mobile/README.md @@ -1,15 +1,9 @@ -# Semantic conventions for mobile platform +# Mobile -**Status**: [Development][DocumentStatus] - -This document defines semantic conventions for mobile platform spans, metrics and logs. - -Semantic conventions for the mobile platform are defined for the following signals: - -* [Mobile Events](events.md) : Semantic Conventions for mobile events in *logs*. - -[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status +This page has moved to +[Mobile](/docs/registry/namespaces/). diff --git a/docs/mobile/events.md b/docs/mobile/events.md deleted file mode 100644 index ff89ffb90e..0000000000 --- a/docs/mobile/events.md +++ /dev/null @@ -1,80 +0,0 @@ - - -# Semantic conventions for mobile events - -**Status**: [Development][DocumentStatus] - -This document defines semantic conventions for instrumentations that emit -events on mobile platforms. All mobile events MUST use a namespace of -`device` in the EventName LogRecord property. - - - -- [Lifecycle instrumentation](#lifecycle-instrumentation) - - [Device app lifecycle event](#device-app-lifecycle-event) - - - -## Lifecycle instrumentation - -This section defines how to apply semantic conventions when instrumenting -application lifecycle. - -### Device app lifecycle event - - - - - - - - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -The event name MUST be `device.app.lifecycle`. - -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.app.state` and `ios.app.state` fields are mutually exclusive and MUST NOT be used together, each field MUST be used with its corresponding `os.name` value. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`android.app.state`](/docs/registry/attributes/android.md) | string | This attribute represents the state of the application. [1] | `created` | `Conditionally Required` if and only if `os.name` is `android` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`ios.app.state`](/docs/registry/attributes/ios.md) | string | This attribute represents the state of the application. [2] | `active`; `inactive`; `background` | `Conditionally Required` if and only if `os.name` is `ios` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1] `android.app.state`:** 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] `ios.app.state`:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate), and from which the `OS terminology` column values are derived. - ---- - -`android.app.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 | -|---|---|---| -| `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. | ![Development](https://img.shields.io/badge/-development-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. | ![Development](https://img.shields.io/badge/-development-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. | ![Development](https://img.shields.io/badge/-development-blue) | - ---- - -`ios.app.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`. | ![Development](https://img.shields.io/badge/-development-blue) | -| `background` | The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`. | ![Development](https://img.shields.io/badge/-development-blue) | -| `foreground` | The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`. | ![Development](https://img.shields.io/badge/-development-blue) | -| `inactive` | The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. | ![Development](https://img.shields.io/badge/-development-blue) | -| `terminate` | The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - - -[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/registry/attributes/code.md b/docs/registry/attributes/code.md index 9c8008ce75..8eb867d569 100644 --- a/docs/registry/attributes/code.md +++ b/docs/registry/attributes/code.md @@ -16,7 +16,7 @@ These attributes provide context about source code | `code.file.path` | string | The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). This attribute MUST NOT be used on the Profile signal since the data is already captured in 'message Function'. This constraint is imposed to prevent redundancy and maintain data integrity. | `/usr/local/MyApplication/content_root/app/index.php` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `code.function.name` | string | The method or function fully-qualified name without arguments. The value should fit the natural representation of the language runtime, which is also likely the same used within `code.stacktrace` attribute value. This attribute MUST NOT be used on the Profile signal since the data is already captured in 'message Function'. This constraint is imposed to prevent redundancy and maintain data integrity. [1] | `com.example.MyHttpService.serveRequest`; `GuzzleHttp\Client::transfer`; `fopen` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `code.line.number` | int | The line number in `code.file.path` best representing the operation. It SHOULD point within the code unit named in `code.function.name`. This attribute MUST NOT be used on the Profile signal since the data is already captured in 'message Line'. This constraint is imposed to prevent redundancy and maintain data integrity. | `42` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `code.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is identical to [`exception.stacktrace`](/docs/exceptions/exceptions-spans.md#stacktrace-representation). This attribute MUST NOT be used on the Profile signal since the data is already captured in 'message Location'. This constraint is imposed to prevent redundancy and maintain data integrity. | `at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `code.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. This attribute MUST NOT be used on the Profile signal since the data is already captured in 'message Location'. This constraint is imposed to prevent redundancy and maintain data integrity. [2] | `at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `code.function.name`:** Values and format depends on each language runtime, thus it is impossible to provide an exhaustive list of examples. The values are usually the same (or prefixes of) the ones found in native stack trace representation stored in @@ -34,6 +34,38 @@ Examples: * Rust: `playground::my_module::my_cool_func` * C function: `fopen` +**[2] `code.stacktrace`:** The table below, adapted from [Google Cloud][gcp-error-reporting], includes +possible representations of stacktraces in various languages. The table is not +meant to be a recommendation for any particular language, although SIGs are free +to adopt them if they see fit. + +| Language | Format | +| ---------- | ------------------------------------------------------------------- | +| C# | the return value of [Exception.ToString()][csharp-stacktrace] | +| Elixir | the return value of [Exception.format/3][elixir-stacktrace] | +| Erlang | the return value of [`erl_error:format`][erlang-stacktrace] | +| Go | the return value of [runtime.Stack][go-stacktrace] | +| Java | the contents of [Throwable.printStackTrace()][java-stacktrace] | +| Javascript | the return value of [error.stack][js-stacktrace] as returned by V8 | +| Python | the return value of [traceback.format_exc()][python-stacktrace] | +| Ruby | the return value of [Exception.full_message][ruby-full-message] | + +Backends can use the language specified methodology for generating a stacktrace +combined with platform information from the +[telemetry sdk resource][telemetry-sdk-resource] in order to extract more fine +grained information from a stacktrace, if necessary. + +[gcp-error-reporting]: https://cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report +[java-stacktrace]: https://docs.oracle.com/javase/7/docs/api/java/lang/Throwable.html#printStackTrace%28%29 +[python-stacktrace]: https://docs.python.org/3/library/traceback.html#traceback.format_exc +[js-stacktrace]: https://v8.dev/docs/stack-trace-api +[ruby-full-message]: https://docs.ruby-lang.org/en/3.4/Exception.html#method-i-full_message +[csharp-stacktrace]: https://docs.microsoft.com/dotnet/api/system.exception.tostring +[go-stacktrace]: https://pkg.go.dev/runtime/debug#Stack +[telemetry-sdk-resource]: ../resource/README.md#telemetry-sdk +[erlang-stacktrace]: https://www.erlang.org/doc/apps/stdlib/erl_error.html#format_exception/3 +[elixir-stacktrace]: https://hexdocs.pm/elixir/1.14.3/Exception.html#format/3 + ## Deprecated Code Attributes These deprecated attributes provide context about source code diff --git a/docs/registry/attributes/exception.md b/docs/registry/attributes/exception.md index 739113022f..7d90d0e442 100644 --- a/docs/registry/attributes/exception.md +++ b/docs/registry/attributes/exception.md @@ -13,9 +13,41 @@ This document defines the shared attributes used to report a single exception as | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| | `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. [1] | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +**[1] `exception.stacktrace`:** The table below, adapted from [Google Cloud][gcp-error-reporting], includes +possible representations of stacktraces in various languages. The table is not +meant to be a recommendation for any particular language, although SIGs are free +to adopt them if they see fit. + +| Language | Format | +| ---------- | ------------------------------------------------------------------- | +| C# | the return value of [Exception.ToString()][csharp-stacktrace] | +| Elixir | the return value of [Exception.format/3][elixir-stacktrace] | +| Erlang | the return value of [`erl_error:format`][erlang-stacktrace] | +| Go | the return value of [runtime.Stack][go-stacktrace] | +| Java | the contents of [Throwable.printStackTrace()][java-stacktrace] | +| Javascript | the return value of [error.stack][js-stacktrace] as returned by V8 | +| Python | the return value of [traceback.format_exc()][python-stacktrace] | +| Ruby | the return value of [Exception.full_message][ruby-full-message] | + +Backends can use the language specified methodology for generating a stacktrace +combined with platform information from the +[telemetry sdk resource][telemetry-sdk-resource] in order to extract more fine +grained information from a stacktrace, if necessary. + +[gcp-error-reporting]: https://cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report +[java-stacktrace]: https://docs.oracle.com/javase/7/docs/api/java/lang/Throwable.html#printStackTrace%28%29 +[python-stacktrace]: https://docs.python.org/3/library/traceback.html#traceback.format_exc +[js-stacktrace]: https://v8.dev/docs/stack-trace-api +[ruby-full-message]: https://docs.ruby-lang.org/en/3.4/Exception.html#method-i-full_message +[csharp-stacktrace]: https://docs.microsoft.com/dotnet/api/system.exception.tostring +[go-stacktrace]: https://pkg.go.dev/runtime/debug#Stack +[telemetry-sdk-resource]: ../resource/README.md#telemetry-sdk +[erlang-stacktrace]: https://www.erlang.org/doc/apps/stdlib/erl_error.html#format_exception/3 +[elixir-stacktrace]: https://hexdocs.pm/elixir/1.14.3/Exception.html#format/3 + ## Deprecated Exception Attributes Deprecated exception attributes. diff --git a/docs/registry/namespaces/exception/event-exception.md b/docs/registry/namespaces/exception/event-exception.md index 760a954430..485d32bad1 100644 --- a/docs/registry/namespaces/exception/event-exception.md +++ b/docs/registry/namespaces/exception/event-exception.md @@ -22,10 +22,42 @@ | [`exception.message`](/docs/registry/attributes/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) | | [`exception.type`](/docs/registry/attributes/exception.md) | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`exception.escaped`](/docs/registry/attributes/exception.md) | boolean | Indicates that the exception is escaping the scope of the span. | | `Recommended` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
It's no longer recommended to record exceptions that are handled and do not escape the scope of a span. | -| [`exception.stacktrace`](/docs/registry/attributes/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`exception.stacktrace`](/docs/registry/attributes/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. [3] | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise. **[2] `exception.type`:** Required if `exception.message` is not set, recommended otherwise. +**[3] `exception.stacktrace`:** The table below, adapted from [Google Cloud][gcp-error-reporting], includes +possible representations of stacktraces in various languages. The table is not +meant to be a recommendation for any particular language, although SIGs are free +to adopt them if they see fit. + +| Language | Format | +| ---------- | ------------------------------------------------------------------- | +| C# | the return value of [Exception.ToString()][csharp-stacktrace] | +| Elixir | the return value of [Exception.format/3][elixir-stacktrace] | +| Erlang | the return value of [`erl_error:format`][erlang-stacktrace] | +| Go | the return value of [runtime.Stack][go-stacktrace] | +| Java | the contents of [Throwable.printStackTrace()][java-stacktrace] | +| Javascript | the return value of [error.stack][js-stacktrace] as returned by V8 | +| Python | the return value of [traceback.format_exc()][python-stacktrace] | +| Ruby | the return value of [Exception.full_message][ruby-full-message] | + +Backends can use the language specified methodology for generating a stacktrace +combined with platform information from the +[telemetry sdk resource][telemetry-sdk-resource] in order to extract more fine +grained information from a stacktrace, if necessary. + +[gcp-error-reporting]: https://cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report +[java-stacktrace]: https://docs.oracle.com/javase/7/docs/api/java/lang/Throwable.html#printStackTrace%28%29 +[python-stacktrace]: https://docs.python.org/3/library/traceback.html#traceback.format_exc +[js-stacktrace]: https://v8.dev/docs/stack-trace-api +[ruby-full-message]: https://docs.ruby-lang.org/en/3.4/Exception.html#method-i-full_message +[csharp-stacktrace]: https://docs.microsoft.com/dotnet/api/system.exception.tostring +[go-stacktrace]: https://pkg.go.dev/runtime/debug#Stack +[telemetry-sdk-resource]: ../resource/README.md#telemetry-sdk +[erlang-stacktrace]: https://www.erlang.org/doc/apps/stdlib/erl_error.html#format_exception/3 +[elixir-stacktrace]: https://hexdocs.pm/elixir/1.14.3/Exception.html#format/3 + diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 83c29363ac..456b9e0ae0 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -16,8 +16,6 @@ This document defines how to describe remote procedure calls - [Service name](#service-name) - [RPC client span](#rpc-client-span) - [RPC server span](#rpc-server-span) - - [Events](#events) - - [Message event](#message-event) - [Distinction from HTTP spans](#distinction-from-http-spans) - [Semantic conventions for specific RPC technologies](#semantic-conventions-for-specific-rpc-technologies) @@ -101,7 +99,7 @@ This span represents an outgoing Remote Procedure Call (RPC). Remote procedure calls can only be represented with these semantic conventions when the names of the called service and method are known and available. -**Span name:** refer to the [Span Name](#span-name) section. +**Span name:** refer to the [Span Name](/docs/rpc/rpc-spans.md#span-name) section. **Span kind** MUST be `CLIENT`. @@ -271,48 +269,6 @@ different processes could be listening on TCP port 12345 and UDP port 12345. -### Events - -#### Message event - - - - - - - - -**Status:** ![Development](https://img.shields.io/badge/-development-blue) - -The event name MUST be `rpc.message`. - -Describes a message sent or received within the context of an RPC call. - -In the lifetime of an RPC stream, an event for each message sent/received on client and server spans SHOULD be created. In case of unary calls only one sent and one received message will be recorded for both client and server spans. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`rpc.message.compressed_size`](/docs/registry/attributes/rpc.md) | int | Compressed size of the message in bytes. | | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`rpc.message.id`](/docs/registry/attributes/rpc.md) | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`rpc.message.type`](/docs/registry/attributes/rpc.md) | string | Whether this is a received or sent message. | `SENT`; `RECEIVED` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`rpc.message.uncompressed_size`](/docs/registry/attributes/rpc.md) | int | Uncompressed size of the message in bytes. | | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | - -**[1] `rpc.message.id`:** This way we guarantee that the values will be consistent between different implementations. - ---- - -`rpc.message.type` 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 | -|---|---|---| -| `RECEIVED` | received | ![Development](https://img.shields.io/badge/-development-blue) | -| `SENT` | sent | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - - ### Distinction from HTTP spans HTTP calls can generally be represented using just [HTTP spans](/docs/http/http-spans.md). diff --git a/model/code/registry.yaml b/model/code/registry.yaml index ca1ffd9e1f..2b7074c807 100644 --- a/model/code/registry.yaml +++ b/model/code/registry.yaml @@ -58,8 +58,39 @@ groups: stability: stable brief: > A stacktrace as a string in the natural representation for the language runtime. - The representation is identical to [`exception.stacktrace`](/docs/exceptions/exceptions-spans.md#stacktrace-representation). This attribute MUST NOT be used on the Profile signal since the data is already captured in 'message Location'. This constraint is imposed to prevent redundancy and maintain data integrity. + note: | + The table below, adapted from [Google Cloud][gcp-error-reporting], includes + possible representations of stacktraces in various languages. The table is not + meant to be a recommendation for any particular language, although SIGs are free + to adopt them if they see fit. + + | Language | Format | + | ---------- | ------------------------------------------------------------------- | + | C# | the return value of [Exception.ToString()][csharp-stacktrace] | + | Elixir | the return value of [Exception.format/3][elixir-stacktrace] | + | Erlang | the return value of [`erl_error:format`][erlang-stacktrace] | + | Go | the return value of [runtime.Stack][go-stacktrace] | + | Java | the contents of [Throwable.printStackTrace()][java-stacktrace] | + | Javascript | the return value of [error.stack][js-stacktrace] as returned by V8 | + | Python | the return value of [traceback.format_exc()][python-stacktrace] | + | Ruby | the return value of [Exception.full_message][ruby-full-message] | + + Backends can use the language specified methodology for generating a stacktrace + combined with platform information from the + [telemetry sdk resource][telemetry-sdk-resource] in order to extract more fine + grained information from a stacktrace, if necessary. + + [gcp-error-reporting]: https://cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report + [java-stacktrace]: https://docs.oracle.com/javase/7/docs/api/java/lang/Throwable.html#printStackTrace%28%29 + [python-stacktrace]: https://docs.python.org/3/library/traceback.html#traceback.format_exc + [js-stacktrace]: https://v8.dev/docs/stack-trace-api + [ruby-full-message]: https://docs.ruby-lang.org/en/3.4/Exception.html#method-i-full_message + [csharp-stacktrace]: https://docs.microsoft.com/dotnet/api/system.exception.tostring + [go-stacktrace]: https://pkg.go.dev/runtime/debug#Stack + [telemetry-sdk-resource]: ../resource/README.md#telemetry-sdk + [erlang-stacktrace]: https://www.erlang.org/doc/apps/stdlib/erl_error.html#format_exception/3 + [elixir-stacktrace]: https://hexdocs.pm/elixir/1.14.3/Exception.html#format/3 examples: > at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n diff --git a/model/database/spans.yaml b/model/database/spans.yaml index a588eb35b0..6c3936240e 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -1007,12 +1007,12 @@ groups: recommended: > Non-parameterized query text SHOULD NOT be collected by default unless explicitly configured and sanitized to exclude sensitive data, e.g. by redacting all literal values present - in the query text. See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). + in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). Parameterized query text MUST also NOT be collected by default unless explicitly configured. The query parameter values themselves are opt-in, - see [`db.query.parameter.`](../registry/attributes/db.md)). + see [`db.query.parameter.`](/docs/registry/attributes/db.md)). note: > - For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). + For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. examples: ["SELECT * FROM wuser_table where username = :mykey"] diff --git a/model/exceptions/registry.yaml b/model/exceptions/registry.yaml index 7231a394de..3b11726c39 100644 --- a/model/exceptions/registry.yaml +++ b/model/exceptions/registry.yaml @@ -26,6 +26,38 @@ groups: brief: > A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. + note: | + The table below, adapted from [Google Cloud][gcp-error-reporting], includes + possible representations of stacktraces in various languages. The table is not + meant to be a recommendation for any particular language, although SIGs are free + to adopt them if they see fit. + + | Language | Format | + | ---------- | ------------------------------------------------------------------- | + | C# | the return value of [Exception.ToString()][csharp-stacktrace] | + | Elixir | the return value of [Exception.format/3][elixir-stacktrace] | + | Erlang | the return value of [`erl_error:format`][erlang-stacktrace] | + | Go | the return value of [runtime.Stack][go-stacktrace] | + | Java | the contents of [Throwable.printStackTrace()][java-stacktrace] | + | Javascript | the return value of [error.stack][js-stacktrace] as returned by V8 | + | Python | the return value of [traceback.format_exc()][python-stacktrace] | + | Ruby | the return value of [Exception.full_message][ruby-full-message] | + + Backends can use the language specified methodology for generating a stacktrace + combined with platform information from the + [telemetry sdk resource][telemetry-sdk-resource] in order to extract more fine + grained information from a stacktrace, if necessary. + + [gcp-error-reporting]: https://cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report + [java-stacktrace]: https://docs.oracle.com/javase/7/docs/api/java/lang/Throwable.html#printStackTrace%28%29 + [python-stacktrace]: https://docs.python.org/3/library/traceback.html#traceback.format_exc + [js-stacktrace]: https://v8.dev/docs/stack-trace-api + [ruby-full-message]: https://docs.ruby-lang.org/en/3.4/Exception.html#method-i-full_message + [csharp-stacktrace]: https://docs.microsoft.com/dotnet/api/system.exception.tostring + [go-stacktrace]: https://pkg.go.dev/runtime/debug#Stack + [telemetry-sdk-resource]: ../resource/README.md#telemetry-sdk + [erlang-stacktrace]: https://www.erlang.org/doc/apps/stdlib/erl_error.html#format_exception/3 + [elixir-stacktrace]: https://hexdocs.pm/elixir/1.14.3/Exception.html#format/3 examples: > Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n diff --git a/model/rpc/spans.yaml b/model/rpc/spans.yaml index 9d4383766d..5cff2d7165 100644 --- a/model/rpc/spans.yaml +++ b/model/rpc/spans.yaml @@ -33,7 +33,7 @@ groups: Remote procedure calls can only be represented with these semantic conventions when the names of the called service and method are known and available. - **Span name:** refer to the [Span Name](#span-name) section. + **Span name:** refer to the [Span Name](/docs/rpc/rpc-spans.md#span-name) section. **Span kind** MUST be `CLIENT`. extends: rpc diff --git a/templates/registry/markdown/event_readme.md.j2 b/templates/registry/markdown/event_readme.md.j2 deleted file mode 100644 index 1e86e8504b..0000000000 --- a/templates/registry/markdown/event_readme.md.j2 +++ /dev/null @@ -1,41 +0,0 @@ -{%- import 'stability.j2' as stability -%} - - - - - -# Event registry - -The event registry is the catalog of available Events. - -> [!WARNING] -> -> The following registry overview is a work in progress. - -Currently, the following namespaces exist: - - - - - - - - - -{% for bundle in ctx %} - - -{%- for group in bundle.groups | sort(attribute='name') -%} - {%- set my_file_name = bundle.id | kebab_case ~ "/" ~ (group.id | kebab_case) ~ ".md" -%} - - - - - -{%- endfor %} -{%- endfor %} - -
NamespaceEventStability
{{ bundle.id | title_case | acronym }}
{{ group.name }}{{ stability.htmlbadge(group.stability, group.deprecated) | trim }}
- From 6b5fd79d57b0c81b037505cb65578bf8ad81633b Mon Sep 17 00:00:00 2001 From: James Thompson Date: Wed, 16 Jul 2025 14:01:59 +1000 Subject: [PATCH 5/5] Interim Gen-ai solution --- docs/gen-ai/gen-ai-events.md | 251 +----------------- docs/gen-ai/gen-ai-implementations.md | 349 ++++++++++++++++++++++++++ 2 files changed, 351 insertions(+), 249 deletions(-) create mode 100644 docs/gen-ai/gen-ai-implementations.md diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md index 8724fa17e9..1719eabda0 100644 --- a/docs/gen-ai/gen-ai-events.md +++ b/docs/gen-ai/gen-ai-events.md @@ -6,17 +6,6 @@ linkTitle: Events **Status**: [Development][DocumentStatus] - - -- [Events](#events) -- [Custom events](#custom-events) -- [Examples](#examples) - - [Chat completion](#chat-completion) - - [Tools](#tools) - - [Chat completion with multiple choices](#chat-completion-with-multiple-choices) - - - > [!Warning] > > Existing GenAI instrumentations that are using @@ -65,247 +54,11 @@ Instrumentations MAY offer configuration options allowing to disable events or a Is now described in the namespace registry. +To see usage of the events defined in the registry refer to the [Gen-AI implementations](gen-ai-implementations.md) documentation. + ## Custom events System-specific events that are not covered in this document SHOULD be documented in corresponding Semantic Conventions extensions and SHOULD follow `{gen_ai.provider.name}.*` naming pattern. -## Examples - -### Chat completion - -This is an example of telemetry generated for a chat completion call with system and user messages. - -```mermaid -%%{init: -{ - "sequence": { "messageAlign": "left", "htmlLabels":true }, - "themeVariables": { "noteBkgColor" : "green", "noteTextColor": "black", "activationBkgColor": "green", "htmlLabels":true } -} -}%% -sequenceDiagram - participant A as Application - participant I as Instrumented Client - participant M as Model - A->>+I: #U+200D - I->>M: gen_ai.system.message: You are a helpful bot
gen_ai.user.message: Tell me a joke about OpenTelemetry - Note left of I: GenAI Client span - I-->M: gen_ai.choice: Why did the developer bring OpenTelemetry to the party? Because it always knows how to trace the fun! - I-->>-A: #U+200D -``` - -**GenAI Client span:** - -| Attribute name | Value | -|---------------------------------|--------------------------------------------| -| Span name | `"chat gpt-4"` | -| `gen_ai.provider.name` | `"openai"` | -| `gen_ai.request.model` | `"gpt-4"` | -| `gen_ai.request.max_tokens` | `200` | -| `gen_ai.request.top_p` | `1.0` | -| `gen_ai.response.id` | `"chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l"` | -| `gen_ai.response.model` | `"gpt-4-0613"` | -| `gen_ai.usage.output_tokens` | `47` | -| `gen_ai.usage.input_tokens` | `52` | -| `gen_ai.response.finish_reasons`| `["stop"]` | - -**Events:** - -1. `gen_ai.system.message` - - | Property | Value | - |---------------------|-------------------------------------------------------| - | `gen_ai.provider.name`| `"openai"` | - | Event body (with content enabled) | `{"content": "You're a helpful bot"}` | - -2. `gen_ai.user.message` - - | Property | Value | - |---------------------|-------------------------------------------------------| - | `gen_ai.provider.name`| `"openai"` | - | Event body (with content enabled) | `{"content":"Tell me a joke about OpenTelemetry"}` | - -3. `gen_ai.choice` - - | Property | Value | - |---------------------|-------------------------------------------------------| - | `gen_ai.provider.name`| `"openai"` | - | Event body (with content enabled) | `{"index":0,"finish_reason":"stop","message":{"content":"Why did the developer bring OpenTelemetry to the party? Because it always knows how to trace the fun!"}}` | - | Event body (without content) | `{"index":0,"finish_reason":"stop","message":{}}` | - -### Tools - -This is an example of telemetry generated for a chat completion call with user message and function definition -that results in a model requesting application to call provided function. Application executes a function and -requests another completion now with the tool response. - -```mermaid -%%{init: -{ - "sequence": { "messageAlign": "left", "htmlLabels":true }, - "themeVariables": { "noteBkgColor" : "green", "noteTextColor": "black", "activationBkgColor": "green", "htmlLabels":true } -} -}%% -sequenceDiagram - participant A as Application - participant I as Instrumented Client - participant M as Model - A->>+I: #U+200D - I->>M: gen_ai.user.message: What's the weather in Paris? - Note left of I: GenAI Client span 1 - I-->M: gen_ai.choice: Call to the get_weather tool with Paris as the location argument. - I-->>-A: #U+200D - A -->> A: parse tool parameters
execute tool
update chat history - A->>+I: #U+200D - I->>M: gen_ai.user.message: What's the weather in Paris?
gen_ai.assistant.message: get_weather tool call
gen_ai.tool.message: rainy, 57°F - Note left of I: GenAI Client span 2 - I-->M: gen_ai.choice: The weather in Paris is rainy and overcast, with temperatures around 57°F - I-->>-A: #U+200D -``` - -Here's the telemetry generated for each step in this scenario: - -**GenAI Client span 1:** - -| Attribute name | Value | -|---------------------|-------------------------------------------------------| -| Span name | `"chat gpt-4"` | -| `gen_ai.provider.name`| `"openai"` | -| `gen_ai.request.model`| `"gpt-4"` | -| `gen_ai.request.max_tokens`| `200` | -| `gen_ai.request.top_p`| `1.0` | -| `gen_ai.response.id`| `"chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l"` | -| `gen_ai.response.model`| `"gpt-4-0613"` | -| `gen_ai.usage.output_tokens`| `17` | -| `gen_ai.usage.input_tokens`| `47` | -| `gen_ai.response.finish_reasons`| `["tool_calls"]` | - - **Events**: - - All the following events are parented to the **GenAI chat span 1**. - - 1. `gen_ai.user.message` (not reported when capturing content is disabled) - - | Property | Value | - |---------------------|-------------------------------------------------------| - | `gen_ai.provider.name`| `"openai"` | - | Event body | `{"content":"What's the weather in Paris?"}` | - - 2. `gen_ai.choice` - - | Property | Value | - |---------------------|-------------------------------------------------------| - | `gen_ai.provider.name`| `"openai"` | - | Event body (with content) | `{"index":0,"finish_reason":"tool_calls","message":{"tool_calls":[{"id":"call_VSPygqKTWdrhaFErNvMV18Yl","function":{"name":"get_weather","arguments":"{\"location\":\"Paris\"}"},"type":"function"}]}` | - | Event body (without content) | `{"index":0,"finish_reason":"tool_calls","message":{"tool_calls":[{"id":"call_VSPygqKTWdrhaFErNvMV18Yl","function":{"name":"get_weather"},"type":"function"}]}` | - -**GenAI Client span 2:** - - | Attribute name | Value | - |---------------------------------|-------------------------------------------------------| - | Span name | `"chat gpt-4"` | - | `gen_ai.provider.name` | `"openai"` | - | `gen_ai.request.model` | `"gpt-4"` | - | `gen_ai.request.max_tokens` | `200` | - | `gen_ai.request.top_p` | `1.0` | - | `gen_ai.response.id` | `"chatcmpl-call_VSPygqKTWdrhaFErNvMV18Yl"` | - | `gen_ai.response.model` | `"gpt-4-0613"` | - | `gen_ai.usage.output_tokens` | `52` | - | `gen_ai.usage.input_tokens` | `47` | - | `gen_ai.response.finish_reasons`| `["stop"]` | - - **Events**: - - All the following events are parented to the **GenAI chat span 2**. - - In this example, the event content matches the original messages, but applications may also drop messages or change their content. - - 1. `gen_ai.user.message` - - | Property | Value | - |----------------------------------|------------------------------------------------------------| - | `gen_ai.provider.name` | `"openai"` | - | Event body | `{"content":"What's the weather in Paris?"}` | - - 2. `gen_ai.assistant.message` - - | Property | Value | - |----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| - | `gen_ai.provider.name` | `"openai"` | - | Event body (content enabled) | `{"tool_calls":[{"id":"call_VSPygqKTWdrhaFErNvMV18Yl","function":{"name":"get_weather","arguments":"{\"location\":\"Paris\"}"},"type":"function"}]}` | - | Event body (content not enabled) | `{"tool_calls":[{"id":"call_VSPygqKTWdrhaFErNvMV18Yl","function":{"name":"get_weather"},"type":"function"}]}` | - - 3. `gen_ai.tool.message` - - | Property | Value | - |----------------------------------|------------------------------------------------------------------------------------------------| - | `gen_ai.provider.name` | `"openai"` | - | Event body (content enabled) | `{"content":"rainy, 57°F","id":"call_VSPygqKTWdrhaFErNvMV18Yl"}` | - | Event body (content not enabled) | `{"id":"call_VSPygqKTWdrhaFErNvMV18Yl"}` | - - 4. `gen_ai.choice` - - | Property | Value | - |----------------------------------|-------------------------------------------------------------------------------------------------------------------------------| - | `gen_ai.provider.name` | `"openai"` | - | Event body (content enabled) | `{"index":0,"finish_reason":"stop","message":{"content":"The weather in Paris is rainy and overcast, with temperatures around 57°F"}}` | - | Event body (content not enabled) | `{"index":0,"finish_reason":"stop","message":{}}` | - -### Chat completion with multiple choices - -This example covers the scenario when user requests model to generate two completions for the same prompt : - -```mermaid -%%{init: -{ - "sequence": { "messageAlign": "left", "htmlLabels":true }, - "themeVariables": { "noteBkgColor" : "green", "noteTextColor": "black", "activationBkgColor": "green", "htmlLabels":true } -} -}%% -sequenceDiagram - participant A as Application - participant I as Instrumented Client - participant M as Model - A->>+I: #U+200D - I->>M: gen_ai.system.message - "You are a helpful bot"
gen_ai.user.message - "Tell me a joke about OpenTelemetry" - Note left of I: GenAI Client span - I-->M: gen_ai.choice - Why did the developer bring OpenTelemetry to the party? Because it always knows how to trace the fun!
gen_ai.choice - Why did OpenTelemetry get promoted? It had great span of control! - I-->>-A: #U+200D -``` - -**GenAI Client Span**: - -| Attribute name | Value | -|---------------------|--------------------------------------------| -| Span name | `"chat gpt-4"` | -| `gen_ai.provider.name`| `"openai"` | -| `gen_ai.request.model`| `"gpt-4"` | -| `gen_ai.request.max_tokens`| `200` | -| `gen_ai.request.top_p`| `1.0` | -| `gen_ai.response.id`| `"chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l"` | -| `gen_ai.response.model`| `"gpt-4-0613"` | -| `gen_ai.usage.output_tokens`| `77` | -| `gen_ai.usage.input_tokens`| `52` | -| `gen_ai.response.finish_reasons`| `["stop", "stop"]` | - -**Events**: - -All events are parented to the GenAI chat span above. - -1. `gen_ai.system.message`: the same as in the [Chat Completion](#chat-completion) example -2. `gen_ai.user.message`: the same as in the [Chat Completion](#chat-completion) example -3. `gen_ai.choice` - - | Property | Value | - |------------------------------|-------------------------------------------------------| - | `gen_ai.provider.name` | `"openai"` | - | Event body (content enabled) | `{"index":0,"finish_reason":"stop","message":{"content":"Why did the developer bring OpenTelemetry to the party? Because it always knows how to trace the fun!"}}` | - -4. `gen_ai.choice` - - | Property | Value | - |------------------------------|-------------------------------------------------------| - | `gen_ai.provider.name` | `"openai"` | - | Event body (content enabled) | `{"index":1,"finish_reason":"stop","message":{"content":"Why did OpenTelemetry get promoted? It had great span of control!"}}` | - [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/gen-ai/gen-ai-implementations.md b/docs/gen-ai/gen-ai-implementations.md new file mode 100644 index 0000000000..5c1738d954 --- /dev/null +++ b/docs/gen-ai/gen-ai-implementations.md @@ -0,0 +1,349 @@ + + +# Implementation of Semantic conventions for generative AI + +**Status**: [Development][DocumentStatus] + + + +- [Chat completion](#chat-completion) + - [GenAI Client](#genai-client) +- [Tools](#tools) + - [GenAI Client Span 1](#genai-client-span-1) + - [GenAI Client Span 2](#genai-client-span-2) +- [Chat completion with multiple choices](#chat-completion-with-multiple-choices) + - [GenAI Client](#genai-client-1) + + + +> [!Warning] +> +> Existing GenAI instrumentations that are using +> [v1.36.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.36.0/docs/gen-ai/README.md) +> (or prior): +> +> * SHOULD NOT change the version of the GenAI conventions that they emit by default. +> Conventions include, but are not limited to, attributes, metric, span and event names, +> span kind and unit of measure. +> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` +> as a comma-separated list of category-specific values. The list of values +> includes: +> * `gen_ai_latest_experimental` - emit the latest experimental version of +> GenAI conventions (supported by the instrumentation) and do not emit the +> old one (v1.36.0 or prior). +> * The default behavior is to continue emitting whatever version of the GenAI +> conventions the instrumentation was emitting (1.36.0 or prior). +> +> This transition plan will be updated to include stable version before the +> GenAI conventions are marked as stable. + +GenAI instrumentations MAY capture user inputs sent to the model and responses received from it as [events](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.46.0/specification/logs/data-model.md#events). + +> Note: +> Events are in-development and not yet available in some languages. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.46.0/spec-compliance-matrix.md#logs) to see the implementation status in corresponding language. + +Instrumentations MAY capture inputs and outputs if and only if application has enabled the collection of this data. +This is for three primary reasons: + +1. Data privacy concerns. End users of GenAI applications may input sensitive information or personally identifiable information (PII) that they do not wish to be sent to a telemetry backend. +2. Data size concerns. Although there is no specified limit to sizes, there are practical limitations in programming languages and telemetry systems. Some GenAI systems allow for extremely large context windows that end users may take full advantage of. +3. Performance concerns. Sending large amounts of data to a telemetry backend may cause performance issues for the application. + +Body fields that contain user input, model output, or other potentially sensitive and verbose data +SHOULD NOT be captured by default. + +Semantic conventions for individual systems which extend content events SHOULD document all additional body fields and specify whether they +should be captured by default or need application to opt into capturing them. + +Telemetry consumers SHOULD expect to receive unknown body fields. + +Instrumentations SHOULD NOT capture undocumented body fields and MUST follow the documented defaults for known fields. +Instrumentations MAY offer configuration options allowing to disable events or allowing to capture all fields. + +## Chat completion + +This is an example of telemetry generated for a chat completion call with system and user messages. + +```mermaid +%%{init: +{ + "sequence": { "messageAlign": "left", "htmlLabels":true }, + "themeVariables": { "noteBkgColor" : "green", "noteTextColor": "black", "activationBkgColor": "green", "htmlLabels":true } +} +}%% +sequenceDiagram + participant A as Application + participant I as Instrumented Client + participant M as Model + A->>+I: #U+200D + I->>M: gen_ai.system.message: You are a helpful bot
gen_ai.user.message: Tell me a joke about OpenTelemetry + Note left of I: GenAI Client span + I-->M: gen_ai.choice: Why did the developer bring OpenTelemetry to the party? Because it always knows how to trace the fun! + I-->>-A: #U+200D +``` + +### GenAI Client + +**Span:** + +A GenAI implementation following Open Telemetry will implement the [Gen AI Inference](gen-ai-spans.md#inference) span to describe the transaction. It is expected that the attributes of the span are set according to the table below. + +| Attribute name | Value | +|---------------------------------|--------------------------------------------| +| Span name | `"chat gpt-4"` | +| `gen_ai.provider.name` | `"openai"` | +| `gen_ai.request.model` | `"gpt-4"` | +| `gen_ai.request.max_tokens` | `200` | +| `gen_ai.request.top_p` | `1.0` | +| `gen_ai.response.id` | `"chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l"` | +| `gen_ai.response.model` | `"gpt-4-0613"` | +| `gen_ai.usage.output_tokens` | `47` | +| `gen_ai.usage.input_tokens` | `52` | +| `gen_ai.response.finish_reasons`| `["stop"]` | + +**Events:** + +**1. `gen_ai.system.message`** + +A GenAI implementation following Open Telemetry will implement the [System Message](/docs/registry/namespaces/gen-ai/event-gen-ai-system-message.md) event to describe the system instructions passed to the GenAI model. It is expected that the attributes/properties of the event are set according to the table below. + + | Property | Value | + |---------------------|-------------------------------------------------------| + | `gen_ai.provider.name`| `"openai"` | + | Event body (with content enabled) | `{"content": "You're a helpful bot"}` | + +**2. `gen_ai.user.message`** + +A GenAI implementation following Open Telemetry will implement the [User Message](/docs/registry/namespaces/gen-ai/event-gen-ai-user-message.md) event to describe the user message passed to the GenAI model. It is expected that the attributes/properties of the event are set according to the table below. + + | Property | Value | + |---------------------|-------------------------------------------------------| + | `gen_ai.provider.name`| `"openai"` | + | Event body (with content enabled) | `{"content":"Tell me a joke about OpenTelemetry"}` | + +**3. `gen_ai.choice`** + +A GenAI implementation following Open Telemetry will implement the [Choice](/docs/registry/namespaces/gen-ai/event-gen-ai-choice.md) event to describe the Gen AI response message. It is expected that the attributes/properties of the event are set according to the table below. + + | Property | Value | + |---------------------|-------------------------------------------------------| + | `gen_ai.provider.name`| `"openai"` | + | Event body (with content enabled) | `{"index":0,"finish_reason":"stop","message":{"content":"Why did the developer bring OpenTelemetry to the party? Because it always knows how to trace the fun!"}}` | + | Event body (without content) | `{"index":0,"finish_reason":"stop","message":{}}` | + +## Tools + +This is an example of telemetry generated for a chat completion call with user message and function definition +that results in a model requesting application to call provided function. Application executes a function and +requests another completion now with the tool response. + +```mermaid +%%{init: +{ + "sequence": { "messageAlign": "left", "htmlLabels":true }, + "themeVariables": { "noteBkgColor" : "green", "noteTextColor": "black", "activationBkgColor": "green", "htmlLabels":true } +} +}%% +sequenceDiagram + participant A as Application + participant I as Instrumented Client + participant M as Model + A->>+I: #U+200D + I->>M: gen_ai.user.message: What's the weather in Paris? + Note left of I: GenAI Client span 1 + I-->M: gen_ai.choice: Call to the get_weather tool with Paris as the location argument. + I-->>-A: #U+200D + A -->> A: parse tool parameters
execute tool
update chat history + A->>+I: #U+200D + I->>M: gen_ai.user.message: What's the weather in Paris?
gen_ai.assistant.message: get_weather tool call
gen_ai.tool.message: rainy, 57°F + Note left of I: GenAI Client span 2 + I-->M: gen_ai.choice: The weather in Paris is rainy and overcast, with temperatures around 57°F + I-->>-A: #U+200D +``` + +Here's the telemetry generated for each step in this scenario: + +### GenAI Client Span 1 + +**Span:** + +A GenAI implementation following Open Telemetry will implement the [Gen AI Inference](gen-ai-spans.md#inference) span to describe the transaction. It is expected that the attributes of the span are set according to the table below. + +| Attribute name | Value | +|---------------------|-------------------------------------------------------| +| Span name | `"chat gpt-4"` | +| `gen_ai.provider.name`| `"openai"` | +| `gen_ai.request.model`| `"gpt-4"` | +| `gen_ai.request.max_tokens`| `200` | +| `gen_ai.request.top_p`| `1.0` | +| `gen_ai.response.id`| `"chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l"` | +| `gen_ai.response.model`| `"gpt-4-0613"` | +| `gen_ai.usage.output_tokens`| `17` | +| `gen_ai.usage.input_tokens`| `47` | +| `gen_ai.response.finish_reasons`| `["tool_calls"]` | + +**Events:** + +All the following events are parented to the **GenAI chat span 1**. + +**1. `gen_ai.user.message` (not reported when capturing content is disabled)** + +A GenAI implementation following Open Telemetry will implement the [User Message](/docs/registry/namespaces/gen-ai/event-gen-ai-user-message.md) event to describe the user message passed to the GenAI model. It is expected that the attributes/properties of the event are set according to the table below. + +| Property | Value | +|---------------------|-------------------------------------------------------| +| `gen_ai.provider.name`| `"openai"` | +| Event body | `{"content":"What's the weather in Paris?"}` | + +**2. `gen_ai.choice`** + +A GenAI implementation following Open Telemetry will implement the [Choice](/docs/registry/namespaces/gen-ai/event-gen-ai-choice.md) event to describe the Gen AI response message. It is expected that the attributes/properties of the event are set according to the table below. + +| Property | Value | +|---------------------|-------------------------------------------------------| +| `gen_ai.provider.name`| `"openai"` | +| Event body (with content) | `{"index":0,"finish_reason":"tool_calls","message":{"tool_calls":[{"id":"call_VSPygqKTWdrhaFErNvMV18Yl","function":{"name":"get_weather","arguments":"{\"location\":\"Paris\"}"},"type":"function"}]}` | +| Event body (without content) | `{"index":0,"finish_reason":"tool_calls","message":{"tool_calls":[{"id":"call_VSPygqKTWdrhaFErNvMV18Yl","function":{"name":"get_weather"},"type":"function"}]}` | + +### GenAI Client Span 2 + +**Span:** + +A GenAI implementation following Open Telemetry will implement the [Gen AI Inference](gen-ai-spans.md#inference) span to describe the transaction. It is expected that the attributes of the span are set according to the table below. + +| Attribute name | Value | +|---------------------------------|-------------------------------------------------------| +| Span name | `"chat gpt-4"` | +| `gen_ai.provider.name` | `"openai"` | +| `gen_ai.request.model` | `"gpt-4"` | +| `gen_ai.request.max_tokens` | `200` | +| `gen_ai.request.top_p` | `1.0` | +| `gen_ai.response.id` | `"chatcmpl-call_VSPygqKTWdrhaFErNvMV18Yl"` | +| `gen_ai.response.model` | `"gpt-4-0613"` | +| `gen_ai.usage.output_tokens` | `52` | +| `gen_ai.usage.input_tokens` | `47` | +| `gen_ai.response.finish_reasons`| `["stop"]` | + +**Events:** + +All the following events are parented to the **GenAI chat span 2**. + +In this example, the event content matches the original messages, but applications may also drop messages or change their content. + +**1. `gen_ai.user.message`** + +A GenAI implementation following Open Telemetry will implement the [User Message](/docs/registry/namespaces/gen-ai/event-gen-ai-user-message.md) event to describe the user message passed to the GenAI model. It is expected that the attributes/properties of the event are set according to the table below. + +| Property | Value | +|----------------------------------|------------------------------------------------------------| +| `gen_ai.provider.name` | `"openai"` | +| Event body | `{"content":"What's the weather in Paris?"}` | + +**2. `gen_ai.assistant.message`** + +A GenAI implementation following Open Telemetry will implement the [Assistant Message](/docs/registry/namespaces/gen-ai/event-gen-ai-assistant-message.md) event to describe the assistant message passed to GenAI system. It is expected that the attributes/properties of the event are set according to the table below. + +| Property | Value | +|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| +| `gen_ai.provider.name` | `"openai"` | +| Event body (content enabled) | `{"tool_calls":[{"id":"call_VSPygqKTWdrhaFErNvMV18Yl","function":{"name":"get_weather","arguments":"{\"location\":\"Paris\"}"},"type":"function"}]}` | +| Event body (content not enabled) | `{"tool_calls":[{"id":"call_VSPygqKTWdrhaFErNvMV18Yl","function":{"name":"get_weather"},"type":"function"}]}` | + +**3. `gen_ai.tool.message`** + +A GenAI implementation following Open Telemetry will implement the [Assistant Message](/docs/registry/namespaces/gen-ai/event-gen-ai-assistant-message.md) event to describe the response from a tool or function call passed to the GenAI model. It is expected that the attributes/properties of the event are set according to the table below. + +| Property | Value | +|----------------------------------|------------------------------------------------------------------------------------------------| +| `gen_ai.provider.name` | `"openai"` | +| Event body (content enabled) | `{"content":"rainy, 57°F","id":"call_VSPygqKTWdrhaFErNvMV18Yl"}` | +| Event body (content not enabled) | `{"id":"call_VSPygqKTWdrhaFErNvMV18Yl"}` | + +**4. `gen_ai.choice`** + +A GenAI implementation following Open Telemetry will implement the [Choice](/docs/registry/namespaces/gen-ai/event-gen-ai-choice.md) event to describe the Gen AI response message. It is expected that the attributes/properties of the event are set according to the table below. + +| Property | Value | +|----------------------------------|-------------------------------------------------------------------------------------------------------------------------------| +| `gen_ai.provider.name` | `"openai"` | +| Event body (content enabled) | `{"index":0,"finish_reason":"stop","message":{"content":"The weather in Paris is rainy and overcast, with temperatures around 57°F"}}` | +| Event body (content not enabled) | `{"index":0,"finish_reason":"stop","message":{}}` | + +## Chat completion with multiple choices + +This example covers the scenario when user requests model to generate two completions for the same prompt : + +```mermaid +%%{init: +{ + "sequence": { "messageAlign": "left", "htmlLabels":true }, + "themeVariables": { "noteBkgColor" : "green", "noteTextColor": "black", "activationBkgColor": "green", "htmlLabels":true } +} +}%% +sequenceDiagram + participant A as Application + participant I as Instrumented Client + participant M as Model + A->>+I: #U+200D + I->>M: gen_ai.system.message - "You are a helpful bot"
gen_ai.user.message - "Tell me a joke about OpenTelemetry" + Note left of I: GenAI Client span + I-->M: gen_ai.choice - Why did the developer bring OpenTelemetry to the party? Because it always knows how to trace the fun!
gen_ai.choice - Why did OpenTelemetry get promoted? It had great span of control! + I-->>-A: #U+200D +``` + +### GenAI Client + +**Span:** + +A GenAI implementation following Open Telemetry will implement the [Gen AI Inference](gen-ai-spans.md#inference) span to describe the transaction. It is expected that the attributes of the span are set according to the table below. + +| Attribute name | Value | +|---------------------|--------------------------------------------| +| Span name | `"chat gpt-4"` | +| `gen_ai.provider.name`| `"openai"` | +| `gen_ai.request.model`| `"gpt-4"` | +| `gen_ai.request.max_tokens`| `200` | +| `gen_ai.request.top_p`| `1.0` | +| `gen_ai.response.id`| `"chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l"` | +| `gen_ai.response.model`| `"gpt-4-0613"` | +| `gen_ai.usage.output_tokens`| `77` | +| `gen_ai.usage.input_tokens`| `52` | +| `gen_ai.response.finish_reasons`| `["stop", "stop"]` | + +**Events:** + +All events are parented to the GenAI chat span above. + +**1. `gen_ai.system.message`:** + +A GenAI implementation following Open Telemetry will implement the [System Message](/docs/registry/namespaces/gen-ai/event-gen-ai-system-message.md) event to describe the system instructions passed to the GenAI model. It is expected that the attributes/properties of the event are set according to the table below. + +The same as in the [Chat Completion](#chat-completion) example + +**2. `gen_ai.user.message`:** + +A GenAI implementation following Open Telemetry will implement the [User Message](/docs/registry/namespaces/gen-ai/event-gen-ai-user-message.md) event to describe the user message passed to the GenAI model. It is expected that the attributes/properties of the event are set according to the table below. + +The same as in the [Chat Completion](#chat-completion) example + +**3. `gen_ai.choice`** + +A GenAI implementation following Open Telemetry will implement the [Choice](/docs/registry/namespaces/gen-ai/event-gen-ai-choice.md) event to describe the Gen AI response message. It is expected that the attributes/properties of the event are set according to the table below. + +| Property | Value | +|------------------------------|-------------------------------------------------------| +| `gen_ai.provider.name` | `"openai"` | +| Event body (content enabled) | `{"index":0,"finish_reason":"stop","message":{"content":"Why did the developer bring OpenTelemetry to the party? Because it always knows how to trace the fun!"}}` | + +**4. `gen_ai.choice`** + +A GenAI implementation following Open Telemetry will implement the [Choice](/docs/registry/namespaces/gen-ai/event-gen-ai-choice.md) event to describe the Gen AI response message. It is expected that the attributes/properties of the event are set according to the table below. + +| Property | Value | +|------------------------------|-------------------------------------------------------| +| `gen_ai.provider.name` | `"openai"` | +| Event body (content enabled) | `{"index":1,"finish_reason":"stop","message":{"content":"Why did OpenTelemetry get promoted? It had great span of control!"}}` | + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status