diff --git a/.chloggen/add-service-instance-cost-center-id.yaml b/.chloggen/add-service-instance-cost-center-id.yaml new file mode 100644 index 0000000000..cab549cd29 --- /dev/null +++ b/.chloggen/add-service-instance-cost-center-id.yaml @@ -0,0 +1,5 @@ +# Use this changelog template to create an entry for release notes. +change_type: enhancement +component: service +note: "Add `service.instance.cost_center.id` attribute to the service registry." +issues: [3754] diff --git a/docs/registry/attributes/service.md b/docs/registry/attributes/service.md index bd2ffe1b00..194c94b5bd 100644 --- a/docs/registry/attributes/service.md +++ b/docs/registry/attributes/service.md @@ -15,14 +15,17 @@ A service instance. | Key | Stability | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | | `service.criticality` | ![Alpha](https://img.shields.io/badge/alpha-mediumpurple) | string | The operational criticality of the service. [1] | `critical`; `high`; `medium`; `low` | -| `service.instance.id` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | The string ID of the service instance. [2] | `627cc493-f310-47de-96bd-71410b7dec09` | -| `service.name` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | Logical name of the service. [3] | `shoppingcart` | -| `service.namespace` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | A namespace for `service.name`. [4] | `Shop` | +| `service.instance.cost_center.id` | ![Development](https://img.shields.io/badge/-development-blue) | string | Identifier of the cost center associated with the service instance. [2] | `94002`; `engineering-platform`; `marketing-campaigns-2026` | +| `service.instance.id` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | The string ID of the service instance. [3] | `627cc493-f310-47de-96bd-71410b7dec09` | +| `service.name` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | Logical name of the service. [4] | `shoppingcart` | +| `service.namespace` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | A namespace for `service.name`. [5] | `Shop` | | `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.criticality`:** Application developers are encouraged to set `service.criticality` to express the operational importance of their services. Telemetry consumers MAY use this attribute to optimize telemetry collection or improve user experience. -**[2] `service.instance.id`:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words +**[2] `service.instance.cost_center.id`:** The cost center identifier enables tracking and attribution of service resource costs to organizational units or teams. This standardization ensures consistent cost allocation across cloud providers, Kubernetes clusters, and observability platforms. + +**[3] `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). @@ -49,10 +52,10 @@ 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.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 the process executable name, e.g. `unknown_service:bash`. If the process executable name is not available, the value MUST be set to `unknown_service`. +**[4] `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 the process executable name, e.g. `unknown_service:bash`. If the process executable name is not available, the value MUST be set to `unknown_service`. The process executable name is the name of the process executable, the same value as described by the [`process.executable.name`](process.md) resource attribute. -**[4] `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. +**[5] `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. --- @@ -60,18 +63,18 @@ The process executable name is the name of the process executable, the same valu | Value | Description | Stability | | --- | --- | --- | -| `critical` | Service is business-critical; downtime directly impacts revenue, user experience, or core functionality. [5] | ![Alpha](https://img.shields.io/badge/alpha-mediumpurple) | -| `high` | Service is important but has degradation tolerance or fallback mechanisms. [6] | ![Alpha](https://img.shields.io/badge/alpha-mediumpurple) | -| `low` | Service is non-essential to core operations; used for background tasks or internal tools. [7] | ![Alpha](https://img.shields.io/badge/alpha-mediumpurple) | -| `medium` | Service provides supplementary functionality; degradation has limited user impact. [8] | ![Alpha](https://img.shields.io/badge/alpha-mediumpurple) | +| `critical` | Service is business-critical; downtime directly impacts revenue, user experience, or core functionality. [6] | ![Alpha](https://img.shields.io/badge/alpha-mediumpurple) | +| `high` | Service is important but has degradation tolerance or fallback mechanisms. [7] | ![Alpha](https://img.shields.io/badge/alpha-mediumpurple) | +| `low` | Service is non-essential to core operations; used for background tasks or internal tools. [8] | ![Alpha](https://img.shields.io/badge/alpha-mediumpurple) | +| `medium` | Service provides supplementary functionality; degradation has limited user impact. [9] | ![Alpha](https://img.shields.io/badge/alpha-mediumpurple) | -**[5]:** Examples include payment processing, authentication, and primary user-facing APIs. +**[6]:** Examples include payment processing, authentication, and primary user-facing APIs. -**[6]:** Examples include shopping cart, search, and recommendation engines. +**[7]:** Examples include shopping cart, search, and recommendation engines. -**[7]:** Examples include batch processors, cleanup jobs, and internal dashboards. +**[8]:** Examples include batch processors, cleanup jobs, and internal dashboards. -**[8]:** Examples include analytics, reporting, and non-essential integrations. +**[9]:** Examples include analytics, reporting, and non-essential integrations. ## Service Attributes for Peer Services diff --git a/docs/registry/entities/service.md b/docs/registry/entities/service.md index f8238beb4a..59d99c0f37 100644 --- a/docs/registry/entities/service.md +++ b/docs/registry/entities/service.md @@ -56,6 +56,7 @@ The process executable name is the name of the process executable, the same valu | 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) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | The string ID of the service instance. [7] | `627cc493-f310-47de-96bd-71410b7dec09` | +| Description | [`service.instance.cost_center.id`](/docs/registry/attributes/service.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | Identifier of the cost center associated with the service instance. [8] | `94002`; `engineering-platform`; `marketing-campaigns-2026` | **[7] `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 @@ -84,6 +85,8 @@ 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. +**[8] `service.instance.cost_center.id`:** The cost center identifier enables tracking and attribution of service resource costs to organizational units or teams. This standardization ensures consistent cost allocation across cloud providers, Kubernetes clusters, and observability platforms. + ## Service Namespace **Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) @@ -96,6 +99,6 @@ port. | 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) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | A namespace for `service.name`. [8] | `Shop` | +| Identity | [`service.namespace`](/docs/registry/attributes/service.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | A namespace for `service.name`. [9] | `Shop` | -**[8] `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. +**[9] `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 index c34fcaffa7..b2334fc1ed 100644 --- a/docs/resource/service.md +++ b/docs/resource/service.md @@ -111,6 +111,7 @@ The process executable name is the name of the process executable, the same valu | 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) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | The string ID of the service instance. [1] | `627cc493-f310-47de-96bd-71410b7dec09` | +| Description | [`service.instance.cost_center.id`](/docs/registry/attributes/service.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | Identifier of the cost center associated with the service instance. [2] | `94002`; `engineering-platform`; `marketing-campaigns-2026` | **[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 @@ -138,6 +139,8 @@ likely be wrong, as the Collector might not know from which container within tha 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. + +**[2] `service.instance.cost_center.id`:** The cost center identifier enables tracking and attribution of service resource costs to organizational units or teams. This standardization ensures consistent cost allocation across cloud providers, Kubernetes clusters, and observability platforms. diff --git a/model/service/entities.yaml b/model/service/entities.yaml index 514ae202bd..7038246ff5 100644 --- a/model/service/entities.yaml +++ b/model/service/entities.yaml @@ -32,6 +32,9 @@ groups: - ref: service.instance.id role: identifying requirement_level: required + - ref: service.instance.cost_center.id + requirement_level: opt_in + role: descriptive - id: entity.service.namespace type: entity name: service.namespace diff --git a/model/service/registry.yaml b/model/service/registry.yaml index 7498287762..60d7f4c563 100644 --- a/model/service/registry.yaml +++ b/model/service/registry.yaml @@ -112,6 +112,16 @@ groups: consumers MAY use this attribute to optimize telemetry collection or improve user experience. examples: ["critical", "high", "medium", "low"] + - id: service.instance.cost_center.id + type: string + stability: development + brief: > + Identifier of the cost center associated with the service instance. + note: > + The cost center identifier enables tracking and attribution of service resource costs to + organizational units or teams. This standardization ensures consistent cost allocation + across cloud providers, Kubernetes clusters, and observability platforms. + examples: ["94002", "engineering-platform", "marketing-campaigns-2026"] - id: registry.service.peer type: attribute_group display_name: Service Attributes for Peer Services