resource

README

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

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

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

Examples

• New

Variables

var ErrPartialResource = errors.New("partial 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.

var ErrSchemaURLConflict = errors.New("conflicting Schema URL")

ErrSchemaURLConflict is an error returned when two Resources are merged together that contain different, non-empty, schema URLs.

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

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 WithHostID

func WithHostID() Option

WithHostID adds host ID information 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 returns a new Resource merged from all the Resources each of the detectors produces. Each of the detectors are called sequentially, in the order they are passed, merging the produced resource into the previous.

This may return a partial Resource along with an error containing ErrPartialResource if that error is returned from a detector. It may also return a merge-conflicting Resource along with an error containing ErrSchemaURLConflict if merging Resources from different detectors results in a schema URL conflict. It is up to the caller to determine if this returned Resource should be used or not.

If one of the detectors returns an error that is not ErrPartialResource, the resource produced by the detector will not be merged and the returned error will wrap that detector's error.

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 merging a and b.

If there are common keys between a and b, then the value from b will overwrite the value from a, even if b's value is empty.

The SchemaURL of the resources will be merged according to the OpenTelemetry specification rules:

• If a's schema URL is empty then the returned Resource's schema URL will be set to the schema URL of b,
• Else if b's schema URL is empty then the returned Resource's schema URL will be set to the schema URL of a,
• Else if the schema URLs of a and b are the same then that will be the schema URL of the returned Resource,
• Else this is a merging error. If the resources have different, non-empty, schema URLs an error containing ErrSchemaURLConflict will be returned with the merged Resource. The merged Resource will have an empty schema URL. It may be the case that some unintended attributes have been overwritten or old semantic conventions persisted in the returned Resource. It is up to the caller to determine if this returned Resource should be used or not.

func New

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

New returns a Resource built using opts.

This may return a partial Resource along with an error containing ErrPartialResource if options that provide a Detector are used and that error is returned from one or more of the Detectors. It may also return a merge-conflict Resource along with an error containing ErrSchemaURLConflict if merging Resources from the opts results in a schema URL conflict (see [Resource.Merge] for more information). It is up to the caller to determine if this returned Resource should be used or not based on these errors.

Example

package main

import (
	"context"
	"errors"
	"fmt"
	"log"

	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/sdk/resource"
)

func main() {
	res, err := resource.New(
		context.Background(),
		resource.WithFromEnv(),      // Discover and provide attributes from OTEL_RESOURCE_ATTRIBUTES and OTEL_SERVICE_NAME environment variables.
		resource.WithTelemetrySDK(), // Discover and provide information about the OpenTelemetry SDK used.
		resource.WithProcess(),      // Discover and provide process information.
		resource.WithOS(),           // Discover and provide OS information.
		resource.WithContainer(),    // Discover and provide container information.
		resource.WithHost(),         // Discover and provide host information.
		resource.WithAttributes(attribute.String("foo", "bar")), // Add custom resource attributes.
		// resource.WithDetectors(thirdparty.Detector{}), // Bring your own external Detector implementation.
	)
	if errors.Is(err, resource.ErrPartialResource) || errors.Is(err, resource.ErrSchemaURLConflict) {
		log.Println(err) // Log non-fatal issues.
	} else if err != nil {
		log.Fatalln(err) // The error may be fatal.
	}

	// Now, you can use the resource (e.g. pass it to a tracer or meter provider).
	fmt.Println(res.SchemaURL())
}

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

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.