resource

package
v1.16.0 Latest Latest
Warning

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

 Go to latest Published: May 22, 2023 License: Apache-2.0 Imports: 18 Imported by: 2,885

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

While this package provides a stable API, the attributes added by resource detectors may change.

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 added in v0.14.0 

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 added in v0.14.0 

type Option interface {
	// contains filtered or unexported methods
}

Option is the interface that applies a configuration option.

func WithAttributes added in v0.14.0 

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

WithAttributes adds attributes to the configured Resource.

func WithContainer added in v1.5.0 

func WithContainer() Option

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

func WithContainerID added in v1.5.0 

func WithContainerID() Option

WithContainerID adds an attribute with the id of the container to the configured Resource. Note: WithContainerID will not extract the correct container ID in an ECS environment. Please use the ECS resource detector instead (https://pkg.go.dev/go.opentelemetry.io/contrib/detectors/aws/ecs).

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() Option

WithFromEnv adds attributes from environment variables to the configured resource.

func WithHost added in v0.14.0 

func WithHost() Option

WithHost adds attributes from the host to the configured resource.

func WithHostID added in v1.15.0 

func WithHostID() Option

WithHostID adds host ID information to the configured resource.

func WithOS added in v1.0.0 

func WithOS() Option

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

func WithOSDescription added in v1.0.0 

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 added in v0.20.0 

func WithOSType() Option

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

func WithProcess added in v0.20.0 

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 added in v0.20.0 

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 added in v0.20.0 

func WithProcessExecutableName() Option

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

func WithProcessExecutablePath added in v0.20.0 

func WithProcessExecutablePath() Option

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

func WithProcessOwner added in v0.20.0 

func WithProcessOwner() Option

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

func WithProcessPID added in v0.20.0 

func WithProcessPID() Option

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

func WithProcessRuntimeDescription added in v0.20.0 

func WithProcessRuntimeDescription() Option

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

func WithProcessRuntimeName added in v0.20.0 

func WithProcessRuntimeName() Option

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

func WithProcessRuntimeVersion added in v0.20.0 

func WithProcessRuntimeVersion() Option

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

func WithSchemaURL added in v1.0.0 

func WithSchemaURL(schemaURL string) Option

WithSchemaURL sets the schema URL for the configured resource.

func WithTelemetrySDK added in v0.14.0 

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 added in v0.18.0 

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 added in v0.20.0 

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/v1.20.0/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 added in v1.0.0 

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 added in v0.14.0 

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 added in v1.4.0 

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

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

func (*Resource) SchemaURL added in v1.0.0 

func (r *Resource) SchemaURL() string

SchemaURL returns the schema URL associated with Resource r.

func (*Resource) Set added in v0.19.0 

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.