resource

Documentation

Overview

Package resource provides detecting and representing resources.

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>,...`).

Index

• Variables
• type Detector
• type FromEnv
  • func (d *FromEnv) Detect(context.Context) (*Resource, error)
• type Resource
  • func Detect(ctx context.Context, detectors ...Detector) (*Resource, error)
  • func Empty() *Resource
  • func Merge(a, b *Resource) *Resource
  • func New(kvs ...label.KeyValue) *Resource
  • func (r *Resource) Attributes() []label.KeyValue
  • func (r *Resource) Encoded(enc label.Encoder) string
  • func (r *Resource) Equal(eq *Resource) bool
  • func (r *Resource) Equivalent() label.Distinct
  • func (r *Resource) Iter() label.Iterator
  • func (r *Resource) LabelSet() *label.Set
  • func (r *Resource) Len() int
  • func (r *Resource) MarshalJSON() ([]byte, error)
  • func (r *Resource) String() string

Variables

var (
	// ErrMissingResource is returned by a detector when source information
	// is unavailable for a Resource.
	ErrMissingResource = errors.New("missing resource")
	// 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")
)

Types

type Detector

type Detector interface {
	// Detect returns an initialized Resource based on gathered information.
	// If source information to construct a Resource is inaccessible, an
	// uninitialized Resource is returned with an appropriately wrapped
	// ErrMissingResource error is returned. 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

type FromEnv

type FromEnv struct{}

FromEnv is a detector that implements the Detector and collects resources from environment

func (*FromEnv) Detect

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

Detect collects resources from environment

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(kvs ...label.KeyValue) *Resource

New 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.