Version: v0.16.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Jan 14, 2021 License: Apache-2.0 Imports: 8 Imported by: 1,550



Package resource provides detecting and representing resources.

This package is currently in a pre-GA phase. Backwards incompatible changes may be introduced in subsequent minor version releases as we work to track the evolving OpenTelemetry specification and user feedback.

The fundamental struct is a Resource which holds identifying information about the entities for which telemetry is exported.

To automatically construct Resources from an environment a Detector interface is defined. Implementations of this interface can be passed to the Detect function to generate a Resource from the merged information.

To load a user defined Resource from the environment variable OTEL_RESOURCE_ATTRIBUTES the FromEnv Detector can be used. It will interpret the value as a list of comma delimited key/value pairs (e.g. `<key1>=<value1>,<key2>=<value2>,...`).



This section is empty.


View Source
var (
	// ErrPartialResource is returned by a detector when complete source
	// information for a Resource is unavailable or the source information
	// contains invalid values that are omitted from the returned Resource.
	ErrPartialResource = errors.New("partial resource")


This section is empty.


type Detector

type Detector interface {
	// Detect returns an initialized Resource based on gathered information.
	// If the source information to construct a Resource contains invalid
	// values, a Resource is returned with the valid parts of the source
	// information used for initialization along with an appropriately
	// wrapped ErrPartialResource error.
	Detect(ctx context.Context) (*Resource, error)

Detector detects OpenTelemetry resource information

func StringDetector added in v0.14.0

func StringDetector(k label.Key, f func() (string, error)) Detector

StringDetector returns a Detector that will produce a *Resource containing the string as a value corresponding to k.

type FromEnv

type FromEnv struct{}

FromEnv is a Detector that implements the Detector and collects resources from environment. This Detector is included as a builtin. If these resource attributes are not wanted, use the WithFromEnv(nil) or WithoutBuiltin() options to explicitly disable them.

func (FromEnv) Detect

func (FromEnv) Detect(context.Context) (*Resource, error)

Detect collects resources from environment

type Host added in v0.14.0

type Host struct{}

Host is a Detector that provides information about the host being run on. This Detector is included as a builtin. If these resource attributes are not wanted, use the WithHost(nil) or WithoutBuiltin() options to explicitly disable them.

func (Host) Detect added in v0.14.0

func (Host) Detect(ctx context.Context) (*Resource, error)

Detect returns a *Resource that describes the host being run on.

type Option added in v0.14.0

type Option interface {
	// Apply sets the Option value of a config.

Option is the interface that applies a configuration option.

func WithAttributes added in v0.14.0

func WithAttributes(attributes ...label.KeyValue) Option

WithAttributes adds attributes to the configured Resource.

func WithDetectors added in v0.14.0

func WithDetectors(detectors ...Detector) Option

WithDetectors adds detectors to be evaluated for the configured resource.

func WithFromEnv added in v0.14.0

func WithFromEnv(d Detector) Option

WithFromEnv overrides the builtin detector for OTEL_RESOURCE_ATTRIBUTES. Use nil to disable environment checking.

func WithHost added in v0.14.0

func WithHost(d Detector) Option

WithHost overrides the builtin `host.*` attributes. Use nil to disable these attributes entirely.

func WithTelemetrySDK added in v0.14.0

func WithTelemetrySDK(d Detector) Option

WithTelemetrySDK overrides the builtin `telemetry.sdk.*` attributes. Use nil to disable these attributes entirely.

func WithoutBuiltin added in v0.14.0

func WithoutBuiltin() Option

WithoutBuiltin disables all the builtin detectors, including the telemetry.sdk.*, host.*, and the environment detector.

type Resource

type Resource struct {
	// contains filtered or unexported fields

Resource describes an entity about which identifying information and metadata is exposed. Resource is an immutable object, equivalent to a map from key to unique value.

Resources should be passed and stored as pointers (`*resource.Resource`). The `nil` value is equivalent to an empty Resource.

func Detect

func Detect(ctx context.Context, detectors ...Detector) (*Resource, error)

Detect calls all input detectors sequentially and merges each result with the previous one. It returns the merged error too.

func Empty

func Empty() *Resource

Empty returns an instance of Resource with no attributes. It is equivalent to a `nil` Resource.

func Merge

func Merge(a, b *Resource) *Resource

Merge creates a new resource by combining resource a and b.

If there are common keys between resource a and b, then the value from resource a is preserved.

func New

func New(ctx context.Context, opts ...Option) (*Resource, error)

New returns a Resource combined from the provided attributes, user-provided detectors and builtin detectors.

func NewWithAttributes added in v0.14.0

func NewWithAttributes(kvs ...label.KeyValue) *Resource

NewWithAttributes creates a resource from a set of attributes. If there are duplicate keys present in the list of attributes, then the last value found for the key is preserved.

func (*Resource) Attributes

func (r *Resource) Attributes() []label.KeyValue

Attributes returns a copy of attributes from the resource in a sorted order. To avoid allocating a new slice, use an iterator.

func (*Resource) Encoded

func (r *Resource) Encoded(enc label.Encoder) string

Encoded returns an encoded representation of the resource by applying a label encoder. The result is cached by the underlying label set.

func (*Resource) Equal

func (r *Resource) Equal(eq *Resource) bool

Equal returns true when a Resource is equivalent to this Resource.

func (*Resource) Equivalent

func (r *Resource) Equivalent() label.Distinct

Equivalent returns an object that can be compared for equality between two resources. This value is suitable for use as a key in a map.

func (*Resource) Iter

func (r *Resource) Iter() label.Iterator

Iter returns an interator of the Resource attributes. This is ideal to use if you do not want a copy of the attributes.

func (*Resource) LabelSet

func (r *Resource) LabelSet() *label.Set

LabelSet returns the equivalent *label.Set.

func (*Resource) Len

func (r *Resource) Len() int

Len returns the number of unique key-values in this Resource.

func (*Resource) MarshalJSON

func (r *Resource) MarshalJSON() ([]byte, error)

MarshalJSON encodes labels as a JSON list of { "Key": "...", "Value": ... } pairs in order sorted by key.

func (*Resource) String

func (r *Resource) String() string

String implements the Stringer interface and provides a human-readable form of the resource.

Avoid using this representation as the key in a map of resources, use Equivalent() as the key instead.

type TelemetrySDK added in v0.14.0

type TelemetrySDK struct{}

TelemetrySDK is a Detector that provides information about the OpenTelemetry SDK used. This Detector is included as a builtin. If these resource attributes are not wanted, use the WithTelemetrySDK(nil) or WithoutBuiltin() options to explicitly disable them.

func (TelemetrySDK) Detect added in v0.14.0

Detect returns a *Resource that describes the OpenTelemetry SDK used.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL