From 56bec66129f2c5f805b6f3e5229736dfa1e42f0a Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 18 Dec 2024 19:20:39 -0800 Subject: [PATCH 1/6] Refactor and update naming guidance (#1694) Co-authored-by: Trask Stalnaker --- .chloggen/1694.yaml | 8 + CONTRIBUTING.md | 2 +- docs/attributes-registry/README.md | 2 +- docs/general/README.md | 9 - docs/general/attribute-naming.md | 177 ------------- docs/general/events.md | 2 +- docs/general/metrics.md | 146 +---------- docs/general/naming.md | 312 +++++++++++++++++++++++ docs/system/README.md | 2 + model/README.md | 2 +- templates/registry/markdown/readme.md.j2 | 2 +- 11 files changed, 336 insertions(+), 328 deletions(-) create mode 100644 .chloggen/1694.yaml delete mode 100644 docs/general/attribute-naming.md create mode 100644 docs/general/naming.md diff --git a/.chloggen/1694.yaml b/.chloggen/1694.yaml new file mode 100644 index 0000000000..ddf40d60a4 --- /dev/null +++ b/.chloggen/1694.yaml @@ -0,0 +1,8 @@ +change_type: enhancement +component: docs +note: Update attribute, events, and metrics naming guidance to include new best practices. +subtext: | + - Use namespaces (with `.` delimiter) whenever possible. + - Use precise, descriptive, unambiguous names that leave room for expansion. + +issues: [1694] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5f764273a9..4cfc04991c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -399,7 +399,7 @@ exists in some form in ECS, consider the following guidelines: data, user issue reports, feature requests, examples of prior work on a different standard or comparable evidence about the alternatives. - When no suitable alternatives are provided, altering an ECS name solely - for the purpose of complying with [Name Pluralization guidelines](docs/general/attribute-naming.md#name-pluralization-guidelines) + for the purpose of complying with [Name Pluralization guidelines](docs/general/naming.md#attribute-name-pluralization-guidelines) MAY BE avoided. - Do not use an existing ECS name as a namespace. If the name must differ, use a different namespace name to avoid clashes or avoid using the namespace diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 91df4271b1..4bfe974911 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -102,4 +102,4 @@ Currently, the following namespaces exist: - [VCS](vcs.md) - [Webengine](webengine.md) -[developers recommendations]: ../general/attribute-naming.md#recommendations-for-application-developers +[developers recommendations]: ../general/naming.md#recommendations-for-application-developers diff --git a/docs/general/README.md b/docs/general/README.md index a4bff5597e..83fd3366cb 100644 --- a/docs/general/README.md +++ b/docs/general/README.md @@ -17,12 +17,3 @@ The following general Semantic Conventions are defined: * [Logs](logs.md): General Semantic Conventions for logs. * [Metrics](metrics.md): General Semantic Conventions for metrics. * [Spans](trace.md): General Semantic Conventions for traces / spans. - -## Event Name Reuse Prohibition - -A new event MUST NOT be added with the same name as an event that existed in -the past but was renamed (with a corresponding schema file). - -When introducing a new event name check all existing schema files to make sure -the name does not appear as a key of any "rename_events" section (keys denote -old event names in rename operations). diff --git a/docs/general/attribute-naming.md b/docs/general/attribute-naming.md deleted file mode 100644 index 34e84d2f9d..0000000000 --- a/docs/general/attribute-naming.md +++ /dev/null @@ -1,177 +0,0 @@ -# Attribute Naming - -**Status**: [Stable][DocumentStatus] - -
-Table of Contents - - - -- [Name Pluralization Guidelines](#name-pluralization-guidelines) -- [Name Abbreviation Guidelines](#name-abbreviation-guidelines) -- [Name Reuse Prohibition](#name-reuse-prohibition) -- [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors) -- [Recommendations for Application Developers](#recommendations-for-application-developers) -- [otel.\* Namespace](#otel-namespace) - - - -
- -_This section applies to Resource, Span, Log, and Metric attribute names (also -known as the "attribute keys"). For brevity within this section when we use the -term "name" without an adjective it is implied to mean "attribute name"._ - -Every name MUST be a valid Unicode sequence. - -_Note: we merely require that the names are represented as Unicode sequences. -This specification does not define how exactly the Unicode sequences are -encoded. The encoding can vary from one programming language to another and from -one wire format to another. Use the idiomatic way to represent Unicode in the -particular programming language or wire format._ - -Names SHOULD follow these rules: - -- Names SHOULD be lowercase. - -- Use namespacing to avoid name clashes. Delimit the namespaces using a dot - character. For example `service.version` denotes the service version where - `service` is the namespace and `version` is an attribute in that namespace. - -- Namespaces can be nested. For example `telemetry.sdk` is a namespace inside - top-level `telemetry` namespace and `telemetry.sdk.name` is an attribute - inside `telemetry.sdk` namespace. Note: the fact that an entity is located - within another entity is typically not a sufficient reason for forming nested - namespaces. The purpose of a namespace is to avoid name clashes, not to - indicate entity hierarchies. This purpose should primarily drive the decision - about forming nested namespaces. - -- For each multi-word dot-delimited component of the attribute name separate the - words by underscores (i.e. use snake_case). For example - `http.response.status_code` denotes the status code in the http namespace. - -- Names SHOULD NOT coincide with namespaces. For example if - `service.instance.id` is an attribute name then it is no longer valid to have - an attribute named `service.instance` because `service.instance` is already a - namespace. Because of this rule be careful when choosing names: every existing - name prohibits existence of an equally named namespace in the future, and vice - versa: any existing namespace prohibits existence of an equally named - attribute key in the future. - -## Name Pluralization Guidelines - -- When an attribute represents a single entity, the attribute name SHOULD be - singular. Examples: `host.name`, `container.id`. - -- When attribute can represent multiple entities, the attribute name SHOULD be - pluralized and the value type SHOULD be an array. E.g. `process.command_args` - might include multiple values: the executable name and command arguments. - -- When an attribute represents a measurement, - [Metric Name Pluralization Guidelines](./metrics.md#pluralization) SHOULD be - followed for the attribute name. - -## Name Abbreviation Guidelines - -Abbreviations MAY be used when they are widely recognized and commonly used. - -Examples include common technical abbreviations such as `IP`, `DB`, `CPU`, -`HTTP`, `URL`, or product names like `AWS`, `GCP`, `K8s`. - -Abbreviations SHOULD be avoided if they are ambiguous, for example, when they apply -to multiple products or concepts. - -## Name Reuse Prohibition - -A new attribute MUST NOT be added with the same name as an attribute that -existed in the past but was renamed (with a corresponding schema file). - -When introducing a new attribute name check all existing schema files to make -sure the name does not appear as a key of any "rename_attributes" section (keys -denote old attribute names in rename operations). - -## Recommendations for OpenTelemetry Authors - -- All names that are part of OpenTelemetry semantic conventions SHOULD be part - of a namespace. - -- When coming up with a new semantic convention make sure to check existing - namespaces ([Semantic Conventions](./README.md)) to see if the new name fits. - -- When a new namespace is necessary consider whether it should be a top-level - namespace (e.g. `service`) or a nested namespace (e.g. `service.instance`). - -- Semantic conventions exist for four areas: for Resource, Span, Log, and Metric - attribute names. In addition, for spans we have two more areas: Event and Link - attribute names. Identical namespaces or names in all these areas MUST have - identical meanings. For example the `http.request.method` span attribute name - denotes exactly the same concept as the `http.request.method` metric - attribute, has the same data type and the same set of possible values (in both - cases it records the value of the HTTP protocol's request method as a string). - -- Semantic conventions MUST limit names to printable Basic Latin characters - (more precisely to - [U+0021 .. U+007E]() - subset of Unicode code points). It is recommended to further limit names to - the following Unicode code points: Latin alphabet, Numeric, Underscore, Dot - (as namespace delimiter). - -> Note: -> Semantic Conventions tooling limits names to lowercase -> Latin alphabet, Numeric, Underscore, Dot (as namespace delimiter). -> Names must start with a letter, end with an alphanumeric character, and must not -> contain two or more consecutive delimiters (Underscore or Dot). - -## Recommendations for Application Developers - -As an application developer when you need to record an attribute first consult -existing [semantic conventions](./README.md). If an appropriate name does not -exists you will need to come up with a new name. To do that consider a few -options: - -- The name is specific to your company and may be possibly used outside the - company as well. To avoid clashes with names introduced by other companies (in - a distributed system that uses applications from multiple vendors) it is - recommended to prefix the new name by your company's reverse domain name, e.g. - `com.acme.shopname`. - -- The name is specific to your application that will be used internally only. If - you already have an internal company process that helps you to ensure no name - clashes happen then feel free to follow it. Otherwise it is recommended to - prefix the attribute name by your application name, provided that the - application name is reasonably unique within your organization (e.g. - `myuniquemapapp.longitude` is likely fine). Make sure the application name - does not clash with an existing semantic convention namespace. - -- It is not recommended to use existing OpenTelemetry semantic convention - namespace as a prefix for a new company- or application-specific attribute - name. Doing so may result in a name clash in the future, if OpenTelemetry - decides to use that same name for a different purpose or if some other third - party instrumentation decides to use that exact same attribute name and you - combine that instrumentation with your own. - -- The name may be generally applicable to applications in the industry. In that - case consider submitting a proposal to this specification to add a new name to - the semantic conventions, and if necessary also to add a new namespace. - -It is recommended to limit names to printable Basic Latin characters (more -precisely to -[U+0021 .. U+007E]() -subset of Unicode code points). - -## otel.\* Namespace - -Attribute names that start with `otel.` are reserved to be defined by -OpenTelemetry specification. These are typically used to express OpenTelemetry -concepts in formats that don't have a corresponding concept. - -For example, the `otel.scope.name` attribute is used to record the -instrumentation scope name, which is an OpenTelemetry concept that is natively -represented in OTLP, but does not have an equivalent in other telemetry formats -and protocols. - -Any additions to the `otel.*` namespace MUST be approved as part of -OpenTelemetry specification. - -[DocumentStatus]: - https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/general/events.md b/docs/general/events.md index c63aa5904a..4e80862f13 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -31,7 +31,7 @@ structure and semantics will also be defined. ## General event semantics * An event MUST have an [Event name property](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) - that uniquely identifies the event. Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). + that uniquely identifies the event. Event names are subject to the [Naming guidelines](/docs/general/naming.md). * Event MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) attributes that provide additional context about the event. * It MAY contain a _payload_ (body) that describes the specific details of the diff --git a/docs/general/metrics.md b/docs/general/metrics.md index fbe38ea7c4..961abaedf4 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -10,15 +10,7 @@ aliases: [metrics-general] - [General Guidelines](#general-guidelines) - - [Name Reuse Prohibition](#name-reuse-prohibition) - - [Metric attributes](#metric-attributes) - [Units](#units) - - [Naming rules for Counters and UpDownCounters](#naming-rules-for-counters-and-updowncounters) - - [Pluralization](#pluralization) - - [Use `count` Instead of Pluralization for UpDownCounters](#use-count-instead-of-pluralization-for-updowncounters) - - [Do not use `total`](#do-not-use-total) -- [General Metric Semantic Conventions](#general-metric-semantic-conventions) - - [Instrument Naming](#instrument-naming) - [Instrument Units](#instrument-units) - [Instrument Types](#instrument-types) - [Consistent UpDownCounter timeseries](#consistent-updowncounter-timeseries) @@ -30,12 +22,16 @@ The following semantic conventions surrounding metrics are defined: * **[General Guidelines](#general-guidelines): General metrics guidelines.** * [Database](/docs/database/database-metrics.md): For SQL and NoSQL client metrics. * [FaaS](/docs/faas/faas-metrics.md): For [Function as a Service](https://wikipedia.org/wiki/Function_as_a_service) metrics. +* [GenAI](/docs/gen-ai/gen-ai-metrics.md): For Generative AI metrics. * [HTTP](/docs/http/http-metrics.md): For HTTP client and server metrics. * [Messaging](/docs/messaging/messaging-metrics.md): For messaging systems (queues, publish/subscribe, etc.) metrics. * [RPC](/docs/rpc/rpc-metrics.md): For RPC client and server metrics. +* [.NET](/docs/dotnet/README.md): For network-related metrics emitted by .NET runtime components. * **System metrics** * [System](/docs/system/system-metrics.md): For standard system metrics. + * [Container](/docs/system/container-metrics.md) * [Hardware](/docs/system/hardware-metrics.md): For hardware-related metrics. + * [K8s](/docs/system/k8s-metrics.md): For K8s metrics. * [Process](/docs/system/process-metrics.md): For standard process metrics. * [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics. @@ -47,11 +43,8 @@ their own [Resource Semantic Conventions](/docs/resource/README.md). **Status**: [Experimental][DocumentStatus] -Metric names and attributes exist within a single universe and a single -hierarchy. Metric names and attributes MUST be considered within the universe of -all existing metric names. When defining new metric names and attributes, -consider the prior art of existing standard metrics and metrics from -frameworks/libraries. +When defining new metric names and attributes, consider the prior art of +existing standard metrics and metrics from frameworks/libraries. Associated metrics SHOULD be nested together in a hierarchy based on their usage. Define a top-level hierarchy for common metric categories: for OS @@ -78,41 +71,11 @@ where similar metrics have significantly different implementations across the breadth of all existing metrics. For example, every garbage collected runtime has slightly different strategies and measures. Using a single set of metric names for GC, not divided by the runtime, could create dissimilar comparisons -and confusion for end users. (For example, prefer `process.runtime.java.gc*` over -`process.runtime.gc.*`.) Measures of many operating system metrics are similarly +and confusion for end users. (For example, prefer `jvm.gc*` over +`gc.*`.) Measures of many operating system metrics are similarly ambiguous. -Metric names and attributes SHOULD follow the general -[name abbreviation guidelines](attribute-naming.md#name-abbreviation-guidelines). - -### Name Reuse Prohibition - -A new metric MUST NOT be added with the same name as a metric that existed in -the past but was renamed (with a corresponding schema file). - -When introducing a new metric name check all existing schema files to make sure -the name does not appear as a key of any "rename_metrics" section (keys denote -old metric names in rename operations). - -### Metric attributes - -Metric attributes SHOULD follow the general [attribute naming rules](attribute-naming.md). -In particular, metric attributes SHOULD have a namespace. - -Metric attributes SHOULD be added under the metric namespace when their usage and -semantics are exclusive to the metric. - -Examples: - -Attributes `mode` and `mountpoint` for metric `system.filesystem.usage` -should be namespaced as `system.filesystem.mode` and `system.filesystem.mountpoint`. - -Metrics can also have attributes outside of their namespace. - -Examples: - -Metric `http.server.request.duration` uses attributes from the registry such as -`server.port`, `error.type`. +Metric names and attributes SHOULD follow the general [naming guidelines](naming.md). ### Units @@ -126,97 +89,6 @@ When building components that interoperate between OpenTelemetry and a system using the OpenMetrics exposition format, use the [OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/compatibility/prometheus_and_openmetrics.md). -### Naming rules for Counters and UpDownCounters - -#### Pluralization - -Metric namespaces SHOULD NOT be pluralized. - -Metric names SHOULD NOT be pluralized, unless the value being recorded -represents discrete instances of a -[countable quantity](https://wikipedia.org/wiki/Count_noun). -Generally, the name SHOULD be pluralized only if the unit of the metric in -question is a non-unit (like `{fault}` or `{operation}`). - -Examples: - -* `system.filesystem.utilization`, `http.server.request.duration`, and `system.cpu.time` -should not be pluralized, even if many data points are recorded. -* `system.paging.faults`, `system.disk.operations`, and `system.network.packets` -should be pluralized, even if only a single data point is recorded. - -#### Use `count` Instead of Pluralization for UpDownCounters - -If the value being recorded represents the count of concepts signified -by the namespace then the metric should be named `count` (within its namespace). - -For example if we have a namespace `system.process` which contains all metrics related -to the processes then to represent the count of the processes we can have a metric named -`system.process.count`. - -#### Do not use `total` - -UpDownCounters SHOULD NOT use `_total` because then they will look like -monotonic sums. - -Counters SHOULD NOT append `_total` either because then their meaning will -be confusing in delta backends. - -## General Metric Semantic Conventions - -**Status**: [Mixed][DocumentStatus] - -The following semantic conventions aim to keep naming consistent. They -provide guidelines for most of the cases in this specification and should be -followed for other instruments not explicitly defined in this document. - -### Instrument Naming - -**Status**: [Experimental][DocumentStatus] - -- **limit** - an instrument that measures the constant, known total amount of -something should be called `entity.limit`. For example, `system.memory.limit` -for the total amount of memory on a system. - -- **usage** - an instrument that measures an amount used out of a known total -(**limit**) amount should be called `entity.usage`. For example, -`system.memory.usage` with attribute `state = used | cached | free | ...` for the -amount of memory in a each state. Where appropriate, the sum of **usage** -over all attribute values SHOULD be equal to the **limit**. - - A measure of the amount consumed of an unlimited resource, or of a resource - whose limit is unknowable, is differentiated from **usage**. For example, the - maximum possible amount of virtual memory that a process may consume may - fluctuate over time and is not typically known. - -- **utilization** - an instrument that measures the *fraction* of **usage** -out of its **limit** should be called `entity.utilization`. For example, -`system.memory.utilization` for the fraction of memory in use. Utilization can -be with respect to a fixed limit or a soft limit. Utilization values are -represented as a ratio and are typically in the range `[0, 1]`, but may go above 1 -in case of exceeding a soft limit. - -- **time** - an instrument that measures passage of time should be called -`entity.time`. For example, `system.cpu.time` with attribute `state = idle | user -| system | ...`. **time** measurements are not necessarily wall time and can -be less than or greater than the real wall time between measurements. - - **time** instruments are a special case of **usage** metrics, where the - **limit** can usually be calculated as the sum of **time** over all attribute - values. **utilization** for time instruments can be derived automatically - using metric event timestamps. For example, `system.cpu.utilization` is - defined as the difference in `system.cpu.time` measurements divided by the - elapsed time and number of CPUs. - -- **io** - an instrument that measures bidirectional data flow should be -called `entity.io` and have attributes for direction. For example, -`system.network.io`. - -- Other instruments that do not fit the above descriptions may be named more -freely. For example, `system.paging.faults` and `system.network.packets`. -Units do not need to be specified in the names since they are included during -instrument creation, but can be added if there is ambiguity. - ### Instrument Units **Status**: [Stable][DocumentStatus] diff --git a/docs/general/naming.md b/docs/general/naming.md new file mode 100644 index 0000000000..51b04cd7af --- /dev/null +++ b/docs/general/naming.md @@ -0,0 +1,312 @@ +# Naming + +**Status**: [Stable][DocumentStatus], Unless otherwise specified. + +
+Table of Contents + + + +- [General Naming Considerations](#general-naming-considerations) +- [Name Abbreviation Guidelines](#name-abbreviation-guidelines) +- [Name Reuse Prohibition](#name-reuse-prohibition) +- [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors) +- [Recommendations for Application Developers](#recommendations-for-application-developers) +- [Attributes](#attributes) + - [otel.\* Namespace](#otel-namespace) + - [Attribute Name Pluralization Guidelines](#attribute-name-pluralization-guidelines) + - [Signal-specific Attributes](#signal-specific-attributes) +- [Metrics](#metrics) + - [Naming Rules for Counters and UpDownCounters](#naming-rules-for-counters-and-updowncounters) + - [Pluralization](#pluralization) + - [Use `count` Instead of Pluralization for UpDownCounters](#use-count-instead-of-pluralization-for-updowncounters) + - [Do Not Use `total`](#do-not-use-total) + - [Instrument Naming](#instrument-naming) + + + +
+ +## General Naming Considerations + +_This section applies to attribute names (also +known as the "attribute keys"), as well as Metric and Event names. For brevity +within this section when we use the term "name" without an adjective it is +implied to mean all of these._ + +Every name MUST be a valid Unicode sequence. + +_Note: we merely require that the names are represented as Unicode sequences. +This specification does not define how exactly the Unicode sequences are +encoded. The encoding can vary from one programming language to another and from +one wire format to another. Use the idiomatic way to represent Unicode in the +particular programming language or wire format._ + +Names SHOULD follow these rules: + +- Names SHOULD be lowercase. + +- Use namespacing. Delimit the namespaces using a dot character. + For example `service.version` denotes the service version where + `service` is the namespace and `version` is an attribute in that namespace. + +- Namespaces can be nested. For example `telemetry.sdk` is a namespace inside + top-level `telemetry` namespace and `telemetry.sdk.name` is an attribute + inside `telemetry.sdk` namespace. + + Use namespaces (and dot separator) whenever it makes sense. For example + when introducing an attribute representing a property of some object, follow + `*{object}.{property}` pattern. Avoid using underscore (`*{object}_{property}`) + if this object could have other properties. + +- For each multi-word dot-delimited component of the name separate the + words by underscores (i.e. use snake_case). For example + `http.response.status_code` denotes the status code in the http namespace. + + Use underscore only when using dot (namespacing) does not make sense or changes + the semantic meaning of the name. For example, use `rate_limiting` + instead of `rate.limiting`. + +- Be precise. Attribute, event, metric, and other names should be descriptive and + unambiguous. + - When introducing a name describing a certain property of the object, + include the property name. For example, use `file.owner.name` instead of `file.owner` + and `system.network.packet.dropped` instead of `system.network.dropped` + - Avoid introducing names and namespaces that would mean different things when + used by different conventions or instrumentations. For example, use `security_rule` + instead of `rule`. + +- Use shorter names when it does not compromise clarity. Drop namespace + components or words in multi-word components when they are not necessary. For example, + `vcs.change.id` describes pull request id as precisely as `vcs.repository.change.id` does. + +## Name Abbreviation Guidelines + +Abbreviations MAY be used when they are widely recognized and commonly used. + +Examples include common technical abbreviations such as `IP`, `DB`, `CPU`, +`HTTP`, `URL`, or product names like `AWS`, `GCP`, `K8s`. + +Abbreviations that are commonly recognized but only within a certain domain MAY +be used when qualified by the corresponding namespace. + +For example, use `container.csi.*` instead of `container.container_storage_interface` +or `container.oci.*` instead of `container.open_container_initiative.*` + +Abbreviations SHOULD be avoided if they are ambiguous, for example, when they apply +to multiple products or concepts. + +## Name Reuse Prohibition + +Two attributes, two metrics, or two events MUST NOT share the same name. +Different entities (attribute and metric, metric and event) MAY share the same name. + +Attributes, metrics, and events SHOULD NOT be removed from semantic +conventions regardless of their maturity level. When the convention is renamed or +no longer recommended, it SHOULD be deprecated. + +## Recommendations for OpenTelemetry Authors + +- When coming up with a new semantic convention make sure to check existing + namespaces ([Semantic Conventions](/docs/README.md)) to see if a similar namespace + already exists. + +- All names that are part of OpenTelemetry semantic conventions SHOULD be part + of a namespace. + +- When a new namespace is necessary consider whether it should be a top-level + namespace (e.g. `service`) or a nested namespace (e.g. `service.instance`). + +- Semantic conventions MUST limit names to printable Basic Latin characters + (more precisely to + [U+0021 .. U+007E]() + subset of Unicode code points). It is recommended to further limit names to + the following Unicode code points: Latin alphabet, Numeric, Underscore, Dot + (as namespace delimiter). + +> Note: +> Semantic Conventions tooling limits names to lowercase +> Latin alphabet, Numeric, Underscore, Dot (as namespace delimiter). +> Names must start with a letter, end with an alphanumeric character, and must not +> contain two or more consecutive delimiters (Underscore or Dot). + +## Recommendations for Application Developers + +As an application developer when you need to record an attribute, metric, event, or +other signal first consult existing [semantic conventions](./README.md). +If an appropriate name does not exists you will need to come up with a new name. +To do that consider a few options: + +- The name is specific to your company and may be possibly used outside the + company as well. To avoid clashes with names introduced by other companies (in + a distributed system that uses applications from multiple vendors) it is + recommended to prefix the new name by your company's reverse domain name, e.g. + `com.acme.shopname`. + +- The name is specific to your application that will be used internally only. If + you already have an internal company process that helps you to ensure no name + clashes happen then feel free to follow it. Otherwise it is recommended to + prefix the attribute name by your application name, provided that the + application name is reasonably unique within your organization (e.g. + `myuniquemapapp.longitude` is likely fine). Make sure the application name + does not clash with an existing semantic convention namespace. + +- It is not recommended to use existing OpenTelemetry semantic convention + namespace as a prefix for a new company- or application-specific attribute + name. Doing so may result in a name clash in the future, if OpenTelemetry + decides to use that same name for a different purpose or if some other third + party instrumentation decides to use that exact same attribute name and you + combine that instrumentation with your own. + +- The name may be generally applicable to applications in the industry. In that + case consider submitting a proposal to this specification to add a new name to + the semantic conventions, and if necessary also to add a new namespace. + +It is recommended to limit names to printable Basic Latin characters (more +precisely to +[U+0021 .. U+007E]() +subset of Unicode code points). + +## Attributes + +### otel.\* Namespace + +Attribute names that start with `otel.` are reserved to be defined by +OpenTelemetry specification. These are typically used to express OpenTelemetry +concepts in formats that don't have a corresponding concept. + +For example, the `otel.scope.name` attribute is used to record the +instrumentation scope name, which is an OpenTelemetry concept that is natively +represented in OTLP, but does not have an equivalent in other telemetry formats +and protocols. + +Any additions to the `otel.*` namespace MUST be approved as part of +OpenTelemetry specification. + +### Attribute Name Pluralization Guidelines + +- When an attribute represents a single entity, the attribute name SHOULD be + singular. Examples: `host.name`, `container.id`. + +- When attribute can represent multiple entities, the attribute name SHOULD be + pluralized and the value type SHOULD be an array. E.g. `process.command_args` + might include multiple values: the executable name and command arguments. + +- When an attribute represents a measurement, + [Metric Name Pluralization Guidelines](./metrics.md#pluralization) SHOULD be + followed for the attribute name. + +### Signal-specific Attributes + +**Status**: [Experimental][DocumentStatus] + +Attributes are defined in semantic conventions in a signal-agnostic way. The same attribute +is expected to be used on multiple signals. + +When an attribute is defined, it is not always clear if it will be applicable outside +of a certain metric, event, or other convention. + +Attributes that are unlikely to have any usage beyond a specific convention, +SHOULD be added under that metric (event, etc) namespace. + +Examples: + +Attributes `mode` and `mountpoint` for metric `system.filesystem.usage` +should be namespaced as `system.filesystem.mode` and `system.filesystem.mountpoint`. + +Metrics, events, resources, and other signals are expected and encouraged to use +applicable attributes from multiple namespaces. + +Examples: + +Metric `http.server.request.duration` uses attributes from the registry such as +`server.port`, `error.type`. + +## Metrics + +**Status**: [Experimental][DocumentStatus] + +### Naming Rules for Counters and UpDownCounters + +#### Pluralization + +Metric namespaces SHOULD NOT be pluralized. + +Metric names SHOULD NOT be pluralized, unless the value being recorded +represents discrete instances of a +[countable quantity](https://wikipedia.org/wiki/Count_noun). +Generally, the name SHOULD be pluralized only if the unit of the metric in +question is a non-unit (like `{fault}` or `{operation}`). + +Examples: + +* `system.filesystem.utilization`, `http.server.request.duration`, and `system.cpu.time` +should not be pluralized, even if many data points are recorded. +* `system.paging.faults`, `system.disk.operations`, and `system.network.packets` +should be pluralized, even if only a single data point is recorded. + +#### Use `count` Instead of Pluralization for UpDownCounters + +If the value being recorded represents the count of concepts signified +by the namespace then the metric should be named `count` (within its namespace). + +For example if we have a namespace `system.process` which contains all metrics related +to the processes then to represent the count of the processes we can have a metric named +`system.process.count`. + +#### Do Not Use `total` + +UpDownCounters SHOULD NOT use `_total` because then they will look like +monotonic sums. + +Counters SHOULD NOT append `_total` either because then their meaning will +be confusing in delta backends. + +### Instrument Naming + +**Status**: [Experimental][DocumentStatus] + +- **limit** - an instrument that measures the constant, known total amount of +something should be called `entity.limit`. For example, `system.memory.limit` +for the total amount of memory on a system. + +- **usage** - an instrument that measures an amount used out of a known total +(**limit**) amount should be called `entity.usage`. For example, +`system.memory.usage` with attribute `state = used | cached | free | ...` for the +amount of memory in a each state. Where appropriate, the sum of **usage** +over all attribute values SHOULD be equal to the **limit**. + + A measure of the amount consumed of an unlimited resource, or of a resource + whose limit is unknowable, is differentiated from **usage**. For example, the + maximum possible amount of virtual memory that a process may consume may + fluctuate over time and is not typically known. + +- **utilization** - an instrument that measures the _fraction_ of **usage** +out of its **limit** should be called `entity.utilization`. For example, +`system.memory.utilization` for the fraction of memory in use. Utilization can +be with respect to a fixed limit or a soft limit. Utilization values are +represented as a ratio and are typically in the range `[0, 1]`, but may go above 1 +in case of exceeding a soft limit. + +- **time** - an instrument that measures passage of time should be called +`entity.time`. For example, `system.cpu.time` with attribute `state = idle | user +| system | ...`. **time** measurements are not necessarily wall time and can +be less than or greater than the real wall time between measurements. + + **time** instruments are a special case of **usage** metrics, where the + **limit** can usually be calculated as the sum of **time** over all attribute + values. **utilization** for time instruments can be derived automatically + using metric event timestamps. For example, `system.cpu.utilization` is + defined as the difference in `system.cpu.time` measurements divided by the + elapsed time and number of CPUs. + +- **io** - an instrument that measures bidirectional data flow should be +called `entity.io` and have attributes for direction. For example, +`system.network.io`. + +- Other instruments that do not fit the above descriptions may be named more +freely. For example, `system.paging.faults` and `system.network.packets`. +Units do not need to be specified in the names since they are included during +instrument creation, but can be added if there is ambiguity. + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/system/README.md b/docs/system/README.md index dc6b643b5d..61c332a22b 100644 --- a/docs/system/README.md +++ b/docs/system/README.md @@ -14,6 +14,8 @@ This document defines semantic conventions for systems (such as processes, runti System semantic conventions are defined for the following metrics: * [System](system-metrics.md): For standard system metrics. +* [Container](container-metrics.md): For container-related metrics. +* [K8s](k8s-metrics.md): For K8s-related metrics. * [Hardware](hardware-metrics.md): For hardware-related metrics. * [Process](process-metrics.md): For standard process metrics. * [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics. diff --git a/model/README.md b/model/README.md index ce6fb75e93..821423416e 100644 --- a/model/README.md +++ b/model/README.md @@ -10,7 +10,7 @@ the generated markdown output in the [docs](../docs/README.md) folder. ## Writing semantic conventions Semantic conventions for the spec MUST adhere to the -[attribute naming](../docs/general/attribute-naming.md), +[naming](../docs/general/naming.md), [attribute requirement level](../docs/general/attribute-requirement-level.md), and [metric requirement level](../docs/general/metric-requirement-level.md) conventions. diff --git a/templates/registry/markdown/readme.md.j2 b/templates/registry/markdown/readme.md.j2 index 14438da535..1767f38b2e 100644 --- a/templates/registry/markdown/readme.md.j2 +++ b/templates/registry/markdown/readme.md.j2 @@ -36,5 +36,5 @@ Currently, the following namespaces exist: {%- set my_file_name = bundle.id | kebab_case ~ ".md" -%} - [{{ bundle.id | title_case | acronym }}]({{ my_file_name }}) {% endfor %} -[developers recommendations]: ../general/attribute-naming.md#recommendations-for-application-developers +[developers recommendations]: ../general/naming.md#recommendations-for-application-developers From 3d4013dbf25fddcd774dc4ce6ed8a2da6fdd9e71 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gerhard=20St=C3=B6bich?= Date: Thu, 19 Dec 2024 17:19:17 +0100 Subject: [PATCH 2/6] [chore] Add x-amzn-requestid as source for aws.request_id (#1691) --- docs/attributes-registry/aws.md | 2 +- docs/cloud-providers/aws-sdk.md | 2 +- docs/database/dynamodb.md | 26 +++++++++++++------------- docs/object-stores/s3.md | 2 +- model/aws/registry.yaml | 2 +- 5 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/attributes-registry/aws.md b/docs/attributes-registry/aws.md index ed5fdca4e2..5ccb0e33b6 100644 --- a/docs/attributes-registry/aws.md +++ b/docs/attributes-registry/aws.md @@ -21,7 +21,7 @@ This document defines generic attributes for AWS services. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| | `aws.extended_request_id` | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `aws.request_id` | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `aws.request_id` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## Amazon DynamoDB Attributes diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index 498f6c77a0..2d2114c3b3 100644 --- a/docs/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -35,7 +35,7 @@ with the naming guidelines for RPC client spans. |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/dynamodb.md b/docs/database/dynamodb.md index e5547f9338..fb11c89316 100644 --- a/docs/database/dynamodb.md +++ b/docs/database/dynamodb.md @@ -26,7 +26,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `["{ \"CapacityUnits\": number, \"GlobalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"LocalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"ReadCapacityUnits\": number, \"Table\": { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number }, \"TableName\": \"string\", \"WriteCapacityUnits\": number }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | The keys in the `RequestItems` object field. | `["Users", "Cats"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -67,7 +67,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `["{ \"CapacityUnits\": number, \"GlobalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"LocalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"ReadCapacityUnits\": number, \"Table\": { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number }, \"TableName\": \"string\", \"WriteCapacityUnits\": number }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.item_collection_metrics`](/docs/attributes-registry/aws.md) | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | The keys in the `RequestItems` object field. | `["Users", "Cats"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -112,7 +112,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | [`aws.dynamodb.provisioned_read_capacity`](/docs/attributes-registry/aws.md) | double | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. | `1.0`; `2.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.provisioned_write_capacity`](/docs/attributes-registry/aws.md) | double | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. | `1.0`; `2.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -153,7 +153,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `["{ \"CapacityUnits\": number, \"GlobalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"LocalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"ReadCapacityUnits\": number, \"Table\": { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number }, \"TableName\": \"string\", \"WriteCapacityUnits\": number }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.item_collection_metrics`](/docs/attributes-registry/aws.md) | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -192,7 +192,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -231,7 +231,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -273,7 +273,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `["{ \"CapacityUnits\": number, \"GlobalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"LocalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"ReadCapacityUnits\": number, \"Table\": { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number }, \"TableName\": \"string\", \"WriteCapacityUnits\": number }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.projection`](/docs/attributes-registry/aws.md) | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -314,7 +314,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | [`aws.dynamodb.exclusive_start_table`](/docs/attributes-registry/aws.md) | string | The value of the `ExclusiveStartTableName` request parameter. | `Users`; `CatsTable` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.limit`](/docs/attributes-registry/aws.md) | int | The value of the `Limit` request parameter. | `10` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_count`](/docs/attributes-registry/aws.md) | int | The number of items in the `TableNames` response parameter. | `20` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -355,7 +355,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `["{ \"CapacityUnits\": number, \"GlobalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"LocalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"ReadCapacityUnits\": number, \"Table\": { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number }, \"TableName\": \"string\", \"WriteCapacityUnits\": number }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.item_collection_metrics`](/docs/attributes-registry/aws.md) | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | The keys in the `RequestItems` object field. | `["Users", "Cats"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -402,7 +402,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | [`aws.dynamodb.scan_forward`](/docs/attributes-registry/aws.md) | boolean | The value of the `ScanIndexForward` request parameter. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.select`](/docs/attributes-registry/aws.md) | string | The value of the `Select` request parameter. | `ALL_ATTRIBUTES`; `COUNT` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -452,7 +452,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | [`aws.dynamodb.select`](/docs/attributes-registry/aws.md) | string | The value of the `Select` request parameter. | `ALL_ATTRIBUTES`; `COUNT` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.total_segments`](/docs/attributes-registry/aws.md) | int | The value of the `TotalSegments` request parameter. | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -493,7 +493,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `["{ \"CapacityUnits\": number, \"GlobalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"LocalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"ReadCapacityUnits\": number, \"Table\": { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number }, \"TableName\": \"string\", \"WriteCapacityUnits\": number }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.item_collection_metrics`](/docs/attributes-registry/aws.md) | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -537,7 +537,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | [`aws.dynamodb.provisioned_read_capacity`](/docs/attributes-registry/aws.md) | double | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. | `1.0`; `2.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.provisioned_write_capacity`](/docs/attributes-registry/aws.md) | double | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. | `1.0`; `2.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/object-stores/s3.md b/docs/object-stores/s3.md index 9624771191..2de5d4a3d6 100644 --- a/docs/object-stores/s3.md +++ b/docs/object-stores/s3.md @@ -22,7 +22,7 @@ described on this page. |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.s3.bucket`](/docs/attributes-registry/aws.md) | string | The S3 bucket name the request refers to. Corresponds to the `--bucket` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [1] | `some-bucket-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.s3.copy_source`](/docs/attributes-registry/aws.md) | string | The source object (in the form `bucket`/`key`) for the copy operation. [2] | `someFile.yml` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.s3.delete`](/docs/attributes-registry/aws.md) | string | The delete request container that specifies the objects to be deleted. [3] | `Objects=[{Key=string,VersionId=string},{Key=string,VersionId=string}],Quiet=boolean` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/aws/registry.yaml b/model/aws/registry.yaml index 4c8a39ae7b..092ef48d9b 100644 --- a/model/aws/registry.yaml +++ b/model/aws/registry.yaml @@ -8,7 +8,7 @@ groups: - id: aws.request_id type: string stability: experimental - brief: "The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`." + brief: "The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`." examples: - 79b9da39-b7ae-508a-a6bc-864b2829c622 - C9ER4AJX75574TDJ From 5a5803258f04292540676384be293bc4c57f5ceb Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 20 Dec 2024 00:14:54 -0800 Subject: [PATCH 3/6] Improve rendering of database release candidate status (#1702) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- docs/attributes-registry/db.md | 37 +++++--------- docs/database/cassandra.md | 26 +++------- docs/database/cosmosdb.md | 34 +++++-------- docs/database/couchdb.md | 10 ++-- docs/database/database-metrics.md | 64 +++++++++--------------- docs/database/database-spans.md | 37 +++++--------- docs/database/elasticsearch.md | 15 +++--- docs/database/hbase.md | 15 ++---- docs/database/mariadb.md | 16 +++--- docs/database/mongodb.md | 14 ++---- docs/database/mssql.md | 16 +++--- docs/database/mysql.md | 16 +++--- docs/database/postgresql.md | 16 +++--- docs/database/redis.md | 17 +++---- docs/database/sql.md | 16 +++--- model/database/metrics.yaml | 2 +- model/database/registry.yaml | 44 +++++----------- templates/registry/markdown/stability.j2 | 1 + 18 files changed, 140 insertions(+), 256 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 381ead2fda..c50e8f0112 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -21,16 +21,16 @@ This group defines the attributes used to describe telemetry in the context of d |---|---|---|---|---| | `db.client.connection.pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, instrumentation SHOULD use a combination of parameters that would make the name unique, for example, combining attributes `server.address`, `server.port`, and `db.namespace`, formatted as `server.address:server.port/db.namespace`. Instrumentations that generate connection pool name following different patterns SHOULD document it. | `myDataSource` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `db.client.connection.state` | string | The state of a connection in the pool | `idle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.collection.name` | string | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.namespace` | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.operation.batch.size` | int | The number of queries included in a batch operation. [3] | `2`; `3`; `4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.operation.name` | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.operation.parameter.` | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [5] | `someval`; `55` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.query.summary` | string | Low cardinality representation of a database query text. [6] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.query.text` | string | The database query being executed. [7] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.collection.name` | string | The name of a collection (table, container) within the database. [1] | `public.users`; `customers` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `db.namespace` | string | The name of the database, fully qualified within the server address and port. [2] | `customers`; `test.users` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `db.operation.batch.size` | int | The number of queries included in a batch operation. [3] | `2`; `3`; `4` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `db.operation.name` | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `db.operation.parameter.` | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [5] | `someval`; `55` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `db.query.summary` | string | Low cardinality representation of a database query text. [6] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `db.query.text` | string | The database query being executed. [7] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `db.response.returned_rows` | int | Number of rows returned by the operation. | `10`; `30`; `1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.response.status_code` | string | Database response status code. [8] | `102`; `ORA-17002`; `08P01`; `404` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `db.system` | string | The database management system (DBMS) product as identified by the client instrumentation. [9] | `other_sql`; `adabas`; `cache` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.response.status_code` | string | Database response status code. [8] | `102`; `ORA-17002`; `08P01`; `404` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `db.system` | string | The database management system (DBMS) product as identified by the client instrumentation. [9] | `other_sql`; `adabas`; `cache` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | **[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -40,15 +40,11 @@ unless the query format is known to only ever have a single collection name pres For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used. -This attribute has stability level RELEASE CANDIDATE. - **[2] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid. Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -This attribute has stability level RELEASE CANDIDATE. **[3] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[4] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -61,27 +57,20 @@ then that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. -This attribute has stability level RELEASE CANDIDATE. - **[5] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. -This attribute has stability level RELEASE CANDIDATE. **[6] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. -This attribute has stability level RELEASE CANDIDATE. **[7] `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. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -This attribute has stability level RELEASE CANDIDATE. **[8] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. -This attribute has stability level RELEASE CANDIDATE. **[9] `db.system`:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge. -This attribute has stability level RELEASE CANDIDATE. --- @@ -128,13 +117,13 @@ This attribute has stability level RELEASE CANDIDATE. | `instantdb` | InstantDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `interbase` | InterBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `intersystems_cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mariadb` | MariaDB (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mariadb` | MariaDB (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mssql` | Microsoft SQL Server (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mssql` | Microsoft SQL Server (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `mssqlcompact` | Deprecated, Microsoft SQL Server Compact is discontinued. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed, use `other_sql` instead. | -| `mysql` | MySQL (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mysql` | MySQL (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `netezza` | Netezza | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `opensearch` | OpenSearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -142,7 +131,7 @@ This attribute has stability level RELEASE CANDIDATE. | `other_sql` | Some other SQL database. Fallback only. See notes. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `pervasive` | Pervasive PSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `pointbase` | PointBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `postgresql` | PostgreSQL (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `postgresql` | PostgreSQL (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `progress` | Progress Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `redis` | Redis | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `redshift` | Amazon Redshift | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index 270a90c2aa..7ec690b232 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -21,10 +21,10 @@ The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend a | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of the Cassandra table that the operation is acting upon. [1] | `public.users`; `customers` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The keyspace associated with the session. [3] | `mykeyspace` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [Cassandra protocol error code](https://github.com/apache/cassandra/blob/cassandra-5.0/doc/native_protocol_v5.spec) represented as a string. [6] | `102`; `40020` | `Conditionally Required` [7] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of the Cassandra table that the operation is acting upon. [1] | `public.users`; `customers` | `Conditionally Required` [2] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The keyspace associated with the session. [3] | `mykeyspace` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [5] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [Cassandra protocol error code](https://github.com/apache/cassandra/blob/cassandra-5.0/doc/native_protocol_v5.spec) represented as a string. [6] | `102`; `40020` | `Conditionally Required` [7] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [8] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [9] | `80`; `8080`; `443` | `Conditionally Required` [10] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.cassandra.consistency_level`](/docs/attributes-registry/db.md) | string | The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). | `all`; `each_quorum`; `quorum` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -33,14 +33,14 @@ The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend a | [`db.cassandra.idempotence`](/docs/attributes-registry/db.md) | boolean | Whether or not the query is idempotent. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cassandra.page_size`](/docs/attributes-registry/db.md) | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cassandra.speculative_execution_count`](/docs/attributes-registry/db.md) | int | The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. | `0`; `2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [11] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [12] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [13] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [14] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [15] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [11] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [12] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [13] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [14] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [15] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [16] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [17] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [18] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [18] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | **[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -50,14 +50,11 @@ unless the query format is known to only ever have a single collection name pres For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used. -This attribute has stability level RELEASE CANDIDATE. - **[2] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query. **[3] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid. Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -This attribute has stability level RELEASE CANDIDATE. **[4] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -70,13 +67,10 @@ then that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. -This attribute has stability level RELEASE CANDIDATE. - **[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query. **[6] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. -This attribute has stability level RELEASE CANDIDATE. **[7] `db.response.status_code`:** If the operation failed and status code is available. @@ -89,18 +83,15 @@ Instrumentations SHOULD document how `error.type` is populated. **[10] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. **[11] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[12] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. -This attribute has stability level RELEASE CANDIDATE. **[13] `db.query.summary`:** if readily available or if instrumentation supports query summarization. **[14] `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. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -This attribute has stability level RELEASE CANDIDATE. **[15] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes 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 SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). @@ -111,7 +102,6 @@ Parameterized query text SHOULD be collected by default (the query parameter val **[18] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. -This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index f32d64d57d..810967a907 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -39,27 +39,27 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | Cosmos DB container name. [1] | `public.users`; `customers` | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | Cosmos DB container name. [1] | `public.users`; `customers` | `Conditionally Required` if available | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.cosmosdb.connection_mode`](/docs/attributes-registry/db.md) | string | Cosmos client connection mode. | `gateway`; `direct` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.consistency_level`](/docs/attributes-registry/db.md) | string | Account or request [consistency level](https://learn.microsoft.com/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong`; `Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.regions_contacted`](/docs/attributes-registry/db.md) | string[] | List of regions contacted during operation in the order that they were contacted. If there is more than one region listed, it indicates that the operation was performed on multiple regions i.e. cross-regional call. [3] | `["North Central US", "Australia East", "Australia Southeast"]` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.request_charge`](/docs/attributes-registry/db.md) | double | Request units consumed for the operation. | `46.18`; `1.0` | `Conditionally Required` when available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` when response was received and contained sub-code. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `create_item`; `query_items`; `read_item` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [4] | `create_item`; `query_items`; `read_item` | `Conditionally Required` [5] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Cosmos DB row count in result set. | `10`; `20` | `Conditionally Required` if response was received and returned any rows | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Cosmos DB status code. [6] | `200`; `201` | `Conditionally Required` if response was received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Cosmos DB status code. [6] | `200`; `201` | `Conditionally Required` if response was received | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [7] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [8] | `80`; `8080`; `443` | `Conditionally Required` If not default (443). | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`az.namespace`](/docs/attributes-registry/azure.md) | string | [Azure Resource Provider Namespace](https://learn.microsoft.com/azure/azure-resource-manager/management/azure-services-resource-providers) as recognized by the client. [9] | `Microsoft.DocumentDB` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.client_id`](/docs/attributes-registry/db.md) | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.request_content_length`](/docs/attributes-registry/db.md) | int | Request payload size in bytes. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [10] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [10] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [11] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [12] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [13] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [14] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`user_agent.original`](/docs/attributes-registry/user-agent.md) | string | Full user-agent string is generated by Cosmos DB SDK [16] | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [17] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [17] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | **[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -195,7 +195,6 @@ additional values when introducing new operations. **[6] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. -This attribute has stability level RELEASE CANDIDATE. **[7] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. @@ -206,18 +205,15 @@ Instrumentations SHOULD document how `error.type` is populated. **[9] `az.namespace`:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.DocumentDB` for all operations performed by Cosmos DB client. **[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. -This attribute has stability level RELEASE CANDIDATE. **[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization. **[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. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -This attribute has stability level RELEASE CANDIDATE. **[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes 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 SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). @@ -230,7 +226,6 @@ Parameterized query text SHOULD be collected by default (the query parameter val **[17] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. -This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): @@ -345,12 +340,12 @@ Explaining bucket configuration: | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | Cosmos DB container name. [1] | `public.users`; `customers` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | Cosmos DB container name. [1] | `public.users`; `customers` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.cosmosdb.consistency_level`](/docs/attributes-registry/db.md) | string | Account or request [consistency level](https://learn.microsoft.com/azure/cosmos-db/consistency-levels). | `Eventual`; `ConsistentPrefix`; `BoundedStaleness`; `Strong`; `Session` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`db.cosmosdb.sub_status_code`](/docs/attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | `Conditionally Required` when response was received and contained sub-code. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [4] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [4] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [5] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [6] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Conditionally Required` [8] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.cosmosdb.regions_contacted`](/docs/attributes-registry/db.md) | string[] | List of regions contacted during operation in the order that they were contacted. If there is more than one region listed, it indicates that the operation was performed on multiple regions i.e. cross-regional call. [9] | `["North Central US", "Australia East", "Australia Southeast"]` | `Recommended` If available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -364,8 +359,6 @@ unless the query format is known to only ever have a single collection name pres For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used. -This attribute has stability level RELEASE CANDIDATE. - **[2] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -377,13 +370,10 @@ then that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. -This attribute has stability level RELEASE CANDIDATE. - **[3] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query. **[4] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. -This attribute has stability level RELEASE CANDIDATE. **[5] `db.response.status_code`:** If the operation failed and status code is available. diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index c95784e085..b4eb826f75 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -21,19 +21,18 @@ The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and o | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The HTTP method + the target REST route. [1] | `GET /{db}/{docid}` | `Conditionally Required` If readily available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | The HTTP response code returned by the Couch DB. [2] | `200`; `201`; `429` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The HTTP method + the target REST route. [1] | `GET /{db}/{docid}` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | The HTTP response code returned by the Couch DB. [2] | `200`; `201`; `429` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [4] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [5] | `80`; `8080`; `443` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [7] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [7] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `db.operation.name`:** In **CouchDB**, `db.operation.name` should be set to the HTTP method + the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation.name` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`](https://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). **[2] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. -This attribute has stability level RELEASE CANDIDATE. **[3] `db.response.status_code`:** If response was received and the HTTP response code is available. @@ -46,7 +45,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[6] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. **[7] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[8] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 30af7d9790..de86f04111 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -77,27 +77,26 @@ of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `db.client.operation.duration` | Histogram | `s` | Duration of database client operations. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `db.client.operation.duration` | Histogram | `s` | Duration of database client operations. [1] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | **[1]:** Batch operations SHOULD be recorded as a single operation. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `adabas`; `cache` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [2] | `public.users`; `customers` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [4] | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [5] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [7] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `adabas`; `cache` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [2] | `public.users`; `customers` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [4] | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [5] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [6] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [7] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [8] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [9] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Conditionally Required` [11] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [12] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [13] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [12] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [13] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [14] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this database system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` If and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [16] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [16] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | **[1] `db.system`:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge. -This attribute has stability level RELEASE CANDIDATE. **[2] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -107,14 +106,11 @@ unless the query format is known to only ever have a single collection name pres For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used. -This attribute has stability level RELEASE CANDIDATE. - **[3] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query. **[4] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid. Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -This attribute has stability level RELEASE CANDIDATE. **[5] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -127,13 +123,10 @@ then that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. -This attribute has stability level RELEASE CANDIDATE. - **[6] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query. **[7] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. -This attribute has stability level RELEASE CANDIDATE. **[8] `db.response.status_code`:** If the operation failed and status code is available. @@ -147,7 +140,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[12] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. -This attribute has stability level RELEASE CANDIDATE. **[13] `db.query.summary`:** if readily available or if instrumentation supports query summarization. @@ -159,7 +151,6 @@ If a database operation involved multiple network calls (for example retries), t **[16] `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. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -This attribute has stability level RELEASE CANDIDATE. --- @@ -193,12 +184,12 @@ This attribute has stability level RELEASE CANDIDATE. | `instantdb` | InstantDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `interbase` | InterBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `intersystems_cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mariadb` | MariaDB (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mariadb` | MariaDB (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mssql` | Microsoft SQL Server (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mysql` | MySQL (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mssql` | Microsoft SQL Server (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `mysql` | MySQL (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `netezza` | Netezza | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `opensearch` | OpenSearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -206,7 +197,7 @@ This attribute has stability level RELEASE CANDIDATE. | `other_sql` | Some other SQL database. Fallback only. See notes. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `pervasive` | Pervasive PSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `pointbase` | PointBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `postgresql` | PostgreSQL (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `postgresql` | PostgreSQL (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `progress` | Progress Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `redis` | Redis | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `redshift` | Amazon Redshift | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -264,21 +255,20 @@ Explaining bucket configuration: | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `adabas`; `cache` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [2] | `public.users`; `customers` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [4] | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [5] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [7] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `adabas`; `cache` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [2] | `public.users`; `customers` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [4] | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [5] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [6] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [7] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [8] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [9] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Conditionally Required` [11] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [12] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [13] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [12] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [13] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [14] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this database system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` If and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [16] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [16] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | **[1] `db.system`:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge. -This attribute has stability level RELEASE CANDIDATE. **[2] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -288,14 +278,11 @@ unless the query format is known to only ever have a single collection name pres For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used. -This attribute has stability level RELEASE CANDIDATE. - **[3] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query. **[4] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid. Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -This attribute has stability level RELEASE CANDIDATE. **[5] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -308,13 +295,10 @@ then that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. -This attribute has stability level RELEASE CANDIDATE. - **[6] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query. **[7] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. -This attribute has stability level RELEASE CANDIDATE. **[8] `db.response.status_code`:** If the operation failed and status code is available. @@ -328,7 +312,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[12] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. -This attribute has stability level RELEASE CANDIDATE. **[13] `db.query.summary`:** if readily available or if instrumentation supports query summarization. @@ -340,7 +323,6 @@ If a database operation involved multiple network calls (for example retries), t **[16] `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. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -This attribute has stability level RELEASE CANDIDATE. --- @@ -374,12 +356,12 @@ This attribute has stability level RELEASE CANDIDATE. | `instantdb` | InstantDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `interbase` | InterBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `intersystems_cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mariadb` | MariaDB (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mariadb` | MariaDB (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mssql` | Microsoft SQL Server (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mysql` | MySQL (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mssql` | Microsoft SQL Server (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `mysql` | MySQL (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `netezza` | Netezza | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `opensearch` | OpenSearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -387,7 +369,7 @@ This attribute has stability level RELEASE CANDIDATE. | `other_sql` | Some other SQL database. Fallback only. See notes. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `pervasive` | Pervasive PSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `pointbase` | PointBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `postgresql` | PostgreSQL (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `postgresql` | PostgreSQL (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `progress` | Progress Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `redis` | Redis | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `redshift` | Amazon Redshift | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index aa354baa1b..ac7f2c1931 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -156,24 +156,23 @@ These attributes will usually be the same for all operations performed over the | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `adabas`; `cache` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [2] | `public.users`; `customers` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [4] | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [5] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [7] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.system`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `adabas`; `cache` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of a collection (table, container) within the database. [2] | `public.users`; `customers` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. [4] | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [5] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [6] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response status code. [7] | `102`; `ORA-17002`; `08P01`; `404` | `Conditionally Required` [8] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [9] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Conditionally Required` [11] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [12] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [13] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [14] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [15] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [16] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [12] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [13] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [14] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [15] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [16] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [17] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this database system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [18] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [19] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [19] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | **[1] `db.system`:** The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge. -This attribute has stability level RELEASE CANDIDATE. **[2] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -183,14 +182,11 @@ unless the query format is known to only ever have a single collection name pres For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used. -This attribute has stability level RELEASE CANDIDATE. - **[3] `db.collection.name`:** If readily available and if a database call is performed on a single collection. The collection name MAY be parsed from the query text, in which case it SHOULD be the single collection name in the query. **[4] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid. Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -This attribute has stability level RELEASE CANDIDATE. **[5] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -203,13 +199,10 @@ then that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. -This attribute has stability level RELEASE CANDIDATE. - **[6] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query. **[7] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. -This attribute has stability level RELEASE CANDIDATE. **[8] `db.response.status_code`:** If the operation failed and status code is available. @@ -222,18 +215,15 @@ Instrumentations SHOULD document how `error.type` is populated. **[11] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. **[12] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[13] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. -This attribute has stability level RELEASE CANDIDATE. **[14] `db.query.summary`:** if readily available or if instrumentation supports query summarization. **[15] `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. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -This attribute has stability level RELEASE CANDIDATE. **[16] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes 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 SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). @@ -245,7 +235,6 @@ If a database operation involved multiple network calls (for example retries), t **[19] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. -This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): @@ -291,12 +280,12 @@ and SHOULD be provided **at span creation time** (if provided at all): | `instantdb` | InstantDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `interbase` | InterBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `intersystems_cache` | InterSystems Caché | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mariadb` | MariaDB (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mariadb` | MariaDB (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `maxdb` | SAP MaxDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mssql` | Microsoft SQL Server (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `mysql` | MySQL (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `mssql` | Microsoft SQL Server (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `mysql` | MySQL (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `netezza` | Netezza | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `opensearch` | OpenSearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -304,7 +293,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | `other_sql` | Some other SQL database. Fallback only. See notes. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `pervasive` | Pervasive PSQL | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `pointbase` | PointBase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `postgresql` | PostgreSQL (This value has stability level RELEASE CANDIDATE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `postgresql` | PostgreSQL (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `progress` | Progress Database | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `redis` | Redis | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `redshift` | Amazon Redshift | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 191397bec8..175cf43fab 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -25,18 +25,18 @@ The **span name** follows the [general database span name guidelines](database-s | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `search`; `ml.close_job`; `cat.aliases` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `search`; `ml.close_job`; `cat.aliases` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`url.full`](/docs/attributes-registry/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [3] | `https://localhost:9200/index/_search?q=user.id:kimchy` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.elasticsearch.path_parts.`](/docs/attributes-registry/db.md) | string | A dynamic value in the url path. [4] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | `Conditionally Required` when the url has dynamic values | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | The HTTP response code returned by the Elasticsearch cluster. [5] | `200`; `201`; `429` | `Conditionally Required` If response was received. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | The HTTP response code returned by the Elasticsearch cluster. [5] | `200`; `201`; `429` | `Conditionally Required` If response was received. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [6] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Conditionally Required` [8] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The index or data stream against which the query is executed. [9] | `my_index`; `index1, index2` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The index or data stream against which the query is executed. [9] | `my_index`; `index1, index2` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.elasticsearch.node.name`](/docs/attributes-registry/db.md) | string | Represents the human-readable identifier of the node/instance to which a request was routed. [10] | `instance-0000000001` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the Elasticsearch cluster which the client connects to. [11] | `customers`; `test.users` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [12] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. [13] | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | `Recommended` [14] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the Elasticsearch cluster which the client connects to. [11] | `customers`; `test.users` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [12] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. [13] | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | `Recommended` [14] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [15] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `db.operation.name`:** The `db.operation.name` SHOULD match the endpoint identifier provided in the request (see the [Elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json)). @@ -84,7 +84,6 @@ When a query string value is redacted, the query string key SHOULD still be pres **[5] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. -This attribute has stability level RELEASE CANDIDATE. **[6] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. @@ -101,12 +100,10 @@ Instrumentations SHOULD document how `error.type` is populated. **[11] `db.namespace`:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. **[12] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[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. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -This attribute has stability level RELEASE CANDIDATE. **[14] `db.query.text`:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information. diff --git a/docs/database/hbase.md b/docs/database/hbase.md index ad7c89aaed..6e8e2b03b9 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -21,13 +21,13 @@ The Semantic Conventions for [HBase](https://hbase.apache.org/) extend and overr | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The HBase table name. [1] | `mytable`; `ns:table` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The HBase namespace. [2] | `mynamespace` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [3] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` If readily available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Protocol-specific response code recorded as string. [4] | `200`; `409`; `14` | `Conditionally Required` If response was received. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The HBase table name. [1] | `mytable`; `ns:table` | `Conditionally Required` If applicable. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The HBase namespace. [2] | `mynamespace` | `Conditionally Required` If applicable. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [3] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Protocol-specific response code recorded as string. [4] | `200`; `409`; `14` | `Conditionally Required` If response was received. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [5] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [8] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [8] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `db.collection.name`:** If table name includes the namespace, the `db.collection.name` SHOULD be set to the full table name. @@ -35,7 +35,6 @@ The Semantic Conventions for [HBase](https://hbase.apache.org/) extend and overr **[2] `db.namespace`:** If a database system has multiple namespace components, they SHOULD be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces SHOULD NOT be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid. Semantic conventions for individual database systems SHOULD document what `db.namespace` means in the context of that system. It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -This attribute has stability level RELEASE CANDIDATE. **[3] `db.operation.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -48,11 +47,8 @@ then that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. -This attribute has stability level RELEASE CANDIDATE. - **[4] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. -This attribute has stability level RELEASE CANDIDATE. **[5] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. @@ -63,7 +59,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[7] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. **[8] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[9] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md index aff44fdfb9..58285321b5 100644 --- a/docs/database/mariadb.md +++ b/docs/database/mariadb.md @@ -21,16 +21,16 @@ The Semantic Conventions for *MariaDB* extend and override the [Database Semanti | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection. [1] | `products`; `customers` | `Conditionally Required` If available without an additional network call. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [Maria DB error code](https://mariadb.com/kb/en/mariadb-error-code-reference/) represented as a string. [2] | `1008`; `3058` | `Conditionally Required` If response has ended with warning or an error. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection. [1] | `products`; `customers` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [Maria DB error code](https://mariadb.com/kb/en/mariadb-error-code-reference/) represented as a string. [2] | `1008`; `3058` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [8] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [10] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | **[1] `db.namespace`:** A connection's currently associated database may change during its lifetime, e.g. from executing `USE `. @@ -87,18 +87,15 @@ Instrumentations SHOULD document how `error.type` is populated. **[5] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. **[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. -This attribute has stability level RELEASE CANDIDATE. **[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization. **[9] `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. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -This attribute has stability level RELEASE CANDIDATE. **[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes 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 SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). @@ -107,7 +104,6 @@ Parameterized query text SHOULD be collected by default (the query parameter val **[12] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. -This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index 842ae973e7..26f33c9afb 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -21,13 +21,13 @@ The Semantic Conventions for [MongoDB](https://www.mongodb.com/) extend and over | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The MongoDB collection being accessed within the database stated in `db.namespace`. [1] | `public.users`; `customers` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The MongoDB database name. | `customers`; `test.users` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the command being executed. [2] | `findAndModify`; `getMore`; `update` | `Conditionally Required` If readily available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [MongoDB error code](https://www.mongodb.com/docs/manual/reference/error-codes/) represented as a string. [3] | `36`; `11602` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The MongoDB collection being accessed within the database stated in `db.namespace`. [1] | `public.users`; `customers` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The MongoDB database name. | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the command being executed. [2] | `findAndModify`; `getMore`; `update` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [MongoDB error code](https://www.mongodb.com/docs/manual/reference/error-codes/) represented as a string. [3] | `36`; `11602` | `Conditionally Required` [4] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [5] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [8] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [8] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `db.collection.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -38,13 +38,10 @@ unless the query format is known to only ever have a single collection name pres For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used. -This attribute has stability level RELEASE CANDIDATE. - **[2] `db.operation.name`:** See [MongoDB database commands](https://www.mongodb.com/docs/manual/reference/command/). **[3] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. -This attribute has stability level RELEASE CANDIDATE. **[4] `db.response.status_code`:** If the operation failed and error code is available. @@ -57,7 +54,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[7] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. **[8] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[9] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 534ea341e5..e6147cae1d 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -21,16 +21,16 @@ The Semantic Conventions for the *Microsoft SQL Server* extend and override the | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection, qualified by the instance name. [1] | `instance1.products`; `customers` | `Conditionally Required` If available without an additional network call. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [Microsoft SQL Server error](https://learn.microsoft.com/sql/relational-databases/errors-events/database-engine-events-and-errors) number represented as a string. [2] | `102`; `40020` | `Conditionally Required` If response has ended with warning or an error. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection, qualified by the instance name. [1] | `instance1.products`; `customers` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [Microsoft SQL Server error](https://learn.microsoft.com/sql/relational-databases/errors-events/database-engine-events-and-errors) number represented as a string. [2] | `102`; `40020` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [8] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [10] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | **[1] `db.namespace`:** When connected to a default instance, `db.namespace` SHOULD be set to the name of the database. When connected to a [named instance](https://learn.microsoft.com/sql/connect/jdbc/building-the-connection-url#named-and-multiple-sql-server-instances), @@ -57,18 +57,15 @@ Instrumentations SHOULD document how `error.type` is populated. **[5] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. **[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. -This attribute has stability level RELEASE CANDIDATE. **[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization. **[9] `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. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -This attribute has stability level RELEASE CANDIDATE. **[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes 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 SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). @@ -77,7 +74,6 @@ Parameterized query text SHOULD be collected by default (the query parameter val **[12] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. -This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): diff --git a/docs/database/mysql.md b/docs/database/mysql.md index 0e8ae0302b..99bb820e83 100644 --- a/docs/database/mysql.md +++ b/docs/database/mysql.md @@ -21,16 +21,16 @@ The Semantic Conventions for *MySQL* extend and override the [Database Semantic | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection. [1] | `products`; `customers` | `Conditionally Required` If available without an additional network call. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html). [2] | `1005`; `MY-010016` | `Conditionally Required` If response has ended with warning or an error. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection. [1] | `products`; `customers` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html). [2] | `1005`; `MY-010016` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [8] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [10] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | **[1] `db.namespace`:** A connection's currently associated database may change during its lifetime, e.g. from executing `USE `. @@ -87,18 +87,15 @@ Instrumentations SHOULD document how `error.type` is populated. **[5] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. **[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. -This attribute has stability level RELEASE CANDIDATE. **[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization. **[9] `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. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -This attribute has stability level RELEASE CANDIDATE. **[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes 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 SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). @@ -107,7 +104,6 @@ Parameterized query text SHOULD be collected by default (the query parameter val **[12] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. -This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md index 30b132543a..545af7ae55 100644 --- a/docs/database/postgresql.md +++ b/docs/database/postgresql.md @@ -21,16 +21,16 @@ The Semantic Conventions for *PostgreSQL* extend and override the [Database Sema | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The schema associated with the connection, qualified by the database name. [1] | `mydatabase.products`; `mydatabase.customers` | `Conditionally Required` If available without an additional network call. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [PostgreSQL error code](https://www.postgresql.org/docs/current/errcodes-appendix.html). [2] | `08000`; `08P01` | `Conditionally Required` If response has ended with warning or an error. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The schema associated with the connection, qualified by the database name. [1] | `mydatabase.products`; `mydatabase.customers` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [PostgreSQL error code](https://www.postgresql.org/docs/current/errcodes-appendix.html). [2] | `08000`; `08P01` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [8] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [10] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | **[1] `db.namespace`:** `db.namespace` SHOULD be set to the combination of database and schema name following the `{database}.{schema}` pattern. @@ -94,18 +94,15 @@ Instrumentations SHOULD document how `error.type` is populated. **[5] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. **[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. -This attribute has stability level RELEASE CANDIDATE. **[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization. **[9] `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. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -This attribute has stability level RELEASE CANDIDATE. **[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes 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 SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). @@ -114,7 +111,6 @@ Parameterized query text SHOULD be collected by default (the query parameter val **[12] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. -This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): diff --git a/docs/database/redis.md b/docs/database/redis.md index 35c5b186a3..cd826850ff 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -27,17 +27,17 @@ looking confusing. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The [database index] associated with the connection, represented as a string. [1] | `0`; `1`; `15` | `Conditionally Required` If and only if it can be captured reliably. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | The Redis [simple error](https://redis.io/docs/latest/develop/reference/protocol-spec/#simple-errors) prefix. [4] | `ERR`; `WRONGTYPE`; `CLUSTERDOWN` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The [database index] associated with the connection, represented as a string. [1] | `0`; `1`; `15` | `Conditionally Required` If and only if it can be captured reliably. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [2] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | The Redis [simple error](https://redis.io/docs/latest/develop/reference/protocol-spec/#simple-errors) prefix. [4] | `ERR`; `WRONGTYPE`; `CLUSTERDOWN` | `Conditionally Required` [5] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [6] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Conditionally Required` [8] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [9] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The full syntax of the Redis CLI command. [10] | `HMSET myhash field1 'Hello' field2 'World'` | `Recommended` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [9] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The full syntax of the Redis CLI command. [10] | `HMSET myhash field1 'Hello' field2 'World'` | `Recommended` [11] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the database node where the operation was performed. [12] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [14] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [14] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | **[1] `db.namespace`:** A connection's currently associated database index may change during its lifetime, e.g. from executing `SELECT `. @@ -58,13 +58,10 @@ then that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. -This attribute has stability level RELEASE CANDIDATE. - **[3] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query. **[4] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. -This attribute has stability level RELEASE CANDIDATE. **[5] `db.response.status_code`:** If the operation failed and status code is available. @@ -77,7 +74,6 @@ Instrumentations SHOULD document how `error.type` is populated. **[8] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. **[9] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[10] `db.query.text`:** For **Redis**, the value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`. @@ -91,7 +87,6 @@ Parameterized query text SHOULD be collected by default (the query parameter val **[14] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. -This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): diff --git a/docs/database/sql.md b/docs/database/sql.md index 3e43150ab4..a66b348723 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -45,16 +45,16 @@ Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic co | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection, fully qualified within the server address and port. [1] | `customers`; `test.users` | `Conditionally Required` If available without an additional network call. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response code recorded as string. [2] | `ORA-17027`; `1052`; `2201B` | `Conditionally Required` If response has ended with warning or an error. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection, fully qualified within the server address and port. [1] | `customers`; `test.users` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response code recorded as string. [2] | `ORA-17027`; `1052`; `2201B` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.summary`](/docs/attributes-registry/db.md) | string | Low cardinality representation of a database query text. [7] | `SELECT wuser_table`; `INSERT shipping_details SELECT orders`; `get user by id` | `Recommended` [8] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.query.text`](/docs/attributes-registry/db.md) | string | The database query being executed. [9] | `SELECT * FROM wuser_table where username = ?`; `SET mykey ?` | `Recommended` [10] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.response.returned_rows`](/docs/attributes-registry/db.md) | int | Number of rows returned by the operation. | `10`; `30`; `1000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`db.operation.parameter.`](/docs/attributes-registry/db.md) | string | A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. [12] | `someval`; `55` | `Opt-In` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | **[1] `db.namespace`:** If a database system has multiple namespace components (e.g. schema name and database name), they SHOULD be concatenated (potentially using database system specific conventions) from most general to most @@ -119,18 +119,15 @@ Instrumentations SHOULD document how `error.type` is populated. **[5] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. **[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -This attribute has stability level RELEASE CANDIDATE. **[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. -This attribute has stability level RELEASE CANDIDATE. **[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization. **[9] `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. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -This attribute has stability level RELEASE CANDIDATE. **[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes 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 SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). @@ -139,7 +136,6 @@ Parameterized query text SHOULD be collected by default (the query parameter val **[12] `db.operation.parameter`:** If a parameter has no name and instead is referenced only by index, then `` SHOULD be the 0-based index. If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. -This attribute has stability level RELEASE CANDIDATE. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): diff --git a/model/database/metrics.yaml b/model/database/metrics.yaml index 5ae4d801b9..e73476722d 100644 --- a/model/database/metrics.yaml +++ b/model/database/metrics.yaml @@ -7,7 +7,7 @@ groups: Batch operations SHOULD be recorded as a single operation. instrument: histogram unit: "s" - stability: experimental # RELEASE CANDIDATE + stability: release_candidate extends: attributes.db.client.with_query_and_collection attributes: - ref: db.system diff --git a/model/database/registry.yaml b/model/database/registry.yaml index 6b731a9603..77dc009f4c 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -7,7 +7,7 @@ groups: attributes: - id: db.collection.name type: string - stability: experimental # RELEASE CANDIDATE + stability: release_candidate brief: The name of a collection (table, container) within the database. note: | It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. @@ -17,12 +17,10 @@ groups: For batch operations, if the individual operations are known to have the same collection name then that collection name SHOULD be used. - - This attribute has stability level RELEASE CANDIDATE. examples: ["public.users", "customers"] - id: db.namespace type: string - stability: experimental # RELEASE CANDIDATE + stability: release_candidate brief: > The name of the database, fully qualified within the server address and port. note: > @@ -35,12 +33,10 @@ groups: means in the context of that system. It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. - - This attribute has stability level RELEASE CANDIDATE. examples: ["customers", "test.users"] - id: db.operation.name type: string - stability: experimental # RELEASE CANDIDATE + stability: release_candidate brief: > The name of the operation or command being executed. note: | @@ -54,12 +50,10 @@ groups: then that operation name SHOULD be used prepended by `BATCH `, otherwise `db.operation.name` SHOULD be `BATCH` or some other database system specific term if more applicable. - - This attribute has stability level RELEASE CANDIDATE. examples: ["findAndModify", "HMSET", "SELECT"] - id: db.query.text type: string - stability: experimental # RELEASE CANDIDATE + stability: release_candidate brief: > The database query being executed. note: > @@ -72,8 +66,6 @@ groups: Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. - - This attribute has stability level RELEASE CANDIDATE. examples: [ "SELECT * FROM wuser_table where username = ?", @@ -81,7 +73,7 @@ groups: ] - id: db.operation.parameter type: template[string] - stability: experimental # RELEASE CANDIDATE + stability: release_candidate brief: > A database operation parameter, with `` being the parameter name, and the attribute value being a string representation of the parameter value. @@ -91,12 +83,10 @@ groups: If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD match up with the parameterized placeholders present in `db.query.text`. - - This attribute has stability level RELEASE CANDIDATE. examples: ["someval", "55"] - id: db.query.summary type: string - stability: experimental # RELEASE CANDIDATE + stability: release_candidate brief: > Low cardinality representation of a database query text. note: > @@ -109,8 +99,6 @@ groups: that support query parsing SHOULD generate a summary following [Generating query summary](../../docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. - - This attribute has stability level RELEASE CANDIDATE. examples: [ 'SELECT wuser_table', @@ -119,17 +107,15 @@ groups: ] - id: db.operation.batch.size type: int - stability: experimental # RELEASE CANDIDATE + stability: release_candidate brief: The number of queries included in a batch operation. note: > Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. - - This attribute has stability level RELEASE CANDIDATE. examples: [2, 3, 4] - id: db.response.status_code type: string - stability: experimental # RELEASE CANDIDATE + stability: release_candidate brief: Database response status code. note: > The status code returned by the database. Usually it represents an error code, @@ -138,8 +124,6 @@ groups: Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. - - This attribute has stability level RELEASE CANDIDATE. examples: ["102", "ORA-17002", "08P01", "404"] - id: db.response.returned_rows type: int @@ -152,8 +136,6 @@ groups: The actual DBMS may differ from the one identified by the client. For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system` is set to `postgresql` based on the instrumentation's best knowledge. - - This attribute has stability level RELEASE CANDIDATE. type: members: - id: other_sql @@ -287,7 +269,7 @@ groups: - id: mariadb value: "mariadb" brief: "MariaDB (This value has stability level RELEASE CANDIDATE)" - stability: experimental # RELEASE CANDIDATE + stability: release_candidate - id: maxdb value: "maxdb" brief: "SAP MaxDB" @@ -303,7 +285,7 @@ groups: - id: mssql value: "mssql" brief: "Microsoft SQL Server (This value has stability level RELEASE CANDIDATE)" - stability: experimental # RELEASE CANDIDATE + stability: release_candidate - id: mssqlcompact value: "mssqlcompact" deprecated: "Removed, use `other_sql` instead." @@ -312,7 +294,7 @@ groups: - id: mysql value: "mysql" brief: "MySQL (This value has stability level RELEASE CANDIDATE)" - stability: experimental # RELEASE CANDIDATE + stability: release_candidate - id: neo4j value: "neo4j" brief: "Neo4j" @@ -340,7 +322,7 @@ groups: - id: postgresql value: "postgresql" brief: "PostgreSQL (This value has stability level RELEASE CANDIDATE)" - stability: experimental # RELEASE CANDIDATE + stability: release_candidate - id: progress value: "progress" brief: "Progress Database" @@ -377,7 +359,7 @@ groups: value: "vertica" brief: "Vertica" stability: experimental - stability: experimental # RELEASE CANDIDATE + stability: release_candidate - id: db.client.connection.state stability: experimental type: diff --git a/templates/registry/markdown/stability.j2 b/templates/registry/markdown/stability.j2 index c623908bac..747b5a4446 100644 --- a/templates/registry/markdown/stability.j2 +++ b/templates/registry/markdown/stability.j2 @@ -2,6 +2,7 @@ {%- if deprecated %}![Deprecated](https://img.shields.io/badge/-deprecated-red)
{{ deprecated | trim }} {%- elif stability == "mixed" %}![Mixed](https://img.shields.io/badge/-mixed-yellow) {%- elif stability == "stable" %}![Stable](https://img.shields.io/badge/-stable-lightgreen) +{%- elif stability == "release_candidate" %}![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) {%- elif stability == "deprecated" %}![Deprecated](https://img.shields.io/badge/-deprecated-red) {%- else %}![Experimental](https://img.shields.io/badge/-experimental-blue) {%- endif %} From 07e99ebb78efaf0e89be4b4830c3ead9d8a2ad17 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 23 Dec 2024 07:37:37 -0800 Subject: [PATCH 4/6] Document which conventions belong in this repo (#1705) Co-authored-by: Trask Stalnaker Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- CONTRIBUTING.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4cfc04991c..0423486410 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,6 +13,7 @@ requirements and recommendations. - [Sign the CLA](#sign-the-cla) - [How to Contribute](#how-to-contribute) + - [Which semantic conventions belong in this repo](#which-semantic-conventions-belong-in-this-repo) - [Prerequisites](#prerequisites) - [1. Modify the YAML model](#1-modify-the-yaml-model) - [Code structure](#code-structure) @@ -62,6 +63,25 @@ key, but non-obvious, aspects: Please make sure all Pull Requests are compliant with these rules! +### Which semantic conventions belong in this repo + +This repo contains semantic conventions supported by the OpenTelemetry ecosystem +including, but not limited to, components hosted in OpenTelemetry. + +Instrumentations hosted in OpenTelemetry SHOULD contribute their semantic +conventions to this repo with the following exceptions: + +- Instrumentations that follow external schema not fully compatible with OpenTelemetry such as + [Kafka client JMX metrics](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/v2.10.0/instrumentation/kafka/kafka-clients/kafka-clients-2.6/library/README.md) + or [RabbitMQ Collector Receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.116.0/receiver/rabbitmqreceiver) + SHOULD document such conventions in their own repository. + +Having all OTel conventions in this repo allows to reuse common attributes, enforce naming and compatibility policies, +and helps to keep conventions consistent and backward compatible. + +Want to define your own conventions outside this repo while building on OTel’s? +Come help us [decentralize semantic conventions](https://github.com/open-telemetry/weaver/issues/215). + ### Prerequisites The Specification uses several tools to check things like style, From 05b4c173bfdee2e972d252d14593b9fb653cc54a Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Tue, 24 Dec 2024 20:05:41 +0100 Subject: [PATCH 5/6] Introduce gen_ai.request.seed as needed by cohere (#1710) --- .chloggen/genai-request-seed.yaml | 5 +++++ docs/attributes-registry/gen-ai.md | 11 ++++++++++- docs/gen-ai/openai.md | 2 +- model/gen-ai/deprecated/registry-deprecated.yaml | 11 +++++++++++ model/gen-ai/registry.yaml | 10 +++++----- 5 files changed, 32 insertions(+), 7 deletions(-) create mode 100644 .chloggen/genai-request-seed.yaml diff --git a/.chloggen/genai-request-seed.yaml b/.chloggen/genai-request-seed.yaml new file mode 100644 index 0000000000..0c19365120 --- /dev/null +++ b/.chloggen/genai-request-seed.yaml @@ -0,0 +1,5 @@ +change_type: 'enhancement' +component: gen_ai +note: Introduce gen_ai.request.seed and deprecated gen_ai.openai.request.seed + +issues: [1710] diff --git a/docs/attributes-registry/gen-ai.md b/docs/attributes-registry/gen-ai.md index 6606150d2e..5ada7b3cdb 100644 --- a/docs/attributes-registry/gen-ai.md +++ b/docs/attributes-registry/gen-ai.md @@ -9,6 +9,7 @@ - [GenAI Attributes](#genai-attributes) - [OpenAI Attributes](#openai-attributes) - [Deprecated GenAI Attributes](#deprecated-genai-attributes) +- [Deprecated OpenAI GenAI Attributes](#deprecated-openai-genai-attributes) ## GenAI Attributes @@ -22,6 +23,7 @@ This document defines the attributes used to describe telemetry in the context o | `gen_ai.request.max_tokens` | int | The maximum number of tokens the model generates for a request. | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.request.model` | string | The name of the GenAI model a request is being made to. | `gpt-4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.request.presence_penalty` | double | The presence penalty setting for the GenAI request. | `0.1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.request.seed` | int | Requests with same seed value more likely to return same result. | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.request.stop_sequences` | string[] | List of sequences that the model will use to stop generating further tokens. | `["forest", "lived"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.request.temperature` | double | The temperature setting for the GenAI request. | `0.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.request.top_k` | double | The top_k sampling setting for the GenAI request. | `1.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -88,7 +90,6 @@ Thie group defines attributes for OpenAI. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| | `gen_ai.openai.request.response_format` | string | The response format that is requested. | `json` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.openai.request.seed` | int | Requests with same seed value more likely to return same result. | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.openai.request.service_tier` | string | The service tier requested. May be a specific tier, default, or auto. | `auto`; `default` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.openai.response.service_tier` | string | The service tier used for the response. | `scale`; `default` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.openai.response.system_fingerprint` | string | A fingerprint to track any eventual change in the Generative AI environment. | `fp_44709d6fcb` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -122,3 +123,11 @@ Describes deprecated `gen_ai` attributes. | `gen_ai.prompt` | string | Deprecated, use Event API to report prompt contents. | `[{'role': 'user', 'content': 'What is the capital of France?'}]` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed, no replacement at this time. | | `gen_ai.usage.completion_tokens` | int | Deprecated, use `gen_ai.usage.output_tokens` instead. | `42` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `gen_ai.usage.output_tokens` attribute. | | `gen_ai.usage.prompt_tokens` | int | Deprecated, use `gen_ai.usage.input_tokens` instead. | `42` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `gen_ai.usage.input_tokens` attribute. | + +## Deprecated OpenAI GenAI Attributes + +Describes deprecated `gen_ai.openai` attributes. + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `gen_ai.openai.request.seed` | int | Deprecated, use `gen_ai.request.seed`. | `100` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `gen_ai.request.seed` attribute. | diff --git a/docs/gen-ai/openai.md b/docs/gen-ai/openai.md index 0584c16344..35b274b17a 100644 --- a/docs/gen-ai/openai.md +++ b/docs/gen-ai/openai.md @@ -40,7 +40,7 @@ attributes and ones specific the OpenAI. | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [2] | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.openai.request.response_format`](/docs/attributes-registry/gen-ai.md) | string | The response format that is requested. | `json` | `Conditionally Required` if the request includes a response_format | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.openai.request.seed`](/docs/attributes-registry/gen-ai.md) | int | Requests with same seed value more likely to return same result. | `100` | `Conditionally Required` if the request includes a seed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.openai.request.seed`](/docs/attributes-registry/gen-ai.md) | int | Deprecated, use `gen_ai.request.seed`. | `100` | `Conditionally Required` if the request includes a seed | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `gen_ai.request.seed` attribute. | | [`gen_ai.openai.request.service_tier`](/docs/attributes-registry/gen-ai.md) | string | The service tier requested. May be a specific tier, default, or auto. | `auto`; `default` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.openai.response.service_tier`](/docs/attributes-registry/gen-ai.md) | string | The service tier used for the response. | `scale`; `default` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [6] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/model/gen-ai/deprecated/registry-deprecated.yaml b/model/gen-ai/deprecated/registry-deprecated.yaml index 2115482f36..43270e6b00 100644 --- a/model/gen-ai/deprecated/registry-deprecated.yaml +++ b/model/gen-ai/deprecated/registry-deprecated.yaml @@ -28,3 +28,14 @@ groups: deprecated: "Removed, no replacement at this time." brief: "Deprecated, use Event API to report completions contents." examples: ["[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]"] + - id: registry.gen_ai.openai.deprecated + type: attribute_group + brief: Describes deprecated `gen_ai.openai` attributes. + display_name: Deprecated OpenAI GenAI Attributes + attributes: + - id: gen_ai.openai.request.seed + stability: experimental + type: int + deprecated: Replaced by `gen_ai.request.seed` attribute. + brief: "Deprecated, use `gen_ai.request.seed`." + examples: [100] diff --git a/model/gen-ai/registry.yaml b/model/gen-ai/registry.yaml index 918b0a2f21..ddf79f91ed 100644 --- a/model/gen-ai/registry.yaml +++ b/model/gen-ai/registry.yaml @@ -100,6 +100,11 @@ groups: note: > In some GenAI systems the encoding formats are called embedding types. Also, some GenAI systems only accept a single format per request. + - id: gen_ai.request.seed + stability: experimental + type: int + brief: Requests with same seed value more likely to return same result. + examples: [100] - id: gen_ai.response.id stability: experimental type: string @@ -168,11 +173,6 @@ groups: brief: > Thie group defines attributes for OpenAI. attributes: - - id: gen_ai.openai.request.seed - stability: experimental - type: int - brief: Requests with same seed value more likely to return same result. - examples: [100] - id: gen_ai.openai.request.response_format stability: experimental type: From 30f71c6fe146fc99ebb3a9204806fa79420a2fa1 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 27 Dec 2024 00:04:58 -0800 Subject: [PATCH 6/6] [editorial] A few random doc fixes (#1704) Co-authored-by: Trask Stalnaker Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- CONTRIBUTING.md | 42 +++++++++++-------- Makefile | 2 +- docs/attributes-registry/README.md | 9 ++-- docs/attributes-registry/db.md | 2 +- docs/attributes-registry/dns.md | 2 +- docs/gen-ai/gen-ai-events.md | 5 --- ...ility.md => semantic-convention-groups.md} | 0 model/README.md | 28 +++++++++++-- templates/registry/markdown/readme.md.j2 | 5 ++- templates/registry/markdown/weaver.yaml | 2 + 10 files changed, 62 insertions(+), 35 deletions(-) rename docs/general/{group-stability.md => semantic-convention-groups.md} (100%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0423486410..4331414084 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,8 +20,9 @@ requirements and recommendations. - [Schema files](#schema-files) - [2. Update the markdown files](#2-update-the-markdown-files) - [Hugo frontmatter](#hugo-frontmatter) - - [3. Verify the changes before committing](#3-verify-the-changes-before-committing) - - [4. Changelog](#4-changelog) + - [3. Check new convention](#3-check-new-convention) + - [4. Verify the changes before committing](#4-verify-the-changes-before-committing) + - [5. Changelog](#5-changelog) - [When to add a Changelog Entry](#when-to-add-a-changelog-entry) - [Examples](#examples) - [Adding a Changelog Entry](#adding-a-changelog-entry) @@ -32,7 +33,6 @@ requirements and recommendations. - [Markdown style](#markdown-style) - [Misspell check](#misspell-check) - [Markdown link check](#markdown-link-check) - - [Version compatibility check](#version-compatibility-check) - [Updating the referenced specification version](#updating-the-referenced-specification-version) - [Making a Release](#making-a-release) - [Merging existing ECS conventions](#merging-existing-ecs-conventions) @@ -126,6 +126,8 @@ The YAML (model definition) and Markdown (documentation) files are organized in │ │ ├── ....md ├── model │ ├── {root-namespace} +│ │ ├── deprecated +│ │ | ├── registry-deprecated.yaml │ │ ├── events.yaml │ │ ├── metrics.yaml │ │ ├── registry.yaml @@ -146,6 +148,9 @@ HTTP spans are defined in `model/http/spans.yaml`. YAML definitions could be broken down into multiple files. For example, AWS spans are defined in `/model/aws/lambda-spans.yaml` and `/model/aws/sdk-spans.yaml` files. +Deprecated conventions should be placed under `/model/{root-namespace}/deprecated` +folder. + #### Schema files When making changes to existing semantic conventions (attributes, metrics, etc) @@ -157,6 +162,7 @@ For details, please read You can also take examples from past changes inside the `schemas` folder. > [!WARNING] +> > DO NOT add your changes to files inside the `schemas` folder. Always add your > changes to the `schema-next.yaml` file. @@ -187,7 +193,21 @@ When creating new markdown files, you should provide the `linkTitle` attribute. This is used to generate the navigation bar on the website, and will be listed relative to the "parent" document. -### 3. Verify the changes before committing +### 3. Check new convention + +Semantic conventions are validated for name formatting and backward compatibility with last released versions. +Here's [the full list of compatibility checks](./policies/compatibility.rego). + +Removing attributes, metrics, or enum members is not allowed, they should be deprecated instead. +It applies to stable and experimental conventions and prevents semantic conventions auto-generated libraries from introducing breaking changes. + +You can run backward compatibility check (along with other policies) in all yaml files with the following command: + +```bash +make check-policies +``` + +### 4. Verify the changes before committing Before sending a PR with your changes, make sure to run the automated checks: @@ -198,7 +218,7 @@ make check Alternatively, you can run each check individually. Refer to the [Automation](#automation) section for more details. -### 4. Changelog +### 5. Changelog #### When to add a Changelog Entry @@ -361,18 +381,6 @@ To check the validity of links in all markdown files, run the following command: make markdown-link-check ``` -### Version compatibility check - -Semantic conventions are validated for backward compatibility with last released versions. Here's [the full list of compatibility checks](./policies/compatibility.rego). -Removing attributes, metrics, or enum members is not allowed, they should be deprecated instead. -It applies to stable and experimental conventions and prevents semantic conventions auto-generated libraries from introducing breaking changes. - -You can run backward compatibility check (along with other policies) in all yaml files with the following command: - -```bash -make check-policies -``` - ## Updating the referenced specification version 1. Open the `./internal/tools/update_specification_version.sh` script. diff --git a/Makefile b/Makefile index 6f2cf5c809..e4ed069ccc 100644 --- a/Makefile +++ b/Makefile @@ -183,7 +183,7 @@ fix-format: # Run all checks in order of speed / likely failure. # As a last thing, run attribute registry generation and git-diff for differences. .PHONY: check -check: misspell markdownlint check-format markdown-toc compatibility-check markdown-link-check check-policies attribute-registry-generation +check: misspell markdownlint check-format markdown-toc markdown-link-check check-policies attribute-registry-generation git diff --exit-code ':*.md' || (echo 'Generated markdown Table of Contents is out of date, please run "make markdown-toc" and commit the changes in this PR.' && exit 1) @echo "All checks complete" diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 4bfe974911..9f40561d47 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -16,7 +16,7 @@ The attributes registry is the place where attributes are defined. An attribute - a `brief` description of the attribute and optionally a longer `note` - example values -Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id` and `type` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context. +Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id`, `type` and `stability` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context. A definition of an attribute in the registry doesn't necessarily imply that the attribute is used in any of the semantic conventions. @@ -24,7 +24,8 @@ If applicable, application developers are encouraged to use existing attributes All registered attributes are listed by namespace in this registry. -> **Warning** +> [!WARNING] +> > The following registry overview is a work in progress. > > Further attribute namespaces are currently being migrated and will appear in this registry soon. @@ -45,12 +46,12 @@ Currently, the following namespaces exist: - [Code](code.md) - [Container](container.md) - [CPU](cpu.md) -- [Db](db.md) +- [DB](db.md) - [Deployment](deployment.md) - [Destination](destination.md) - [Device](device.md) - [Disk](disk.md) -- [Dns](dns.md) +- [DNS](dns.md) - [Dotnet](dotnet.md) - [Enduser](enduser.md) - [Error](error.md) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index c50e8f0112..6877905356 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -4,7 +4,7 @@ -# Db +# DB - [General Database Attributes](#general-database-attributes) - [Cassandra Attributes](#cassandra-attributes) diff --git a/docs/attributes-registry/dns.md b/docs/attributes-registry/dns.md index b694e02b3e..688b652025 100644 --- a/docs/attributes-registry/dns.md +++ b/docs/attributes-registry/dns.md @@ -4,7 +4,7 @@ -# Dns +# DNS ## DNS Attributes diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md index cc77890c73..e7fa7c0beb 100644 --- a/docs/gen-ai/gen-ai-events.md +++ b/docs/gen-ai/gen-ai-events.md @@ -25,13 +25,8 @@ linkTitle: Generative AI events GenAI instrumentations MAY capture user inputs sent to the model and responses received from it as [events](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/specification/logs/api.md#emit-an-event). -<<<<<<< HEAD -> [!NOTE] -> Event API is experimental and not yet available in some languages. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md#events) to see the implementation status in corresponding language. -======= > Note: > Event API is experimental and not yet available in some languages. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/spec-compliance-matrix.md#logs) to see the implementation status in corresponding language. ->>>>>>> 75746bc9 (reword) Instrumentations MAY capture inputs and outputs if and only if application has enabled the collection of this data. This is for three primary reasons: diff --git a/docs/general/group-stability.md b/docs/general/semantic-convention-groups.md similarity index 100% rename from docs/general/group-stability.md rename to docs/general/semantic-convention-groups.md diff --git a/model/README.md b/model/README.md index 821423416e..8affd9de18 100644 --- a/model/README.md +++ b/model/README.md @@ -4,8 +4,10 @@ The YAML descriptions of semantic convention contained in this directory are int be used by the various OpenTelemetry language implementations to aid in automatic generation of semantics-related code. -⚠ If you want to read the semantic conventions and not edit them, please see -the generated markdown output in the [docs](../docs/README.md) folder. +> [!NOTE] +> +> If you want to read the semantic conventions and not edit them, please see +> the generated markdown output in the [docs](../docs/README.md) folder. ## Writing semantic conventions @@ -21,18 +23,36 @@ A schema file for VS code is configured in the `/.vscode/settings.json` of this repository, enabling auto-completion and additional checks. Refer to [the generator README](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md) for what extension you need. +When defining semantic conventions, follow [contributing guide](/CONTRIBUTING.md#1-modify-the-yaml-model): + +- If new attributes are necessary, define them in the [attribute registry](/docs/attributes-registry/README.md). + Attributes can only be defined inside groups with `attribute_group` type and with `id` starting with `registry.` prefix. +- Define new spans, metrics, events, resources, and other conventions using appropriate group type. See + [semantic convention groups](/docs/general/semantic-convention-groups.md) for more details. + ## Generating markdown -These YAML files are used by the make target `table-generation` to generate consistently +These YAML files are used by the make targets `attribute-registry-generation` and `table-generation` to generate consistently formatted Markdown tables for all semantic conventions in the specification. Run it from the root of this repository using the command ``` -make table-generation +make attribute-registry-generation table-generation ``` For more information, see the [Weaver](https://github.com/open-telemetry/weaver) as our code generations tool. +## Validating semantic conventions + +Semantic conventions YAML files are validated by the `check-policies` make target for backward compatibility, +name formatting, and other policies. + +You can run it with the following command: + +``` +make check-policies +``` + See also: * [Markdown Templates](../templates/registry/markdown) diff --git a/templates/registry/markdown/readme.md.j2 b/templates/registry/markdown/readme.md.j2 index 1767f38b2e..ab36d57be8 100644 --- a/templates/registry/markdown/readme.md.j2 +++ b/templates/registry/markdown/readme.md.j2 @@ -17,7 +17,7 @@ The attributes registry is the place where attributes are defined. An attribute - a `brief` description of the attribute and optionally a longer `note` - example values -Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id` and `type` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context. +Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id`, `type` and `stability` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context. A definition of an attribute in the registry doesn't necessarily imply that the attribute is used in any of the semantic conventions. @@ -25,7 +25,8 @@ If applicable, application developers are encouraged to use existing attributes All registered attributes are listed by namespace in this registry. -> **Warning** +> [!WARNING] +> > The following registry overview is a work in progress. > > Further attribute namespaces are currently being migrated and will appear in this registry soon. diff --git a/templates/registry/markdown/weaver.yaml b/templates/registry/markdown/weaver.yaml index 104823f184..cbe61f30e3 100644 --- a/templates/registry/markdown/weaver.yaml +++ b/templates/registry/markdown/weaver.yaml @@ -14,6 +14,8 @@ acronyms: - CLR - CPU - CSI + - DB + - DNS - DynamoDB - ECS - EKS