Documentation

Overview

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

    Index

    Constants

    This section is empty.

    Variables

    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")
    )

    Functions

    This section is empty.

    Types

    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

      func StringDetector(k attribute.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

            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

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

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

                type Option

                type Option interface {
                	// Apply sets the Option value of a config.
                	Apply(*config)
                	// contains filtered or unexported methods
                }

                  Option is the interface that applies a configuration option.

                  func WithAttributes

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

                    WithAttributes adds attributes to the configured Resource.

                    func WithDetectors

                    func WithDetectors(detectors ...Detector) Option

                      WithDetectors adds detectors to be evaluated for the configured resource.

                      func WithFromEnv

                      func WithFromEnv(d Detector) Option

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

                        func WithHost

                        func WithHost(d Detector) Option

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

                          func WithTelemetrySDK

                          func WithTelemetrySDK(d Detector) Option

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

                            func WithoutBuiltin

                            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 Default

                                func Default() *Resource

                                  Default returns an instance of Resource with a default "service.name" and OpenTelemetrySDK attributes

                                  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 b will overwrite the value from resource a, even if resource b's value is empty.

                                        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

                                          func NewWithAttributes(attrs ...attribute.KeyValue) *Resource

                                            NewWithAttributes creates a resource from attrs. If attrs contains duplicate keys, the last value will be used. If attrs contains any invalid items those items will be dropped.

                                            func (*Resource) Attributes

                                            func (r *Resource) Attributes() []attribute.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 attribute.Encoder) string

                                                Encoded returns an encoded representation of the resource.

                                                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() attribute.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() attribute.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) 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 the resource attributes as a JSON list of { "Key": "...", "Value": ... } pairs in order sorted by key.

                                                          func (*Resource) Set

                                                          func (r *Resource) Set() *attribute.Set

                                                            Set returns the equivalent *attribute.Set of this resources attributes.

                                                            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

                                                              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

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