From c7018b3c7b4ff41cc174b53c35a347a21233f868 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Mon, 14 Dec 2020 16:59:35 +0100 Subject: [PATCH] Define the fallback case for service.name (#1269) --- CHANGELOG.md | 3 +++ semantic_conventions/resource/service.yaml | 4 +++- specification/resource/sdk.md | 3 +++ specification/resource/semantic_conventions/README.md | 11 +++++++++-- 4 files changed, 18 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fe047dcf885..50b8d5b9e96 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,9 @@ Updates: ([#1257](https://github.com/open-telemetry/opentelemetry-specification/pull/1257)) - Add/Update `Status` + `error` mapping for Jaeger & Zipkin Exporters ([#1257](https://github.com/open-telemetry/opentelemetry-specification/pull/1257)) +- Resource's service.name MUST have a default value, service.instance.id is not + required. + ([#1269](https://github.com/open-telemetry/opentelemetry-specification/pull/1269)) ## v0.7.0 (11-18-2020) diff --git a/semantic_conventions/resource/service.yaml b/semantic_conventions/resource/service.yaml index 78983d4d9b2..efc53055fd5 100644 --- a/semantic_conventions/resource/service.yaml +++ b/semantic_conventions/resource/service.yaml @@ -11,6 +11,9 @@ groups: Logical name of the service. note: > 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#process), e.g. `unknown_service:bash`. + If `process.executable.name` is not available, the value MUST be set to `unknown_service`. examples: ["shoppingcart"] - id: namespace type: string @@ -27,7 +30,6 @@ groups: examples: ["Shop"] - id: instance.id type: string - required: always brief: > The string ID of the service instance. note: > diff --git a/specification/resource/sdk.md b/specification/resource/sdk.md index 0932056a0bc..85e7e9b1e20 100644 --- a/specification/resource/sdk.md +++ b/specification/resource/sdk.md @@ -34,6 +34,9 @@ The interface MUST provide a way to create a new resource, from [`Attributes`](. Examples include a factory method or a constructor for a resource object. A factory method is recommended to enable support for cached objects. +Note that certain **required** `Resource` attributes MUST be set to a default value if they were not specified. +See [Attributes with Default Value](semantic_conventions/README.md#attributes-with-default-value). + Required parameters: - [`Attributes`](../common/common.md#attributes) diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index 24b98e93952..97617d694a6 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -9,6 +9,7 @@ This document defines standard attributes for resources. These attributes are ty - [TODOs](#todos) - [Document Conventions](#document-conventions) +- [Attributes with Default Value](#attributes-with-default-value) - [Service](#service) - [Telemetry SDK](#telemetry-sdk) - [Compute Unit](#compute-unit) @@ -32,6 +33,12 @@ Attributes are grouped logically by the type of the concept that they described. Certain attribute groups in this document have a **Required** column. For these groups if any attribute from the particular group is present in the Resource then all attributes that are marked as Required MUST be also present in the Resource. However it is also valid if the entire attribute group is omitted (i.e. none of the attributes from the particular group are present even though some of them are marked as Required in this document). +## Attributes with Default Value + +The SDK MUST set a default value for the following attributes if they were not specified, even if the resource would otherwise not be present at all: + +- [`service.name`](#service) + ## Service **type:** `service` @@ -43,10 +50,10 @@ Certain attribute groups in this document have a **Required** column. For these |---|---|---|---|---| | `service.name` | string | Logical name of the service. [1] | `shoppingcart` | Yes | | `service.namespace` | string | A namespace for `service.name`. [2] | `Shop` | No | -| `service.instance.id` | string | The string ID of the service instance. [3] | `627cc493-f310-47de-96bd-71410b7dec09` | Yes | +| `service.instance.id` | string | The string ID of the service instance. [3] | `627cc493-f310-47de-96bd-71410b7dec09` | No | | `service.version` | string | The version string of the service API or implementation. | `2.0.0` | No | -**[1]:** MUST be the same for all instances of horizontally scaled services. +**[1]:** 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#process), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. **[2]:** 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.