Skip to content

Commit 4cb9af5

Browse files
thompson-tomothompson-tomo
committed
Add more service info #2391
Signed-off-by: James Thompson <[email protected]>
1 parent 978aafe commit 4cb9af5

File tree

7 files changed

+140
-39
lines changed

7 files changed

+140
-39
lines changed

‎.chloggen/extend_services.yaml

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Use this changelog template to create an entry for release notes.
2+
#
3+
# If your change doesn't affect end users you should instead start
4+
# your pull request title with [chore] or use the "Skip Changelog" label.
5+
6+
# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
7+
change_type: enhancement
8+
9+
# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
10+
component: service
11+
12+
# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
13+
note: Allow services to report their status and what roles they perform
14+
15+
# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
16+
# The values here must be integers.
17+
issues: [2391]
18+
19+
# (Optional) One or more lines of additional information to render under the primary note.
20+
# These lines will be padded with 2 spaces and then inserted directly into the document.
21+
# Use pipe (|) for multiline entries.
22+
subtext:

‎docs/registry/attributes/service.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ A service instance.
1212
| <a id="service-instance-id" href="#service-instance-id">`service.instance.id`</a> | string | The string ID of the service instance. [1] | `627cc493-f310-47de-96bd-71410b7dec09` | ![Development](https://img.shields.io/badge/-development-blue) |
1313
| <a id="service-name" href="#service-name">`service.name`</a> | string | Logical name of the service. [2] | `shoppingcart` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
1414
| <a id="service-namespace" href="#service-namespace">`service.namespace`</a> | string | A namespace for `service.name`. [3] | `Shop` | ![Development](https://img.shields.io/badge/-development-blue) |
15+
| <a id="service-roles" href="#service-roles">`service.roles`</a> | string[] | Roles of a service node. [4] | `["ui", "background_tasks"]`; `["background_tasks"]` | ![Development](https://img.shields.io/badge/-development-blue) |
16+
| <a id="service-state" href="#service-state">`service.state`</a> | string | Current state of the service. [5] | `starting`; `running`; `stopping`; `stopped` | ![Development](https://img.shields.io/badge/-development-blue) |
1517
| <a id="service-version" href="#service-version">`service.version`</a> | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
1618

1719
**[1] `service.instance.id`:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words
@@ -44,3 +46,13 @@ port.
4446
**[2] `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`.
4547

4648
**[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.
49+
50+
**[4] `service.roles`:** This allows for distinction between different running roles of the same service.
51+
52+
In the case of Kibana, the service.node.role could be ui or background_tasks or both.
53+
54+
In the case of Elasticsearch, the service.node.role could be master or data or both.
55+
56+
Other services could use this to distinguish between a web and worker role running as part of the service.
57+
58+
**[5] `service.state`:** This state could be reported a collector which monitors the services

‎docs/registry/entities/README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,6 +247,10 @@ Currently, the following namespaces exist:
247247
<td></td>
248248
<td><a href="service.md#service">service</a></td>
249249
<td><img src="https://img.shields.io/badge/-stable-lightgreen" alt="Stable"/></td>
250+
</tr><tr>
251+
<td></td>
252+
<td><a href="service.md#service-instance">service.instance</a></td>
253+
<td><img src="https://img.shields.io/badge/-stable-lightgreen" alt="Stable"/></td>
250254
</tr><tr>
251255
<td>Telemetry</td><td></td><td></td>
252256
</tr><tr>

‎docs/registry/entities/service.md

Lines changed: 42 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,45 @@
1818
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
1919
|---|---|---|---|---|---|
2020
| [`service.name`](/docs/registry/attributes/service.md) | string | Logical name of the service. [1] | `shoppingcart` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
21-
| [`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) |
22-
| [`service.namespace`](/docs/registry/attributes/service.md) | string | A namespace for `service.name`. [3] | `Shop` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
21+
| [`service.namespace`](/docs/registry/attributes/service.md) | string | A namespace for `service.name`. [2] | `Shop` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
22+
| [`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) |
2323

2424
**[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`.
2525

26-
**[2] `service.instance.id`:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words
26+
**[2] `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.
27+
28+
**Descriptive Attributes:**
29+
30+
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
31+
|---|---|---|---|---|---|
32+
| [`service.roles`](/docs/registry/attributes/service.md) | string[] | Roles of a service node. [3] | `["ui", "background_tasks"]`; `["background_tasks"]` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
33+
| [`service.state`](/docs/registry/attributes/service.md) | string | Current state of the service. [4] | `starting`; `running`; `stopping`; `stopped` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
34+
35+
**[3] `service.roles`:** This allows for distinction between different running roles of the same service.
36+
37+
In the case of Kibana, the service.node.role could be ui or background_tasks or both.
38+
39+
In the case of Elasticsearch, the service.node.role could be master or data or both.
40+
41+
Other services could use this to distinguish between a web and worker role running as part of the service.
42+
43+
**[4] `service.state`:** This state could be reported a collector which monitors the services
44+
45+
## Service Instance
46+
47+
**Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen)
48+
49+
**type:** `service.instance`
50+
51+
**Description:** A service instance.
52+
53+
**Identifying Attributes:**
54+
55+
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
56+
|---|---|---|---|---|---|
57+
| [`service.instance.id`](/docs/registry/attributes/service.md) | string | The string ID of the service instance. [5] | `627cc493-f310-47de-96bd-71410b7dec09` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
58+
59+
**[5] `service.instance.id`:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words
2760
`service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to
2861
distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled
2962
service).
@@ -50,13 +83,17 @@ However, Collectors can set the `service.instance.id` if they can unambiguously
5083
for that telemetry. This is typically the case for scraping receivers, as they know the target address and
5184
port.
5285

53-
**[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.
54-
5586
**Descriptive Attributes:**
5687

5788
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
5889
|---|---|---|---|---|---|
90+
| [`service.name`](/docs/registry/attributes/service.md) | string | Logical name of the service. [6] | `shoppingcart` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
91+
| [`service.namespace`](/docs/registry/attributes/service.md) | string | A namespace for `service.name`. [7] | `Shop` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
5992
| [`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) |
6093

94+
**[6] `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`.
95+
96+
**[7] `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.
97+
6198

6299
<!-- markdownlint-restore -->

‎docs/resource/README.md

Lines changed: 14 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -84,40 +84,24 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet
8484
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
8585
|---|---|---|---|---|---|
8686
| [`service.name`](/docs/registry/attributes/service.md) | string | Logical name of the service. [1] | `shoppingcart` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
87-
| [`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) |
88-
| [`service.namespace`](/docs/registry/attributes/service.md) | string | A namespace for `service.name`. [3] | `Shop` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
87+
| [`service.namespace`](/docs/registry/attributes/service.md) | string | A namespace for `service.name`. [2] | `Shop` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
88+
| [`service.roles`](/docs/registry/attributes/service.md) | string[] | Roles of a service node. [3] | `["ui", "background_tasks"]`; `["background_tasks"]` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
89+
| [`service.state`](/docs/registry/attributes/service.md) | string | Current state of the service. [4] | `starting`; `running`; `stopping`; `stopped` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
8990
| [`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) |
9091

9192
**[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`.
9293

93-
**[2] `service.instance.id`:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words
94-
`service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to
95-
distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled
96-
service).
97-
98-
Implementations, such as SDKs, are recommended to generate a random Version 1 or Version 4 [RFC
99-
4122](https://www.ietf.org/rfc/rfc4122.txt) UUID, but are free to use an inherent unique ID as the source of
100-
this value if stability is desirable. In that case, the ID SHOULD be used as source of a UUID Version 5 and
101-
SHOULD use the following UUID as the namespace: `4d63009a-8d0f-11ee-aad7-4c796ed8e320`.
102-
103-
UUIDs are typically recommended, as only an opaque value for the purposes of identifying a service instance is
104-
needed. Similar to what can be seen in the man page for the
105-
[`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/latest/machine-id.html) file, the underlying
106-
data, such as pod name and namespace should be treated as confidential, being the user's choice to expose it
107-
or not via another resource attribute.
108-
109-
For applications running behind an application server (like unicorn), we do not recommend using one identifier
110-
for all processes participating in the application. Instead, it's recommended each division (e.g. a worker
111-
thread in unicorn) to have its own instance.id.
112-
113-
It's not recommended for a Collector to set `service.instance.id` if it can't unambiguously determine the
114-
service instance that is generating that telemetry. For instance, creating an UUID based on `pod.name` will
115-
likely be wrong, as the Collector might not know from which container within that pod the telemetry originated.
116-
However, Collectors can set the `service.instance.id` if they can unambiguously determine the service instance
117-
for that telemetry. This is typically the case for scraping receivers, as they know the target address and
118-
port.
119-
120-
**[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.
94+
**[2] `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.
95+
96+
**[3] `service.roles`:** This allows for distinction between different running roles of the same service.
97+
98+
In the case of Kibana, the service.node.role could be ui or background_tasks or both.
99+
100+
In the case of Elasticsearch, the service.node.role could be master or data or both.
101+
102+
Other services could use this to distinguish between a web and worker role running as part of the service.
103+
104+
**[4] `service.state`:** This state could be reported a collector which monitors the services
121105

122106
<!-- markdownlint-restore -->
123107
<!-- prettier-ignore-end -->

‎model/service/entities.yaml

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,35 @@
11
groups:
2-
- id: entity.service
2+
- id: entity.service.intance
33
type: entity
4-
name: service
4+
name: service.instance
55
brief: >
66
A service instance.
77
stability: stable
88
attributes:
99
- ref: service.name
1010
requirement_level: required
11-
role: identifying
11+
role: descriptive
1212
- ref: service.version
1313
role: descriptive
1414
- ref: service.namespace
15-
role: identifying
15+
role: descriptive
1616
- ref: service.instance.id
1717
role: identifying
18+
- id: entity.service
19+
type: entity
20+
name: service
21+
brief: >
22+
A service which can generate telemetry.
23+
stability: stable
24+
attributes:
25+
- ref: service.name
26+
requirement_level: required
27+
role: identifying
28+
- ref: service.version
29+
role: identifying
30+
- ref: service.namespace
31+
role: identifying
32+
- ref: service.roles
33+
role: descriptive
34+
- ref: service.state
35+
role: descriptive

‎model/service/registry.yaml

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,3 +69,27 @@ groups:
6969
for that telemetry. This is typically the case for scraping receivers, as they know the target address and
7070
port.
7171
examples: ["627cc493-f310-47de-96bd-71410b7dec09"]
72+
- id: service.roles
73+
type: string[]
74+
stability: development
75+
brief: >
76+
Roles of a service node.
77+
note: |
78+
This allows for distinction between different running roles of the same service.
79+
80+
In the case of Kibana, the service.node.role could be ui or background_tasks or both.
81+
82+
In the case of Elasticsearch, the service.node.role could be master or data or both.
83+
84+
Other services could use this to distinguish between a web and worker role running as part of the service.
85+
examples:
86+
- ["ui", "background_tasks"]
87+
- ["background_tasks"]
88+
- id: service.state
89+
type: string
90+
brief: >
91+
Current state of the service.
92+
note: >
93+
This state could be reported a collector which monitors the services
94+
examples: ["starting", "running", "stopping", "stopped"]
95+
stability: development

0 commit comments

Comments
 (0)