From b48ebd5b5fd8795976189fc20f95018ef6ca5eb3 Mon Sep 17 00:00:00 2001 From: urjitasharma-11 <51237691+urjitasharma-11@users.noreply.github.com> Date: Fri, 29 May 2026 12:41:30 +0530 Subject: [PATCH] feat: add service.instance.cost_center attribute (#3754) --- docs/registry/attributes/service.md | 27 +++++++++++++++------------ docs/registry/entities/service.md | 19 +++++++++++-------- docs/resource/service.md | 15 +++++++++------ model/service/entities.yaml | 9 +++++++++ model/service/registry.yaml | 10 ++++++++++ 5 files changed, 54 insertions(+), 26 deletions(-) diff --git a/docs/registry/attributes/service.md b/docs/registry/attributes/service.md index e6f485a4d4..d7ae55b73b 100644 --- a/docs/registry/attributes/service.md +++ b/docs/registry/attributes/service.md @@ -14,15 +14,18 @@ A service instance. | Key | Stability | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | -| `service.criticality` | ![Development](https://img.shields.io/badge/-development-blue) | 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` | ![Development](https://img.shields.io/badge/-development-blue) | string | Identifier of the cost center associated with the service instance. [1] | `94002`; `engineering-platform`; `marketing-campaigns-2026` | +| `service.criticality` | ![Development](https://img.shields.io/badge/-development-blue) | string | The operational criticality of the service. [2] | `critical`; `high`; `medium`; `low` | +| `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. +**[1] `service.instance.cost_center`:** 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. -**[2] `service.instance.id`:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words +**[2] `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. + +**[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. --- @@ -65,13 +68,13 @@ The process executable name is the name of the process executable, the same valu | `low` | Service is non-essential to core operations; used for background tasks or internal tools. [7] | ![Development](https://img.shields.io/badge/-development-blue) | | `medium` | Service provides supplementary functionality; degradation has limited user impact. [8] | ![Development](https://img.shields.io/badge/-development-blue) | -**[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 14fc8666af..3dd97ca6d4 100644 --- a/docs/registry/entities/service.md +++ b/docs/registry/entities/service.md @@ -16,13 +16,16 @@ | 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.criticality`](/docs/registry/attributes/service.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The operational criticality of the service. [2] | `critical`; `high`; `medium`; `low` | +| Description | [`service.instance.cost_center`](/docs/registry/attributes/service.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Identifier of the cost center associated with the service instance. [2] | `94002`; `engineering-platform` | +| Description | [`service.criticality`](/docs/registry/attributes/service.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The operational criticality of the service. [3] | `critical`; `high`; `medium`; `low` | | 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 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. -**[2] `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.cost_center`:** The cost center identifier enables tracking and attribution of service resource costs to organizational units or teams. This attribute is defined at the instance level because costs are primarily incurred by runtime entities, and `service.instance` represents the actual compute unit where resource consumption occurs. Standardizing this identifier ensures consistent cost allocation and normalization across diverse cloud providers, Kubernetes clusters, and observability platforms. + +**[3] `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. --- @@ -30,10 +33,10 @@ 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. [3] | ![Development](https://img.shields.io/badge/-development-blue) | -| `high` | Service is important but has degradation tolerance or fallback mechanisms. [4] | ![Development](https://img.shields.io/badge/-development-blue) | -| `low` | Service is non-essential to core operations; used for background tasks or internal tools. [5] | ![Development](https://img.shields.io/badge/-development-blue) | -| `medium` | Service provides supplementary functionality; degradation has limited user impact. [6] | ![Development](https://img.shields.io/badge/-development-blue) | +| `critical` | Service is business-critical; downtime directly impacts revenue, user experience, or core functionality. [4] | ![Development](https://img.shields.io/badge/-development-blue) | +| `high` | Service is important but has degradation tolerance or fallback mechanisms. [5] | ![Development](https://img.shields.io/badge/-development-blue) | +| `low` | Service is non-essential to core operations; used for background tasks or internal tools. [6] | ![Development](https://img.shields.io/badge/-development-blue) | +| `medium` | Service provides supplementary functionality; degradation has limited user impact. [7] | ![Development](https://img.shields.io/badge/-development-blue) | **[3]:** Examples include payment processing, authentication, and primary user-facing APIs. @@ -55,7 +58,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` | +| 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. [8] | `627cc493-f310-47de-96bd-71410b7dec09` | **[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 @@ -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. diff --git a/docs/resource/service.md b/docs/resource/service.md index 7120ebc95d..a737ec4953 100644 --- a/docs/resource/service.md +++ b/docs/resource/service.md @@ -63,13 +63,16 @@ between them. Additionally, there's a single database instance. | 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.criticality`](/docs/registry/attributes/service.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The operational criticality of the service. [2] | `critical`; `high`; `medium`; `low` | +| Description | [`service.instance.cost_center`](/docs/registry/attributes/service.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Identifier of the cost center associated with the service instance. [2] | `94002`; `engineering-platform` | +| Description | [`service.criticality`](/docs/registry/attributes/service.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The operational criticality of the service. [3] | `critical`; `high`; `medium`; `low` | | 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 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. -**[2] `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.cost_center`:** The cost center identifier enables tracking and attribution of service resource costs to specific organizational units or teams. This attribute is placed at the instance level to reflect that costs are primarily incurred by runtime entities, which represent the actual compute unit where resource consumption occurs. Standardizing this identifier at the instance level provides the flexibility to aggregate costs across different deployments or regions for the same logical service. This ensures consistent financial attribution across multi-cloud environments, Kubernetes clusters, and observability platforms. + +**[3] `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. --- @@ -82,13 +85,13 @@ The process executable name is the name of the process executable, the same valu | `low` | Service is non-essential to core operations; used for background tasks or internal tools. [5] | ![Development](https://img.shields.io/badge/-development-blue) | | `medium` | Service provides supplementary functionality; degradation has limited user impact. [6] | ![Development](https://img.shields.io/badge/-development-blue) | -**[3]:** Examples include payment processing, authentication, and primary user-facing APIs. +**[4]:** Examples include payment processing, authentication, and primary user-facing APIs. -**[4]:** Examples include shopping cart, search, and recommendation engines. +**[5]:** Examples include shopping cart, search, and recommendation engines. -**[5]:** Examples include batch processors, cleanup jobs, and internal dashboards. +**[6]:** Examples include batch processors, cleanup jobs, and internal dashboards. -**[6]:** Examples include analytics, reporting, and non-essential integrations. +**[7]:** Examples include analytics, reporting, and non-essential integrations. diff --git a/model/service/entities.yaml b/model/service/entities.yaml index 514ae202bd..b191a85e8d 100644 --- a/model/service/entities.yaml +++ b/model/service/entities.yaml @@ -44,3 +44,12 @@ groups: - ref: service.namespace role: identifying requirement_level: required + - id: entity.service.instance + type: entity + name: service.instance + attributes: + - ref: service.instance.id + requirement_level: required + - ref: service.instance.cost_center + requirement_level: recommended + role: descriptive \ No newline at end of file diff --git a/model/service/registry.yaml b/model/service/registry.yaml index 5b2cd0d3cb..6b1678fe69 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 + 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