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 that resources are immutable #515

Merged
merged 6 commits into from
Mar 27, 2020
+25 −18
Merged

Clarify that resources are immutable #515

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8926dde
Clarify that resources are immutable
Oberon00 Mar 12, 2020
b29d464
Typo.
Oberon00 Mar 12, 2020
362acfc
Update specification/sdk-resource.md
Oberon00 Mar 12, 2020
93b252e
Mention immutability right in the beginning.
Oberon00 Mar 12, 2020
9a5207e
Reformulate Merge to make immutability more clear
Oberon00 Mar 12, 2020
9610768
Merge branch 'master' into patch-5
bogdandrutu Mar 24, 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
43 changes: 25 additions & 18 deletions specification/sdk-resource.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Resource SDK

A [Resource](overview.md#resources) represents the entity producing
A [Resource](overview.md#resources) is an immutable representation of the entity producing
telemetry. For example, a process producing telemetry that is running in a
container on Kubernetes has a Pod name, it is in a namespace and possibly is
part of a Deployment which also has a name. All three of these attributes can be
Expand All @@ -13,13 +13,15 @@ with closed source environments. The SDK MUST allow for creation of `Resources`
for associating them with telemetry.

When used with distributed tracing, a resource can be associated with the
[TracerProvider](sdk-tracing.md#tracer-sdk). When associated with a
`TracerProvider`, all `Span`s produced by any `Tracer` from the provider will
automatically be associated with this `Resource`.

When used with metrics, a resource can be associated with the
[MeterProvider](sdk-metrics.md#meter-sdk). When associated with a `MeterProvider`,
all `Metrics` produced by any `Meter` from the provider will automatically be
[TracerProvider](sdk-tracing.md#tracer-sdk) when it is created.
That association cannot be changed later.
Copy link
Member Author

@Oberon00 Oberon00 Mar 17, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

Is this sentence OK? There was a discussion in SIG meeting about Kubernetes Pod labels that can change. This would mean that we cannot put them on resources.

Copy link
Contributor

Choose a reason for hiding this comment

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

The conversation about resource labels that can change suggests to me that we should support per-Tracer resources as prototyped in open-telemetry/oteps#78. When the pod label changes, you would construct a new scope with the new resources and begin using that tracer. Modifying "static" resources on the fly sounds problematic, to me.

Copy link
Member

Choose a reason for hiding this comment

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

Not necessary, I can see that pod_labels be logs/events associated with the same immutable Resource. Not saying that scope is not useful but probably not for the pod labels example.

Copy link
Member Author

Choose a reason for hiding this comment

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

Actually, having global events sounds like a useful idea. You should make an issue for that.

Copy link
Member

Choose a reason for hiding this comment

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

Also these events are more or less some type of "time-series" being associated with the time when they change. Not trying to design the solution here, but just some "food for thought" :)

When associated with a `TracerProvider`,
all `Span`s produced by any `Tracer` from the provider MUST be associated with this `Resource`.

Analogous to distributed tracing, when used with metrics,
a resource can be associated with a [MeterProvider](sdk-metrics.md#meter-sdk).
When associated with a `MeterProvider`,
all `Metrics` produced by any `Meter` from the provider will be
associated with this `Resource`.

## Resource creation
Expand All @@ -39,23 +41,27 @@ Required parameters:

### Merge

The interface MUST provide a way for a primary resource to merge with a
secondary resource, resulting in the creation of a brand new resource. The
original resources should be unmodified.
The interface MUST provide a way for a primary resource and a
secondary resource to be merged into a new resource.

Note: This is intended to be utilized for merging of resources whose attributes
come from different sources,
such as environment variables, or metadata extracted from the host or container.

This is utilized for merging of resources whose attributes come from different
sources, such as environment variables, or metadata extracted from the host or
container.
The resulting resource MUST have all attributes that are on any of the two input resources.
Conflicts (i.e. a key for which attributes exist on both the primary and secondary resource)
MUST be handled as follows:

Already set attributes MUST NOT be overwritten unless they are the empty string.
* If the value on the primary resource is an empty string, the result has the value of the secondary resource.
* Otherwise, the value of the primary resource is used.

Attribute key namespacing SHOULD be used to prevent collisions across different
resource detection steps.

Required parameters:

- the primary resource whose attributes takes precedence.
- the secondary resource whose attributes will be merged.
- the primary resource whose attributes take precedence.
- the secondary resource whose attributes will be merged in.

### The empty resource

Expand All @@ -67,7 +73,8 @@ attributes"](data-semantic-conventions.md) that have prescribed semantic meaning

## Resource operations

In addition to resource creation, the following operations should be provided:
Resources are immutable. Thus, in addition to resource creation,
arminru marked this conversation as resolved.
Show resolved Hide resolved
only the following operations should be provided:

### Retrieve attributes

Expand Down