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

Clarify telemetry library resource attributes #494

Merged
merged 8 commits into from
Mar 24, 2020
Merged

Clarify telemetry library resource attributes #494

Changes from 7 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
52098d9
Clarify telemetry library resource attributes
arminru Feb 28, 2020
884b7dd
Fix typo
arminru Feb 28, 2020
523c97f
Clarify non-default SDK name
arminru Feb 28, 2020
f83ebd9
`opentelemetry-sdk` -> `opentelemetry`
arminru Mar 5, 2020
866acd3
Merge branch 'master' into clarify-library-name
arminru Mar 5, 2020
0c1f94c
Merge branch 'master' into clarify-library-name
arminru Mar 10, 2020
6f194ef
Refine description
arminru Mar 11, 2020
3ab4654
Clarify responsibilities
arminru Mar 12, 2020
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
23 changes: 16 additions & 7 deletions specification/data-resource-semantic-conventions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ This document defines standard attributes for resources. These attributes are ty
[OpenCensus Resource standard](https://github.com/census-instrumentation/opencensus-specs/blob/master/resource/StandardResources.md).
arminru marked this conversation as resolved.
Show resolved Hide resolved

* [Service](#service)
* [Library](#library)
* [Telemetry SDK](#telemetry-sdk)
* [Compute Unit](#compute-unit)
* [Container](#container)
* [Deployment Service](#deployment-service)
Expand Down Expand Up @@ -57,17 +57,26 @@ namespace = Company
service.name = Shop.shoppingcart
```

## Library
## Telemetry SDK

**type:** `library`
**type:** `telemetry.sdk`
arminru marked this conversation as resolved.
Show resolved Hide resolved

**Description:** Telemetry library information.
**Description:** The telemetry SDK used to capture data recorded by the instrumentation libraries.

If the default OpenTelemetry SDK provided by the OpenTelemetry project is used,
Copy link
Member

Choose a reason for hiding this comment

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

Wait, if the instrumentation adapter is used - will it be the name of the adapter than?

Copy link
Member Author

Choose a reason for hiding this comment

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

@SergeyKanzhelev Please clarify what you mean by instrumentation adapter, this term is completely new to me.
Do you refer to any of the things defined in our glossary (https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/glossary.md) or something else?

`telemetry.sdk.name` MUST be set to `opentelemetry`.
Copy link
Contributor

Choose a reason for hiding this comment

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

What is responsible for setting mandatory resource attributes? Is the default SDK required to set these values? I think it's unclear where the responsibility lies for a lot of these things. A sentence or two of clarification would be very helpful.

Copy link
Member Author

Choose a reason for hiding this comment

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

Good point! I rephrased it accordingly.


If another SDK, like a fork or a vendor-provided implementation, is used, `telemetry.sdk.name`
MUST be set to the fully-qualified class or module name of that SDK's main entry point
or another suitable identifier depending on the language.
Copy link
Member

Choose a reason for hiding this comment

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

Nit: I wonder if we should recommend fully-qualified name if we ourselves don't use it. Not a big deal, works either way for me.

Copy link
Member Author

Choose a reason for hiding this comment

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

That's fine I think, given that the default SDK will be the most commonly used one out there it deserves a special status.
I defined a hard-coded string for the OpenTelemetry default SDK in order to have a single uniform value across all language implementations. This makes it easier in case someone wants to build handling around that in a backend.

The identifier `opentelemetry` is reserved and MUST NOT be used in this case.
The identifier SHOULD be stable across different versions of an implementation.

| Attribute | Description | Example | Required? |
|---|---|---|---|
| library.name | The name of the telemetry library. | `opentelemetry` | No |
| library.language | The language of telemetry library and of the code instrumented with it. <br/> The following spelling SHOULD be used for language strings: "cpp", "dotnet", "erlang", "go", "java", "nodejs", "php", "python", "ruby", "webjs" | `java` | No |
| library.version | The version string of the library as defined in [Version Attributes](#version-attributes). | `semver:1.2.3` | No |
| telemetry.sdk.name | The name of the telemetry SDK as defined above. | `opentelemetry` | No |
| telemetry.sdk.language | The language of the telemetry SDK.<br/> One of the following values MUST be used, if one applies: "cpp", "dotnet", "erlang", "go", "java", "nodejs", "php", "python", "ruby", "webjs" | `java` | No |
| telemetry.sdk.version | The version string of the telemetry SDK as defined in [Version Attributes](#version-attributes). | `semver:1.2.3` | No |
arminru marked this conversation as resolved.
Show resolved Hide resolved

## Compute Unit

Expand Down