resource

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

• Variables
• type Detector
  • func StringDetector(k attribute.Key, f func() (string, error)) Detector
• type FromEnv
  • func (FromEnv) Detect(context.Context) (*Resource, error)
• type Host
  • func (Host) Detect(ctx context.Context) (*Resource, error)
• type Option
  • func WithAttributes(attributes ...attribute.KeyValue) Option
  • func WithDetectors(detectors ...Detector) Option
  • func WithFromEnv(d Detector) Option
  • func WithHost(d Detector) Option
  • func WithOSType() Option
  • func WithProcess() Option
  • func WithProcessCommandArgs() Option
  • func WithProcessExecutableName() Option
  • func WithProcessExecutablePath() Option
  • func WithProcessOwner() Option
  • func WithProcessPID() Option
  • func WithProcessRuntimeDescription() Option
  • func WithProcessRuntimeName() Option
  • func WithProcessRuntimeVersion() Option
  • func WithTelemetrySDK(d Detector) Option
  • func WithoutBuiltin() Option
• type Resource
  • func Default() *Resource
  • func Detect(ctx context.Context, detectors ...Detector) (*Resource, error)
  • func Empty() *Resource
  • func Environment() *Resource
  • func Merge(a, b *Resource) *Resource
  • func New(ctx context.Context, opts ...Option) (*Resource, error)
  • func NewWithAttributes(attrs ...attribute.KeyValue) *Resource
  • func (r *Resource) Attributes() []attribute.KeyValue
  • func (r *Resource) Encoded(enc attribute.Encoder) string
  • func (r *Resource) Equal(eq *Resource) bool
  • func (r *Resource) Equivalent() attribute.Distinct
  • func (r *Resource) Iter() attribute.Iterator
  • func (r *Resource) Len() int
  • func (r *Resource) MarshalJSON() ([]byte, error)
  • func (r *Resource) Set() *attribute.Set
  • func (r *Resource) String() string
• type TelemetrySDK
  • func (TelemetrySDK) Detect(context.Context) (*Resource, error)

Variables

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

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 WithOSType

func WithOSType() Option

WithOSType adds an attribute with the operating system type to the configured Resource.

func WithProcess

func WithProcess() Option

WithProcess adds all the Process attributes to the configured Resource. See individual WithProcess* functions to configure specific attributes.

func WithProcessCommandArgs

func WithProcessCommandArgs() Option

WithProcessCommandArgs adds an attribute with all the command arguments (including the command/executable itself) as received by the process the configured Resource.

func WithProcessExecutableName

func WithProcessExecutableName() Option

WithProcessExecutableName adds an attribute with the name of the process executable to the configured Resource.

func WithProcessExecutablePath

func WithProcessExecutablePath() Option

WithProcessExecutablePath adds an attribute with the full path to the process executable to the configured Resource.

func WithProcessOwner

func WithProcessOwner() Option

WithProcessOwner adds an attribute with the username of the user that owns the process to the configured Resource.

func WithProcessPID

func WithProcessPID() Option

WithProcessPID adds an attribute with the process identifier (PID) to the configured Resource.

func WithProcessRuntimeDescription

func WithProcessRuntimeDescription() Option

WithProcessRuntimeDescription adds an attribute with an additional description about the runtime of the process to the configured Resource.

func WithProcessRuntimeName

func WithProcessRuntimeName() Option

WithProcessRuntimeName adds an attribute with the name of the runtime of this process to the configured Resource.

func WithProcessRuntimeVersion

func WithProcessRuntimeVersion() Option

WithProcessRuntimeVersion adds an attribute with the version of the runtime of this process to the configured Resource.

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 Environment

func Environment() *Resource

Environment returns an instance of Resource with attributes extracted from the OTEL_RESOURCE_ATTRIBUTES environment variable.

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

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

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