From 44a759c02f97c84386dedda6d799eb8e9cc3621d Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Thu, 23 Oct 2025 08:34:49 -0400 Subject: [PATCH 1/8] Initial cut at modelling service entities based on SIG discussions. --- docs/registry/entities/README.md | 2 + docs/registry/entities/service.md | 38 ++++++-- docs/resource/README.md | 35 +------ docs/resource/service.md | 153 ++++++++++++++++++++++++++++++ model/service/entities.yaml | 23 ++++- 5 files changed, 209 insertions(+), 42 deletions(-) create mode 100644 docs/resource/service.md diff --git a/docs/registry/entities/README.md b/docs/registry/entities/README.md index 9a3c0c576c..a5c6da6344 100644 --- a/docs/registry/entities/README.md +++ b/docs/registry/entities/README.md @@ -88,6 +88,8 @@ Currently, the following namespaces exist: | | [process.runtime](process.md#process-runtime) | ![Development](https://img.shields.io/badge/-development-blue) | | Service | | | | | [service](service.md#service) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| | [service.instance](service.md#service-instance) | ![Development](https://img.shields.io/badge/-development-blue) | +| | [service.namespace](service.md#service-namespace) | ![Development](https://img.shields.io/badge/-development-blue) | | Telemetry | | | | | [telemetry.distro](telemetry.md#telemetry-distro) | ![Development](https://img.shields.io/badge/-development-blue) | | | [telemetry.sdk](telemetry.md#telemetry-sdk) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/registry/entities/service.md b/docs/registry/entities/service.md index e52ed20914..ae56173118 100644 --- a/docs/registry/entities/service.md +++ b/docs/registry/entities/service.md @@ -11,18 +11,36 @@ **type:** `service` -**Description:** A service instance. +**Description:** A logical, distinct, component that makes up an Application, e.g. a microservice. **Identifying Attributes:** | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`service.name`](/docs/registry/attributes/service.md) | string | Logical name of the service. [1] | `shoppingcart` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`service.instance.id`](/docs/registry/attributes/service.md) | string | The string ID of the service instance. [2] | `627cc493-f310-47de-96bd-71410b7dec09` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`service.namespace`](/docs/registry/attributes/service.md) | string | A namespace for `service.name`. [3] | `Shop` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | **[1] `service.name`:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. +**Descriptive Attributes:** + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`service.version`](/docs/registry/attributes/service.md) | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +## Service Instance + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**type:** `service.instance` + +**Description:** A service instance. + +**Identifying Attributes:** + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`service.instance.id`](/docs/registry/attributes/service.md) | string | The string ID of the service instance. [2] | `627cc493-f310-47de-96bd-71410b7dec09` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | + **[2] `service.instance.id`:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words `service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled @@ -50,13 +68,21 @@ However, Collectors can set the `service.instance.id` if they can unambiguously for that telemetry. This is typically the case for scraping receivers, as they know the target address and port. -**[3] `service.namespace`:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. +## Service Namespace -**Descriptive Attributes:** +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**type:** `service.namespace` + +**Description:** A system of components designed for end-users or other applications. + +**Identifying Attributes:** | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`service.version`](/docs/registry/attributes/service.md) | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`service.namespace`](/docs/registry/attributes/service.md) | string | A namespace for `service.name`. [3] | `Shop` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[3] `service.namespace`:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. diff --git a/docs/resource/README.md b/docs/resource/README.md index f7c4ddad6b..5b03b7f9fb 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -75,50 +75,19 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet -**Status:** ![Mixed](https://img.shields.io/badge/-mixed-yellow) +**Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) **type:** `service` -**Description:** A service instance. +**Description:** A logical, distinct, component that makes up an Application, e.g. a microservice. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`service.name`](/docs/registry/attributes/service.md) | string | Logical name of the service. [1] | `shoppingcart` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`service.instance.id`](/docs/registry/attributes/service.md) | string | The string ID of the service instance. [2] | `627cc493-f310-47de-96bd-71410b7dec09` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`service.namespace`](/docs/registry/attributes/service.md) | string | A namespace for `service.name`. [3] | `Shop` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`service.version`](/docs/registry/attributes/service.md) | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `service.name`:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. -**[2] `service.instance.id`:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words -`service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to -distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled -service). - -Implementations, such as SDKs, are recommended to generate a random Version 1 or Version 4 [RFC -4122](https://www.ietf.org/rfc/rfc4122.txt) UUID, but are free to use an inherent unique ID as the source of -this value if stability is desirable. In that case, the ID SHOULD be used as source of a UUID Version 5 and -SHOULD use the following UUID as the namespace: `4d63009a-8d0f-11ee-aad7-4c796ed8e320`. - -UUIDs are typically recommended, as only an opaque value for the purposes of identifying a service instance is -needed. Similar to what can be seen in the man page for the -[`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/latest/machine-id.html) file, the underlying -data, such as pod name and namespace should be treated as confidential, being the user's choice to expose it -or not via another resource attribute. - -For applications running behind an application server (like unicorn), we do not recommend using one identifier -for all processes participating in the application. Instead, it's recommended each division (e.g. a worker -thread in unicorn) to have its own instance.id. - -It's not recommended for a Collector to set `service.instance.id` if it can't unambiguously determine the -service instance that is generating that telemetry. For instance, creating an UUID based on `pod.name` will -likely be wrong, as the Collector might not know from which container within that pod the telemetry originated. -However, Collectors can set the `service.instance.id` if they can unambiguously determine the service instance -for that telemetry. This is typically the case for scraping receivers, as they know the target address and -port. - -**[3] `service.namespace`:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. - diff --git a/docs/resource/service.md b/docs/resource/service.md new file mode 100644 index 0000000000..1c84b4675b --- /dev/null +++ b/docs/resource/service.md @@ -0,0 +1,153 @@ + + +# Service semantic conventions + +Service is a logical component of an application that prodcues telemetry +data (events, metrics, spans, etc.). + +In modern, distributed, application architectures: + +- An `service.namespace` is an entire system of components designed for end-users + or other applications to leverage. +- A `service` is one of the distinct components that make up the application, + typically running as a separate process or microservice. +- A `service.instance` is a distinct instance of a service component, e.g. a + specific kubernetes container that is part of a kubernetes deployment which + offers a service. + +For example, supposes we have a Blog site that consists of a database +and an HTTP server which uses the database: + +```mermaid +flowchart LR + App(("`**service.namespace** + blog-site`")) + Db["`**service.name** + db`"] + Http["`**service.name** + http-server`"] + Http1["`**service.instance.id** + aabcd-1231`"] + Http2["`**service.instance.id** + aabcd-1234`"] + Db1["`**service.instance.id** + aabcd-3421`"] + Db --> Db1 + Http --> Http1 + Http --> Http2 + App --> Db + App --> Http +``` + +Here, we can see the HTTP server has two instances that may use a load-balancer +between them. Additionally, there's a single database instance. + +## Service + + + + + + + + + +**Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) + +**type:** `service` + +**Description:** A logical, distinct, component that makes up an Application, e.g. a microservice. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`service.name`](/docs/registry/attributes/service.md) | string | Logical name of the service. [1] | `shoppingcart` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`service.version`](/docs/registry/attributes/service.md) | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1] `service.name`:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. + + + + + + +## Service Instance + + + + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**type:** `service.instance` + +**Description:** A service instance. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`service.instance.id`](/docs/registry/attributes/service.md) | string | The string ID of the service instance. [1] | `627cc493-f310-47de-96bd-71410b7dec09` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `service.instance.id`:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words +`service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to +distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled +service). + +Implementations, such as SDKs, are recommended to generate a random Version 1 or Version 4 [RFC +4122](https://www.ietf.org/rfc/rfc4122.txt) UUID, but are free to use an inherent unique ID as the source of +this value if stability is desirable. In that case, the ID SHOULD be used as source of a UUID Version 5 and +SHOULD use the following UUID as the namespace: `4d63009a-8d0f-11ee-aad7-4c796ed8e320`. + +UUIDs are typically recommended, as only an opaque value for the purposes of identifying a service instance is +needed. Similar to what can be seen in the man page for the +[`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/latest/machine-id.html) file, the underlying +data, such as pod name and namespace should be treated as confidential, being the user's choice to expose it +or not via another resource attribute. + +For applications running behind an application server (like unicorn), we do not recommend using one identifier +for all processes participating in the application. Instead, it's recommended each division (e.g. a worker +thread in unicorn) to have its own instance.id. + +It's not recommended for a Collector to set `service.instance.id` if it can't unambiguously determine the +service instance that is generating that telemetry. For instance, creating an UUID based on `pod.name` will +likely be wrong, as the Collector might not know from which container within that pod the telemetry originated. +However, Collectors can set the `service.instance.id` if they can unambiguously determine the service instance +for that telemetry. This is typically the case for scraping receivers, as they know the target address and +port. + + + + + + +## Service Namespace + + + + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +**type:** `service.namespace` + +**Description:** A system of components designed for end-users or other applications. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`service.namespace`](/docs/registry/attributes/service.md) | string | A namespace for `service.name`. [1] | `Shop` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `service.namespace`:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. + + + + + + diff --git a/model/service/entities.yaml b/model/service/entities.yaml index 319eb39eae..703f41aaa8 100644 --- a/model/service/entities.yaml +++ b/model/service/entities.yaml @@ -3,7 +3,8 @@ groups: type: entity name: service brief: > - A service instance. + A logical, distinct, component that makes up an Application, + e.g. a microservice. stability: stable attributes: - ref: service.name @@ -11,7 +12,23 @@ groups: role: identifying - ref: service.version role: descriptive - - ref: service.namespace - role: identifying + - id: entity.service.instance + type: entity + name: service.instance + brief: > + A service instance. + stability: development + attributes: - ref: service.instance.id role: identifying + requirement_level: required + - id: entity.service.namespace + type: entity + name: service.namespace + brief: > + A system of components designed for end-users or other applications. + stability: development + attributes: + - ref: service.namespace + role: identifying + requirement_level: required \ No newline at end of file From 22218a0eb982027ac343066bf0f0a633bf61a3e8 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Fri, 24 Oct 2025 08:41:32 -0400 Subject: [PATCH 2/8] Update descriptions from SIG meeting. --- docs/registry/entities/service.md | 4 +-- docs/resource/README.md | 42 +++---------------------------- docs/resource/service.md | 12 ++++----- model/service/entities.yaml | 18 ++++++++++--- 4 files changed, 25 insertions(+), 51 deletions(-) diff --git a/docs/registry/entities/service.md b/docs/registry/entities/service.md index ae56173118..a2ef1399fb 100644 --- a/docs/registry/entities/service.md +++ b/docs/registry/entities/service.md @@ -11,7 +11,7 @@ **type:** `service` -**Description:** A logical, distinct, component that makes up an Application, e.g. a microservice. +**Description:** A logical, distinct, component that makes up a system. **Identifying Attributes:** @@ -33,7 +33,7 @@ **type:** `service.instance` -**Description:** A service instance. +**Description:** A distinct instance of a service component. **Identifying Attributes:** diff --git a/docs/resource/README.md b/docs/resource/README.md index 5b03b7f9fb..e40b89905b 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -62,50 +62,14 @@ as specified in [OpenTelemetry Environment Variable Specification](https://githu These are the attributes which MUST be provided by the SDK as specified in the [Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/resource/sdk.md#sdk-provided-resource-attributes): -- [`service.name`](#service) +- [`service.name`](service.md#service) - [`telemetry.sdk` group](#telemetry-sdk) ## Service - - - - - - - - -**Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) - -**type:** `service` - -**Description:** A logical, distinct, component that makes up an Application, e.g. a microservice. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`service.name`](/docs/registry/attributes/service.md) | string | Logical name of the service. [1] | `shoppingcart` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`service.version`](/docs/registry/attributes/service.md) | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - -**[1] `service.name`:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. - - - - - - -Note: `service.namespace` and `service.name` are not intended to be concatenated for the purpose of forming a single globally unique name for the service. For example the following 2 sets of attributes actually describe 2 different services (despite the fact that the concatenation would result in the same string): - -``` -# Resource attributes that describes a service. -namespace = Company.Shop -service.name = shoppingcart -``` +Logical grouping of components. -``` -# Another set of resource attributes that describe a different service. -namespace = Company -service.name = Shop.shoppingcart -``` +- [Service](service.md). ## Telemetry SDK diff --git a/docs/resource/service.md b/docs/resource/service.md index 1c84b4675b..9140aabf9f 100644 --- a/docs/resource/service.md +++ b/docs/resource/service.md @@ -9,10 +9,10 @@ data (events, metrics, spans, etc.). In modern, distributed, application architectures: -- An `service.namespace` is an entire system of components designed for end-users - or other applications to leverage. -- A `service` is one of the distinct components that make up the application, - typically running as a separate process or microservice. +- An `service.namespace` is an entire system of components designed for + end-users or other applications to leverage. +- A `service` is one of the logical, distinct components that make up the + application, typically running as a separate process or microservice. - A `service.instance` is a distinct instance of a service component, e.g. a specific kubernetes container that is part of a kubernetes deployment which offers a service. @@ -58,7 +58,7 @@ between them. Additionally, there's a single database instance. **type:** `service` -**Description:** A logical, distinct, component that makes up an Application, e.g. a microservice. +**Description:** A logical, distinct, component that makes up a system. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -86,7 +86,7 @@ between them. Additionally, there's a single database instance. **type:** `service.instance` -**Description:** A service instance. +**Description:** A distinct instance of a service component. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/model/service/entities.yaml b/model/service/entities.yaml index 703f41aaa8..b4cac9de4f 100644 --- a/model/service/entities.yaml +++ b/model/service/entities.yaml @@ -3,8 +3,11 @@ groups: type: entity name: service brief: > - A logical, distinct, component that makes up an Application, - e.g. a microservice. + A logical, distinct, component that makes up a system. + note: > + A `service` is a logical component used in a system, product or + application. Examples include a microservice, a database, + a kubernetes deployment. stability: stable attributes: - ref: service.name @@ -16,7 +19,11 @@ groups: type: entity name: service.instance brief: > - A service instance. + A distinct instance of a service component. + note: > + A `service.instance` is a specific instance of a component. For example, + a specific kubernetes container that is part of a kuebrnetes deployment + that offers a service. stability: development attributes: - ref: service.instance.id @@ -27,8 +34,11 @@ groups: name: service.namespace brief: > A system of components designed for end-users or other applications. + note: > + A `service.namespace` is system, product or application that is + composed of services. stability: development attributes: - ref: service.namespace role: identifying - requirement_level: required \ No newline at end of file + requirement_level: required From 11ae7af2fb98a8cb56080a5c3d5d7d24939ff02b Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Thu, 20 Nov 2025 08:31:16 -0500 Subject: [PATCH 3/8] Address all comments. --- docs/registry/attributes/service.md | 2 +- docs/registry/entities/service.md | 8 ++++---- docs/resource/service.md | 12 ++++++------ model/service/entities.yaml | 17 ++++++++--------- model/service/registry.yaml | 2 +- 5 files changed, 20 insertions(+), 21 deletions(-) diff --git a/docs/registry/attributes/service.md b/docs/registry/attributes/service.md index a5d3f6be08..2e0b16cc94 100644 --- a/docs/registry/attributes/service.md +++ b/docs/registry/attributes/service.md @@ -14,7 +14,7 @@ A service instance. | `service.instance.id` | ![Development](https://img.shields.io/badge/-development-blue) | string | The string ID of the service instance. [1] | `627cc493-f310-47de-96bd-71410b7dec09` | | `service.name` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | Logical name of the service. [2] | `shoppingcart` | | `service.namespace` | ![Development](https://img.shields.io/badge/-development-blue) | string | A namespace for `service.name`. [3] | `Shop` | -| `service.version` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | +| `service.version` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | The version string of the service component. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | **[1] `service.instance.id`:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words `service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to diff --git a/docs/registry/entities/service.md b/docs/registry/entities/service.md index e8d8fd9932..f51ea04540 100644 --- a/docs/registry/entities/service.md +++ b/docs/registry/entities/service.md @@ -11,12 +11,12 @@ **type:** `service` -**Description:** A logical, distinct, component that makes up a system. +**Description:** A logical unit of an application or system that performs a specific function. | Role | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | |---|---|---|---|---|---|---| | Identity | [`service.name`](/docs/registry/attributes/service.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | Logical name of the service. [1] | `shoppingcart` | -| Description | [`service.version`](/docs/registry/attributes/service.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | +| Description | [`service.version`](/docs/registry/attributes/service.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The version string of the service component. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | **[1] `service.name`:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. @@ -26,7 +26,7 @@ **type:** `service.instance` -**Description:** A distinct instance of a service component. +**Description:** A unique instance of a logical service. | Role | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | |---|---|---|---|---|---|---| @@ -65,7 +65,7 @@ port. **type:** `service.namespace` -**Description:** A system of components designed for end-users or other applications. +**Description:** Groups related services that compose a system or application under a common namespace. | Role | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | |---|---|---|---|---|---|---| diff --git a/docs/resource/service.md b/docs/resource/service.md index d954b3e8c9..761171416c 100644 --- a/docs/resource/service.md +++ b/docs/resource/service.md @@ -4,7 +4,7 @@ linkTitle: Service # Service semantic conventions -Service is a logical component of an application that prodcues telemetry +Service is a logical component of an application that produces telemetry data (events, metrics, spans, etc.). In modern, distributed, application architectures: @@ -12,7 +12,7 @@ In modern, distributed, application architectures: - An `service.namespace` is an entire system of components designed for end-users or other applications to leverage. - A `service` is one of the logical, distinct components that make up the - application, typically running as a separate process or microservice. + application, typically running as a bundle of the instances that run the same container image for load balancing. - A `service.instance` is a distinct instance of a service component, e.g. a specific kubernetes container that is part of a kubernetes deployment which offers a service. @@ -57,11 +57,11 @@ between them. Additionally, there's a single database instance. **type:** `service` -**Description:** A logical, distinct, component that makes up a system. +**Description:** A logical unit of an application or system that performs a specific function. | Role | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | |---|---|---|---|---|---|---| | Identity | [`service.name`](/docs/registry/attributes/service.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | Logical name of the service. [1] | `shoppingcart` | -| Description | [`service.version`](/docs/registry/attributes/service.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | +| Description | [`service.version`](/docs/registry/attributes/service.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The version string of the service component. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | **[1] `service.name`:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. @@ -82,7 +82,7 @@ between them. Additionally, there's a single database instance. **type:** `service.instance` -**Description:** A distinct instance of a service component. +**Description:** A unique instance of a logical service. | Role | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | |---|---|---|---|---|---|---| | Identity | [`service.instance.id`](/docs/registry/attributes/service.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The string ID of the service instance. [1] | `627cc493-f310-47de-96bd-71410b7dec09` | @@ -131,7 +131,7 @@ port. **type:** `service.namespace` -**Description:** A system of components designed for end-users or other applications. +**Description:** Groups related services that compose a system or application under a common namespace. | Role | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | |---|---|---|---|---|---|---| | Identity | [`service.namespace`](/docs/registry/attributes/service.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | A namespace for `service.name`. [1] | `Shop` | diff --git a/model/service/entities.yaml b/model/service/entities.yaml index b4cac9de4f..ef000c9a8a 100644 --- a/model/service/entities.yaml +++ b/model/service/entities.yaml @@ -3,11 +3,11 @@ groups: type: entity name: service brief: > - A logical, distinct, component that makes up a system. + A logical unit of an application or system that performs a specific function. note: > - A `service` is a logical component used in a system, product or + A service is a logical component used in a system, product or application. Examples include a microservice, a database, - a kubernetes deployment. + a Kubernetes deployment. stability: stable attributes: - ref: service.name @@ -19,10 +19,10 @@ groups: type: entity name: service.instance brief: > - A distinct instance of a service component. + A unique instance of a logical service. note: > - A `service.instance` is a specific instance of a component. For example, - a specific kubernetes container that is part of a kuebrnetes deployment + A `service.instance` uniquely identifies an instance of a logical service. For example, + a container that is part of a Kubernetes deployment that offers a service. stability: development attributes: @@ -33,10 +33,9 @@ groups: type: entity name: service.namespace brief: > - A system of components designed for end-users or other applications. + Groups related services that compose a system or application under a common namespace. note: > - A `service.namespace` is system, product or application that is - composed of services. + A `service.namespace` can be used to logically organize and group related services under a common namespace. stability: development attributes: - ref: service.namespace diff --git a/model/service/registry.yaml b/model/service/registry.yaml index 9715378b19..9eeb1972d5 100644 --- a/model/service/registry.yaml +++ b/model/service/registry.yaml @@ -19,7 +19,7 @@ groups: - id: service.version type: string brief: > - The version string of the service API or implementation. The format is not defined by these conventions. + The version string of the service component. The format is not defined by these conventions. examples: ["2.0.0", "a01dbef8a"] stability: stable - id: service.namespace From ac4b9614a4fa63eb6cca47c74fba6cea3ebfda96 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Thu, 20 Nov 2025 08:54:57 -0500 Subject: [PATCH 4/8] Add changelog. --- .chloggen/fix-2880.yaml | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100755 .chloggen/fix-2880.yaml diff --git a/.chloggen/fix-2880.yaml b/.chloggen/fix-2880.yaml new file mode 100755 index 0000000000..50f0096224 --- /dev/null +++ b/.chloggen/fix-2880.yaml @@ -0,0 +1,26 @@ +# 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: service + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Splits `service` entity into three pieces - namespace, service and instance. + +# 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: [2880] + +# (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: | + The service entity is now split into three: `service.namespace`, + `service` and `service.instance`. Existing service attributes are + distributed between these three and descriptions are updated to + denote how to think about these concepts going forward. \ No newline at end of file From 7ae8a6f62ab8f736b79b93f9d5e1ce2f7d354337 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Thu, 20 Nov 2025 08:57:04 -0500 Subject: [PATCH 5/8] Fix markdown issue. --- docs/resource/service.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/resource/service.md b/docs/resource/service.md index 761171416c..ab58e9215e 100644 --- a/docs/resource/service.md +++ b/docs/resource/service.md @@ -141,4 +141,3 @@ port. - From 4b50851ed4e0dcf8296f6692c1bd04b9fa163b3b Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Thu, 20 Nov 2025 09:02:32 -0500 Subject: [PATCH 6/8] Fix yamllint. --- .chloggen/fix-2880.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chloggen/fix-2880.yaml b/.chloggen/fix-2880.yaml index 50f0096224..c6a0701b63 100755 --- a/.chloggen/fix-2880.yaml +++ b/.chloggen/fix-2880.yaml @@ -23,4 +23,4 @@ subtext: | The service entity is now split into three: `service.namespace`, `service` and `service.instance`. Existing service attributes are distributed between these three and descriptions are updated to - denote how to think about these concepts going forward. \ No newline at end of file + denote how to think about these concepts going forward. From f167f6c51449a41357aaf0ee7e1c1be06e2dbe09 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 24 Nov 2025 15:09:18 -0500 Subject: [PATCH 7/8] Update docs/resource/service.md Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- docs/resource/service.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/resource/service.md b/docs/resource/service.md index ab58e9215e..a2324d88de 100644 --- a/docs/resource/service.md +++ b/docs/resource/service.md @@ -9,7 +9,7 @@ data (events, metrics, spans, etc.). In modern, distributed, application architectures: -- An `service.namespace` is an entire system of components designed for +- A `service.namespace` is an entire system of components designed for end-users or other applications to leverage. - A `service` is one of the logical, distinct components that make up the application, typically running as a bundle of the instances that run the same container image for load balancing. From e3f1cc7ef18d3dc8af63ba0ab83ad21940ba49a2 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 24 Nov 2025 15:10:06 -0500 Subject: [PATCH 8/8] Apply suggestions from code review Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- docs/resource/service.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/resource/service.md b/docs/resource/service.md index a2324d88de..96d5a1c109 100644 --- a/docs/resource/service.md +++ b/docs/resource/service.md @@ -12,12 +12,12 @@ In modern, distributed, application architectures: - A `service.namespace` is an entire system of components designed for end-users or other applications to leverage. - A `service` is one of the logical, distinct components that make up the - application, typically running as a bundle of the instances that run the same container image for load balancing. + application, typically running multiple instances of the same container image for load balancing. - A `service.instance` is a distinct instance of a service component, e.g. a specific kubernetes container that is part of a kubernetes deployment which offers a service. -For example, supposes we have a Blog site that consists of a database +For example, suppose we have a Blog site that consists of a database and an HTTP server which uses the database: ```mermaid @@ -33,7 +33,7 @@ flowchart LR Http2["`**service.instance.id** aabcd-1234`"] Db1["`**service.instance.id** - aabcd-3421`"] + db-gbgfx`"] Db --> Db1 Http --> Http1 Http --> Http2