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
  • func StringDetector(schemaURL string, k attribute.Key, f func() (string, error)) Detector
• type Option
  • func WithAttributes(attributes ...attribute.KeyValue) Option
  • func WithContainer() Option
  • func WithContainerID() Option
  • func WithDetectors(detectors ...Detector) Option
  • func WithFromEnv() Option
  • func WithHost() Option
  • func WithOS() Option
  • func WithOSDescription() 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 WithSchemaURL(schemaURL string) Option
  • func WithTelemetrySDK() 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, error)
  • func New(ctx context.Context, opts ...Option) (*Resource, error)
  • func NewSchemaless(attrs ...attribute.KeyValue) *Resource
  • func NewWithAttributes(schemaURL string, 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) MarshalLog() interface{}
  • func (r *Resource) SchemaURL() string
  • func (r *Resource) Set() *attribute.Set
  • func (r *Resource) String() string

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(schemaURL string, 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. The resulting Resource will have the specified schemaURL.

type Option

type Option interface {
	// 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 WithContainer

func WithContainer() Option

WithContainer adds all the Container attributes to the configured Resource. See individual WithContainer* functions to configure specific attributes.

func WithContainerID

func WithContainerID() Option

WithContainerID adds an attribute with the id of the container 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() Option

WithFromEnv adds attributes from environment variables to the configured resource.

func WithHost

func WithHost() Option

WithHost adds attributes from the host to the configured resource.

func WithOS

func WithOS() Option

WithOS adds all the OS attributes to the configured Resource. See individual WithOS* functions to configure specific attributes.

func WithOSDescription

func WithOSDescription() Option

WithOSDescription adds an attribute with the operating system description to the configured Resource. The formatted string is equivalent to the output of the `uname -snrvm` command.

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.

Warning! This option will include process command line arguments. If these contain sensitive information it will be included in the exported resource.

This option is equivalent to calling WithProcessPID, WithProcessExecutableName, WithProcessExecutablePath, WithProcessCommandArgs, WithProcessOwner, WithProcessRuntimeName, WithProcessRuntimeVersion, and WithProcessRuntimeDescription. See each option function for information about what resource attributes each includes.

func WithProcessCommandArgs

func WithProcessCommandArgs() Option

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

Warning! This option will include process command line arguments. If these contain sensitive information it will be included in the exported 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 WithSchemaURL

func WithSchemaURL(schemaURL string) Option

WithSchemaURL sets the schema URL for the configured resource.

func WithTelemetrySDK

func WithTelemetrySDK() Option

WithTelemetrySDK adds TelemetrySDK version info to the configured resource.

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, error)

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.

The SchemaURL of the resources will be merged according to the spec rules: https://github.com/open-telemetry/opentelemetry-specification/blob/bad49c714a62da5493f2d1d9bafd7ebe8c8ce7eb/specification/resource/sdk.md#merge If the resources have different non-empty schemaURL an empty resource and an error will be returned.

func New

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

New returns a Resource combined from the user-provided detectors.

func NewSchemaless

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

NewSchemaless 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. The resource will not be associated with a schema URL. If the schema of the attrs is known use NewWithAttributes instead.

func NewWithAttributes

func NewWithAttributes(schemaURL string, attrs ...attribute.KeyValue) *Resource

NewWithAttributes creates a resource from attrs and associates the resource with a schema URL. If attrs contains duplicate keys, the last value will be used. If attrs contains any invalid items those items will be dropped. The attrs are assumed to be in a schema identified by schemaURL.

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 iterator 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) MarshalLog

func (r *Resource) MarshalLog() interface{}

MarshalLog is the marshaling function used by the logging system to represent this exporter.

func (*Resource) SchemaURL

func (r *Resource) SchemaURL() string

SchemaURL returns the schema URL associated with Resource r.

func (*Resource) Set

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

Set returns the equivalent *attribute.Set of this resource's 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.