Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add telemetry.source attribute namespace #2192

Closed
wants to merge 1 commit into from
Closed

Add telemetry.source attribute namespace #2192

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 20 additions & 2 deletions specification/resource/semantic_conventions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,25 @@ as specified in [OpenTelemetry Environment Variable Specification](../../sdk-env
These are the attributes which MUST be provided by the SDK
as specified in the [Resource SDK specification](../sdk.md#sdk-provided-resource-attributes):

- [`service.name`](#service)
- [`telemetry.source.name`](#telemetry-source)

## Telemetry Source

**type:** `telemetry.source`

**Description:** Generic description of the source of the telemetry data.

Attributes in this namespace are intended to describe the telemetry source indpendently of the type of the resource (service, client-side etc.).

<!-- semconv service -->
| Attribute | Type | Description | Examples | Required |
|---|---|---|---|---|
| `telemetry.source.name` | string | Logical name of the source of the telemetry data. [1] | `shoppingcart` | Yes |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would be the telemetry.source.name for a metric collected from a Kubernetes cluster, e.g. CPU usage of a Kubernetes Node? We have k8s.node.* attributes for this. Will telemetry.source.name be a duplicate of k8s.node.name? Similarly, will telemetry.source.namespace be a duplicate of k8s.namespace?

Are we requiring that every specific technology for which we already have well-defined set of identifying attributes also duplicates the values of those attributes in telemetry.source.name and telemetry.source.namespace? We have such specific definitions for several Kubernetes entities, for OS processes, for FaaS functions, etc. I fail to see how this attempt to generalize works in the presence of those specific semantic conventions.

| `telemetry.source.namespace` | string | A namespace for `telemetry.source.name`. [2] | `Shop` | No |

**[1]:** If the value was not specified, SDKs MUST fallback to `unknown_source`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we had proposed this would fallback to service.name here, for backwards compatibility with the previous specification.


**[2]:** A string value having a meaning that helps to distinguish a group of related sources, for example the team name that owns a group of services. `telemetry.source.name` is expected to be unique within the same namespace. If `telemetry.source.namespace` is not specified in the Resource then `telemetry.source.name` is expected to be unique for all sources 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.

## Service

Expand All @@ -65,7 +83,7 @@ as specified in the [Resource SDK specification](../sdk.md#sdk-provided-resource
<!-- semconv service -->
| Attribute | Type | Description | Examples | Required |
|---|---|---|---|---|
| `service.name` | string | Logical name of the service. [1] | `shoppingcart` | Yes |
| `service.name` | string | Logical name of the service. [1] | `shoppingcart` | No |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we remove this as required, we'll need to document what we migrated to.

Again, if we think of the specification as an API users consume, then we need to verify this isn't breaking.

We discussed using telemetry.source.* as the new service.name, but what does removing this as required due to expectations of users? I think in the meeting we had talked about some kind of backfill mechanic where telemetry.source.* would be inserting here on-demand to prevent breakages.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jsuereth I am not sure how to verify that it's not breaking in all SDKs. I am guessing that if implemented correctly, it will default to unknown_service when not provided. I think potentially the bigger challenge is that backends might be expecting service.name to be present. So, perhaps I can leave it as required for resources that describe an actual service, with the value being the same as telemetry.source.name.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'd suggest the later. One of my crazy ideas was to have something where when a user asks for service.name they automatically get telemetry.source.name at the API level, e.g. see: open-telemetry/oteps#161 which did not get enough approvals, but would have helped us in this scenario.

| `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` | No |
| `service.version` | string | The version string of the service API or implementation. | `2.0.0` | No |
Expand Down