Initial cut at modelling service entities based on SIG discussions. #2963

jsuereth · 2025-10-23T12:36:58Z

Changes

Updates the service entity to consist of three components and describes each
Adds a service specific markdown file for resource modelling
Migrates existing attributes to appropriate entities in service.

Important

Pull requests acceptance are subject to the triage process as described in Issue and PR Triage Management.
PRs that do not follow the guidance above, may be automatically rejected and closed.

Merge requirement checklist

CONTRIBUTING.md guidelines followed.
Change log entry added, according to the guidelines in When to add a changelog entry.
- If your PR does not need a change log, start the PR title with [chore]
Links to the prototypes or existing instrumentations (when adding or changing conventions)

trask · 2025-10-28T20:35:27Z

docs/registry/entities/service.md

 **type:** `service`

-**Description:** A service instance.
+**Description:** A logical, distinct, component that makes up a system.


Suggested change

**Description:** A logical, distinct, component that makes up a system.

**Description:** A logical, distinct component that makes up a system.

Suggested change

**Description:** A logical, distinct, component that makes up a system.

**Description:** A logical unit of an application or system that performs a specific function.

My AI discussions sometimes used "system", "application" and "distributed system" as alternatives. I want to like system but I also get some weird feeling about it. The more I read.. the more I tend to prefer application more.

trask · 2025-10-28T20:36:11Z

docs/resource/service.md

+
+# Service semantic conventions
+
+Service is a logical component of an application that prodcues telemetry


Suggested change

Service is a logical component of an application that prodcues telemetry

Service is a logical component of an application that produces telemetry

trask · 2025-10-28T20:37:14Z

docs/resource/service.md

+- 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.


the word "process" makes me think of service.instance

Suggested change

application, typically running as a separate process or microservice.

application.

I agree on not using the term "process" to avoid the confusion, but removing latter part makes the sentence a bit vague for me. I would replace the latter part with another phrase. Example here:

Suggested change

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.

trask · 2025-10-28T20:40:35Z

model/service/entities.yaml

+    brief: >
+      A system of components designed for end-users or other applications.
+    note: >
+      A `service.namespace` is system, product or application that is


Suggested change

A `service.namespace` is system, product or application that is

A `service.namespace` is a system, product or application that is

trask · 2025-10-28T20:41:15Z

model/service/entities.yaml

-      A service instance.
+      A logical, distinct, component that makes up a system.
+    note: >
+      A `service` is a logical component used in a system, product or


Suggested change

A `service` is a logical component used in a system, product or

A service is a logical component used in a system, product or

trask · 2025-10-28T20:42:13Z

docs/resource/service.md

+| 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) |


joaopgrassi

I asked AI about how our model relates to k8s constructs. Here's the overview (which nicely aligns with our vision/goal/discussions so far)

OpenTelemetry Attribute	Kubernetes Construct	Description
`service.name`	`Deployment` or `Service`	Represents the logical name of the application or microservice. Typically aligns with a Kubernetes Deployment or Service name.
`service.namespace`	`Namespace`	Groups related services together. Aligns with Kubernetes namespaces for logical organization and isolation.
`service.instance.id`	`Container ID`	Uniquely identifies a specific instance of the service. Maps to the container runtime ID for the service's container.
`service.version`	`Container Image Tag`	Tracks the version of the service. Maps to the container image tag specified in the Deployment spec or Pod template.

joaopgrassi · 2025-10-29T12:23:36Z

docs/registry/entities/service.md

 **type:** `service`

-**Description:** A service instance.
+**Description:** A logical, distinct, component that makes up a system.


Suggested change

**Description:** A logical, distinct, component that makes up a system.

**Description:** A logical unit of an application or system that performs a specific function.

My AI discussions sometimes used "system", "application" and "distributed system" as alternatives. I want to like system but I also get some weird feeling about it. The more I read.. the more I tend to prefer application more.

joaopgrassi · 2025-10-29T12:24:09Z

docs/registry/entities/service.md

 **type:** `service`

-**Description:** A service instance.
+**Description:** A logical, distinct, component that makes up a system.


joaopgrassi · 2025-10-29T12:29:56Z

model/service/entities.yaml

+    type: entity
+    name: service.instance
+    brief: >
+      A distinct instance of a service component.


Suggested change

A distinct instance of a service component.

A unique instance of a logical service.

Maybe? To connect and reinforce that a service is a logical component while a instance is not.

joaopgrassi · 2025-10-29T12:30:10Z

model/service/entities.yaml

+    brief: >
+      A distinct instance of a service component.
+    note: >
+      A `service.instance` is a specific instance of a component. For example,


Suggested change

A `service.instance` is a specific instance of a component. For example,

A `service.instance` uniquely identifies an instance of a logical service. For example,

joaopgrassi · 2025-10-29T12:35:45Z

model/service/entities.yaml

+      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


Suggested change

a specific kubernetes container that is part of a kuebrnetes deployment

a container that is part of a kubernetes deployment

I would suggest beginning with capital letter for proper nouns ("Kubernetes")

joaopgrassi · 2025-10-29T12:38:04Z

model/service/entities.yaml

+    type: entity
+    name: service.namespace
+    brief: >
+      A system of components designed for end-users or other applications.


Suggested change

A system of components designed for end-users or other applications.

Groups related services that compose a system or application under a common namespace.

joaopgrassi · 2025-10-29T12:40:57Z

model/service/entities.yaml

+    brief: >
+      A system of components designed for end-users or other applications.
+    note: >
+      A `service.namespace` is system, product or application that is


Suggested change

A `service.namespace` is system, product or application that is

A `service.namespace` can be used to logically organize and group related services under a common namespace.

Maybe?

ymotongpoo

I just took a glance for the update. I'll add more comments if I have any findings.

ymotongpoo · 2025-10-30T12:43:26Z

docs/resource/service.md

+- 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.


I agree on not using the term "process" to avoid the confusion, but removing latter part makes the sentence a bit vague for me. I would replace the latter part with another phrase. Example here:

Suggested change

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.

ymotongpoo · 2025-10-30T12:45:33Z

model/service/entities.yaml

+      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


I would suggest beginning with capital letter for proper nouns ("Kubernetes")

jsuereth added 2 commits October 23, 2025 08:34

Initial cut at modelling service entities based on SIG discussions.

44a759c

Update descriptions from SIG meeting.

22218a0

lmolkova mentioned this pull request Oct 27, 2025

[chore] Clean up Entity snippets - make sure they include identifying vs. descriptive roles #2970

Merged

trask reviewed Oct 28, 2025

View reviewed changes

joaopgrassi reviewed Oct 29, 2025

View reviewed changes

ymotongpoo reviewed Oct 30, 2025

View reviewed changes

	Description: A logical, distinct, component that makes up a system.
	Description: A logical, distinct component that makes up a system.

	Description: A logical, distinct, component that makes up a system.
	Description: A logical unit of an application or system that performs a specific function.


		# Service semantic conventions

		Service is a logical component of an application that prodcues telemetry

	application, typically running as a separate process or microservice.
	application.

	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.namespace` is system, product or application that is
	A `service.namespace` is a system, product or application that is

	A `service` is a logical component used in a system, product or
	A service is a logical component used in a system, product or

	\| [`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.version`](/docs/registry/attributes/service.md) \| string \| The version string of the service component. The format is not defined by these conventions. \| `2.0.0`; `a01dbef8a` \| `Recommended` \| ![Stable](https://img.shields.io/badge/-stable-lightgreen) \|

	A distinct instance of a service component.
	A unique instance of a logical service.

	A `service.instance` is a specific instance of a component. For example,
	A `service.instance` uniquely identifies an instance of a logical service. For example,

	a specific kubernetes container that is part of a kuebrnetes deployment
	a container that is part of a kubernetes deployment

	A system of components designed for end-users or other applications.
	Groups related services that compose a system or application under a common namespace.

	A `service.namespace` is system, product or application that is
	A `service.namespace` can be used to logically organize and group related services under a common namespace.

Initial cut at modelling service entities based on SIG discussions. #2963

Are you sure you want to change the base?

Initial cut at modelling service entities based on SIG discussions. #2963

Conversation

jsuereth commented Oct 23, 2025

Changes

Merge requirement checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joaopgrassi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ymotongpoo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants