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.

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

resource terminology and API #56

Merged
merged 2 commits into from
Jun 3, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
3 changes: 2 additions & 1 deletion specification/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,5 @@ describes the key types and the overall behavior.

Main APIs:

- [Tracing API](tracing-api.md).
- [Tracing API](tracing-api.md).
- [Resources API](resources-api.md).
75 changes: 75 additions & 0 deletions specification/resources-api.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# Resources API

[Resource](../terminology.md#resources) represents the entity producing
telemetry. The primary purpose of resources as a first-class concept in the API
is decoupling of discovery of resource information from exporters. This allows
for independent development and easy customization for users that need to
integrate with closed source environments. API MUST allow creation of
`Resources` and associating them with telemetry.

When used with distributed tracing resource can be associated with the
[Tracer](tracing-api.md#tracer) or individual
[SpanData](tracing-api.md#spandata). When associated with `Tracer`, all `Span`s
SergeyKanzhelev marked this conversation as resolved.
Show resolved Hide resolved
produced by this `Tracer` will automatically be associated with this `Resource`.
When associated with the `SpanData` explicitly for out-of-band spans -
`Resource` that is set on `Tracer` MUST be ignored.

**TODO**: explain how resource is associated with metrics.
Copy link
Member Author

Choose a reason for hiding this comment

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

Let's add it later. I don't want to introduce an empty metrics-api.md document in this PR.


## Resources SDK

TODO: notes how Resources API is extended when using `SDK`. https://github.com/open-telemetry/opentelemetry-specification/issues/61

## Resource creation

API defines two ways to instantiate an instance of `Resource`. First, by
providing a collection of labels - method [Create](#create). The typical use of
this method is by creating resource from the list of labels taken from
environment variables, metadata API call response, or other sources.

Second, by merging two `Resource`s into a new one. The method [Merge](#merge) is
used when a `Resource` is constructed from multiple sources - metadata API call
for the host and environment variables for the container. So a single `Resource`
will contain labels for both.
Copy link
Member

Choose a reason for hiding this comment

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

What is the reason for doing this on resource level (extending API surface with the Merge() function) instead of doing the merge on the collection of labels?

Copy link
Member Author

Choose a reason for hiding this comment

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

Merge has a logic on how to deal with empty or duplicate values. In OC it was also doiung a merge of a field type.

I agree it's not much to justify this API today. But it is what we have in Java reference API. Do you want to track it as a "API feedback issue"? Please file an issue

Copy link
Member

Choose a reason for hiding this comment

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

Merge has a logic on how to deal with empty or duplicate values. In OC it was also doiung a merge of a field type.

That's just an artifact of having a merge in the first place, no? If it was up to the user to provide a map of labels, then they would have to deal with duplicates, not the spec. And the type would only be specified once.

Copy link
Member

Choose a reason for hiding this comment

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

booked #62


Lastly, it is a good practice for API to allow easy creation of a default or
empty `Resource`.

Note that the OpenTelemetry project documents certain ["standard
labels"](../semantic-conventions.md) that have prescribed semantic meanings.

### Create

Creates a new `Resource` out of the collection of labels. This is a static
method.

Required parameter:

Collection of name/value labels where both name and value are strings.

### Merge

Creates a new `Resource` that is a combination of labels of two `Resource`s. For
example, from two `Resource`s - one representing the host and one representing a
container, resulting `Resource` will describe both.

Already set labels MUST NOT be overwritten unless they are empty string. Label
key namespacing SHOULD be used to prevent collisions across different resource
detection steps.


Required parameter:

`Resource` to merge into the one, on which the method was called.

## Resource operations

API defines a resource class with a single getter for the list of labels
associated with this resource. `Resource` object should be assumed immutable.

### GetLabels

Returns the read only collection of labels associated with this resource. Each
label is a string to string name value pair. The order of labels in collection
is not significant. The typical use of labels collection is enumeration so the
fast access to the label value by it's key is not a requirement.
17 changes: 16 additions & 1 deletion terminology.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,22 @@ TODO: Describe tags terminology https://github.com/open-telemetry/opentelemetry-

## Resources

TODO: Describe resources terminology https://github.com/open-telemetry/opentelemetry-specification/issues/47
`Resource` captures information about the entity for which telemetry is
recorded. For example, metrics exposed by a Kubernetes container can be linked
to a resource that specifies the cluster, namespace, pod, and container name.

`Resource` may capture an entire hierarchy of entity identification. It may
describe the host in the cloud and specific container or an application running
in the process.

Note, that some of the process identification information can be associated with
telemetry automatically by OpenTelemetry SDK or specific exporter. See
OpenTelemetry
[proto](https://github.com/open-telemetry/opentelemetry-proto/blob/a46c815aa5e85a52deb6cb35b8bc182fb3ca86a0/src/opentelemetry/proto/agent/common/v1/common.proto#L28-L96)
SergeyKanzhelev marked this conversation as resolved.
Show resolved Hide resolved
for an example.

**TODO**: Better describe the difference between the resource and a Node
https://github.com/open-telemetry/opentelemetry-proto/issues/17

## Agent/Collector

Expand Down
14 changes: 0 additions & 14 deletions work_in_progress/specification/resource/README.md

This file was deleted.

6 changes: 0 additions & 6 deletions work_in_progress/specification/resource/Resource.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,12 +58,6 @@ Auto-detection of resource information in specific environments, e.g. specific c
vendors, MUST be implemented outside of the core libraries in third party or
[census-ecosystem][census-ecosystem] repositories.

### Merging
As different mechanisms are run to gain information about a resource, their information
has to be merged into a single resulting resource.
Already set labels or type fields MUST NOT be overwritten unless they are empty string. Label key
namespacing SHOULD be used to prevent collisions across different resource detection steps.

### Detectors
To make auto-detection implementations easy to use, the core resource package SHOULD define
an interface to retrieve resource information. Additionally, helper functionality MAY be
Expand Down