Merge branch 'samsp-msft/MCP' of https://github.com/samsp-msft/semantic-conventions into samsp-msft/MCP

Author: Sam Spencer

.chloggen/add_oracledb_semconv.yaml

@@ -0,0 +1,23 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: new_component
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: db
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Adding semantic conventions for `oracledb` instrumentations.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [2612]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
+  Oracle Database semantic conventions.

.chloggen/browser-event.yaml

@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: new_component
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: browser
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add browser web vitals event.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1940]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

.chloggen/ff-generic-error.yaml

@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: breaking
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: feature_flag
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Use generic `error.message` in feature flag evaluation event
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1994]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

.chloggen/rename-span-health-metrics.yaml

@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: 'breaking'
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: 'otel'
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Rename span health metrics to remove the .count suffixes
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1979]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

.chloggen/requests-duration.yaml

@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: 'enhancement'
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: 'otel'
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Adds SDK self-monitoring metric for exporter call duration
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1906]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

.lychee.toml

@@ -7,8 +7,8 @@ exclude = [
     # excluding links to pull requests and issues is done for performance
     "^https://github.com/open-telemetry/semantic-conventions/(pull|issues)/\\d+$",
     "^https://github.com/open-telemetry/opentelemetry-specification/(pull|issues)/\\d+$",
-    # TODO (trask) remove this exclusion after (hopefully) this page comes back up
-    "^https://docs.oracle.com/en/java/javase/17/docs/api/"
+    # TODO (lmolkova) treat timeout as not a failure?
+    "^https://www.intersystems.com"
 ]
 
 # better to be safe and avoid failures

CONTRIBUTING.md

@@ -12,7 +12,7 @@ requirements and recommendations.
 <!-- toc -->
 
 - [Sign the CLA](#sign-the-cla)
-- [How to Contribute](#how-to-contribute)
+- [How to contribute](#how-to-contribute)
   - [Which semantic conventions belong in this repo](#which-semantic-conventions-belong-in-this-repo)
   - [Suggesting conventions for a new area](#suggesting-conventions-for-a-new-area)
   - [Prerequisites](#prerequisites)
@@ -24,12 +24,12 @@ requirements and recommendations.
   - [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)
+    - [When to add a changelog entry](#when-to-add-a-changelog-entry)
       - [Examples](#examples)
-    - [Adding a Changelog Entry](#adding-a-changelog-entry)
+    - [Adding a changelog entry](#adding-a-changelog-entry)
   - [5. Getting your PR merged](#5-getting-your-pr-merged)
 - [Automation](#automation)
-  - [Consistency Checks](#consistency-checks)
+  - [Consistency checks](#consistency-checks)
   - [Auto formatting](#auto-formatting)
   - [Markdown style](#markdown-style)
   - [Misspell check](#misspell-check)
@@ -46,7 +46,7 @@ requirements and recommendations.
 Before you can contribute, you will need to sign the [Contributor License
 Agreement](https://identity.linuxfoundation.org/projects/cncf).
 
-## How to Contribute
+## How to contribute
 
 When contributing to semantic conventions, it's important to understand a few
 key, but non-obvious, aspects:
@@ -248,7 +248,7 @@ Refer to the [Automation](#automation) section for more details.
 
 ### 5. Changelog
 
-#### When to add a Changelog Entry
+#### When to add a changelog entry
 
 Pull requests that contain user-facing changes will require a changelog entry.
 Keep in mind the following types of users (not limited to):
@@ -275,7 +275,7 @@ No changelog entry:
 - Refactorings with no meaningful change in functionality
 - Chores, such as enabling linters, updating dependencies
 
-#### Adding a Changelog Entry
+#### Adding a changelog entry
 
 The [CHANGELOG.md](./CHANGELOG.md) files in this repo is autogenerated
 from `.yaml` files in the [/.chloggen](/.chloggen) directory.
@@ -319,7 +319,7 @@ to merge**.
 
 Semantic Conventions provides a set of automated tools for general development.
 
-### Consistency Checks
+### Consistency checks
 
 The Specification has a number of tools it uses to check things like style,
 spelling and link validity.

docs/attributes-registry/db.md

@@ -61,9 +61,9 @@ If `db.query.text` is also captured, then `db.operation.parameter.<key>` SHOULD
 `db.operation.parameter.<key>` SHOULD NOT be captured on batch operations.
 
 **[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](../database/database-spans.md#generating-a-summary-of-the-query-text) section.
+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.
 
-**[7] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext).
+**[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.
 

docs/attributes-registry/feature-flag.md

@@ -13,7 +13,6 @@ This document defines attributes for Feature Flags.
 | Attribute | Type | Description | Examples | Stability |
 |---|---|---|---|---|
 | <a id="feature-flag-context-id" href="#feature-flag-context-id">`feature_flag.context.id`</a> | string | The unique identifier for the flag evaluation context. For example, the targeting key. | `5157782b-2203-4c80-a857-dbbd5e7761db` | ![Development](https://img.shields.io/badge/-development-blue) |
-| <a id="feature-flag-evaluation-error-message" href="#feature-flag-evaluation-error-message">`feature_flag.evaluation.error.message`</a> | string | A message explaining the nature of an error occurring during flag evaluation. | `Flag `header-color` expected type `string` but found type `number`` | ![Development](https://img.shields.io/badge/-development-blue) |
 | <a id="feature-flag-key" href="#feature-flag-key">`feature_flag.key`</a> | string | The lookup key of the feature flag. | `logo-color` | ![Development](https://img.shields.io/badge/-development-blue) |
 | <a id="feature-flag-provider-name" href="#feature-flag-provider-name">`feature_flag.provider_name`</a> | string | Identifies the feature flag provider. | `Flag Manager` | ![Development](https://img.shields.io/badge/-development-blue) |
 | <a id="feature-flag-result-reason" href="#feature-flag-result-reason">`feature_flag.result.reason`</a> | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | ![Development](https://img.shields.io/badge/-development-blue) |
@@ -48,6 +47,7 @@ Describes deprecated feature flag attributes.
 
 | Attribute | Type | Description | Examples | Stability |
 |---|---|---|---|---|
+| <a id="feature-flag-evaluation-error-message" href="#feature-flag-evaluation-error-message">`feature_flag.evaluation.error.message`</a> | string | Deprecated, use `error.message` instead. | `Flag `header-color` expected type `string` but found type `number`` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `error.message`. |
 | <a id="feature-flag-evaluation-reason" href="#feature-flag-evaluation-reason">`feature_flag.evaluation.reason`</a> | string | Deprecated, use `feature_flag.result.reason` instead. | `static`; `targeting_match`; `error`; `default` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `feature_flag.result.reason`. |
 | <a id="feature-flag-variant" href="#feature-flag-variant">`feature_flag.variant`</a> | string | Deprecated, use `feature_flag.result.variant` instead. | `red`; `true`; `on` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `feature_flag.result.variant`. |
 

docs/browser/events.md

@@ -0,0 +1,54 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Events
+--->
+
+# Semantic conventions for browser events
+
+**Status**: [Development][DocumentStatus]
+
+This document defines semantic conventions for browser (web) instrumentations
+that emit events.
+
+## WebVital Event
+
+<!-- semconv event.browser.web_vital -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+**Status:** ![Development](https://img.shields.io/badge/-development-blue)
+
+The event name MUST be `browser.web_vital`.
+
+This event describes the website performance metrics introduced by Google, See [web vitals](https://web.dev/vitals).
+
+**Body fields:**
+
+:warning: Body fields will be moved to complex attributes once the
+semantic convention tooling supports complex attributes
+(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)).
+
+| Body Field  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| `delta` | double | The delta between the current value and the last-reported value. See [delta](https://github.com/GoogleChrome/web-vitals?tab=readme-ov-file#report-only-the-delta-of-changes). | `0.2` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
+| `id` | string | A unique ID representing this particular metric instance. | `v3-1677874579383-6381583661209` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
+| `name` | enum | Name of the web vital. | `cls` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
+| `value` | double | Value of the web vital. | `1.0` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
+
+`name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
+
+| Value  | Description | Stability |
+|---|---|---|
+| `cls` | Cumulative Layout Shift. See [cls](https://web.dev/articles/cls). | ![Development](https://img.shields.io/badge/-development-blue) |
+| `fid` | First Input Delay. See [fid](https://web.dev/articles/fid). | ![Development](https://img.shields.io/badge/-development-blue) |
+| `inp` | Interation to Next Paint. See [inp](https://web.dev/articles/inp). | ![Development](https://img.shields.io/badge/-development-blue) |
+| `lcp` | Largest Contentful Paint. See [lcp](https://web.dev/articles/lcp). | ![Development](https://img.shields.io/badge/-development-blue) |
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

docs/cli/cli-spans.md

@@ -8,14 +8,6 @@ linkTitle: CLI programs
 
 This document defines semantic conventions to apply when instrumenting CLI programs, both as a caller and as callee. This document is intended for short-lived programs that end their execution, i.e. not daemon or long running background tasks.
 
-Span kind SHOULD be `INTERNAL` when the traced program is the callee or `CLIENT` when the caller is tracing another program.
-
-The span name SHOULD be set to `{process.executable.name}`.
-Instrumentations that have additional context about executed commands MAY use a different low-cardinality span name format and SHOULD document it.
-
-Span status SHOULD be set to `Error` if `{process.exit.code}` is not 0. Refer to the [Recording Errors](/docs/general/recording-errors.md) document for
-additional details on how to record span status.
-
 <!-- TODO: context propagation https://github.com/open-telemetry/semantic-conventions/issues/1612 -->
 
 ## Execution (callee) spans
@@ -27,6 +19,19 @@ additional details on how to record span status.
 <!-- markdownlint-capture -->
 <!-- markdownlint-disable -->
 
+**Status:** ![Development](https://img.shields.io/badge/-development-blue)
+
+This span describes CLI (Command Line Interfaces) program execution from a callee perspective.
+
+**Span name** SHOULD be set to {process.executable.name}.
+Instrumentations that have additional context about executed commands MAY use
+a different low-cardinality span name format and SHOULD document it.
+
+**Span status** SHOULD be set to Error if {process.exit.code} is not 0. Refer to
+the [Recording Errors](/docs/general/recording-errors.md) document for details on how to record span status.
+
+**Span kind** SHOULD be `INTERNAL`.
+
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
 | [`process.executable.name`](/docs/attributes-registry/process.md) | string | The name of the process executable. On Linux based systems, this SHOULD be set to the base name of the target of `/proc/[pid]/exe`. On Windows, this SHOULD be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
@@ -78,6 +83,19 @@ it's RECOMMENDED to:
 <!-- markdownlint-capture -->
 <!-- markdownlint-disable -->
 
+**Status:** ![Development](https://img.shields.io/badge/-development-blue)
+
+This span describes CLI (Command Line Interfaces) program execution from a caller perspective.
+
+**Span name** SHOULD be set to {process.executable.name}.
+Instrumentations that have additional context about executed commands MAY use
+a different low-cardinality span name format and SHOULD document it.
+
+**Span status** SHOULD be set to Error if {process.exit.code} is not 0. Refer to
+the [Recording Errors](/docs/general/recording-errors.md) document for details on how to record span status.
+
+**Span kind** SHOULD be `CLIENT`.
+
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
 | [`process.executable.name`](/docs/attributes-registry/process.md) | string | The name of the process executable. On Linux based systems, this SHOULD be set to the base name of the target of `/proc/[pid]/exe`. On Windows, this SHOULD be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |