|
| 1 | +groups: |
| 2 | + - id: registry.service |
| 3 | + prefix: service |
| 4 | + type: attribute_group |
| 5 | + brief: > |
| 6 | + A service instance. |
| 7 | + attributes: |
| 8 | + - id: name |
| 9 | + type: string |
| 10 | + brief: > |
| 11 | + Logical name of the service. |
| 12 | + note: > |
| 13 | + MUST be the same for all instances of horizontally scaled services. |
| 14 | + If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated |
| 15 | + with [`process.executable.name`](process.md#process), e.g. `unknown_service:bash`. |
| 16 | + If `process.executable.name` is not available, the value MUST be set to `unknown_service`. |
| 17 | + examples: ["shoppingcart"] |
| 18 | + stability: stable |
| 19 | + - id: version |
| 20 | + type: string |
| 21 | + brief: > |
| 22 | + The version string of the service API or implementation. The format is not defined by these conventions. |
| 23 | + examples: ["2.0.0", "a01dbef8a"] |
| 24 | + stability: stable |
| 25 | + - id: namespace |
| 26 | + type: string |
| 27 | + stability: experimental |
| 28 | + brief: > |
| 29 | + A namespace for `service.name`. |
| 30 | + note: > |
| 31 | + A string value having a meaning that helps to distinguish a group of services, |
| 32 | + for example the team name that owns a group of services. |
| 33 | + `service.name` is expected to be unique within the same namespace. |
| 34 | + If `service.namespace` is not specified in the Resource then `service.name` |
| 35 | + is expected to be unique for all services that have no explicit namespace defined |
| 36 | + (so the empty/unspecified namespace is simply one more valid namespace). |
| 37 | + Zero-length namespace string is assumed equal to unspecified namespace. |
| 38 | + examples: ["Shop"] |
| 39 | + - id: instance.id |
| 40 | + type: string |
| 41 | + stability: experimental |
| 42 | + brief: > |
| 43 | + The string ID of the service instance. |
| 44 | + note: | |
| 45 | + MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words |
| 46 | + `service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to |
| 47 | + distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled |
| 48 | + service). |
| 49 | +
|
| 50 | + Implementations, such as SDKs, are recommended to generate a random Version 1 or Version 4 [RFC |
| 51 | + 4122](https://www.ietf.org/rfc/rfc4122.txt) UUID, but are free to use an inherent unique ID as the source of |
| 52 | + this value if stability is desirable. In that case, the ID SHOULD be used as source of a UUID Version 5 and |
| 53 | + SHOULD use the following UUID as the namespace: `4d63009a-8d0f-11ee-aad7-4c796ed8e320`. |
| 54 | +
|
| 55 | + UUIDs are typically recommended, as only an opaque value for the purposes of identifying a service instance is |
| 56 | + needed. Similar to what can be seen in the man page for the |
| 57 | + [`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/machine-id.html) file, the underlying |
| 58 | + data, such as pod name and namespace should be treated as confidential, being the user's choice to expose it |
| 59 | + or not via another resource attribute. |
| 60 | +
|
| 61 | + For applications running behind an application server (like unicorn), we do not recommend using one identifier |
| 62 | + for all processes participating in the application. Instead, it's recommended each division (e.g. a worker |
| 63 | + thread in unicorn) to have its own instance.id. |
| 64 | +
|
| 65 | + It's not recommended for a Collector to set `service.instance.id` if it can't unambiguously determine the |
| 66 | + service instance that is generating that telemetry. For instance, creating an UUID based on `pod.name` will |
| 67 | + likely be wrong, as the Collector might not know from which container within that pod the telemetry originated. |
| 68 | + However, Collectors can set the `service.instance.id` if they can unambiguously determine the service instance |
| 69 | + for that telemetry. This is typically the case for scraping receivers, as they know the target address and |
| 70 | + port. |
| 71 | + examples: ["627cc493-f310-47de-96bd-71410b7dec09"] |
0 commit comments