Resource 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 or individual
SpanData. When associated with Tracer, all Spans
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. Note, that association
of Tracer with the Resource will be done in SDK, not as API call.
TODO: explain how resource is associated with metrics.
TODO: notes how Resources API is extended when using SDK. open-telemetry#61
API defines two ways to instantiate an instance of Resource. First, by
providing a collection of labels - method 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 Resources into a new one. The method 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.
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" that have prescribed semantic meanings.
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.
Creates a new Resource that is a combination of labels of two Resources. For
example, from two Resources - 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.
API defines a resource class with a single getter for the list of labels
associated with this resource. Resource object should be assumed immutable.
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.