package resource
Import Path
go.opentelemetry.io/otel/sdk/resource (on go.dev)
Dependency Relation
imports 20 packages, and imported by 4 packages
Involved Source Files
auto.go
builtin.go
config.go
container.go
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.
env.go
host_id.go
host_id_linux.go
host_id_readfile.go
os.go
os_release_unix.go
os_unix.go
process.go
resource.go
Code Examples
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())
}
Package-Level Type Names (total 3)
Detector detects OpenTelemetry resource information.
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.
func StringDetector(schemaURL string, k attribute.Key, f func() (string, error)) Detector
func Detect(ctx context.Context, detectors ...Detector) (*Resource, error)
func WithDetectors(detectors ...Detector) Option
Option is the interface that applies a configuration 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
func New(ctx context.Context, opts ...Option) (*Resource, error)
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.
Note that the Go == operator compares not just the resource attributes but
also all other internals of the Resource type. Therefore, Resource values
should not be used as map or database keys. In general, the [Resource.Equal]
method should be used instead of direct comparison with ==, since that
method ensures the correct comparison of resource attributes, and the
[attribute.Distinct] returned from [Resource.Equivalent] should be used for
map and database keys instead.
Attributes returns a copy of attributes from the resource in a sorted order.
To avoid allocating a new slice, use an iterator.
Encoded returns an encoded representation of the resource.
Equal reports whether r and o represent the same resource. Two resources can
be equal even if they have different schema URLs.
See the documentation on the [Resource] type for the pitfalls of using ==
with Resource values; most code should use Equal instead.
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.
Iter returns an iterator of the Resource attributes.
This is ideal to use if you do not want a copy of the attributes.
Len returns the number of unique key-values in this Resource.
MarshalJSON encodes the resource attributes as a JSON list of { "Key":
"...", "Value": ... } pairs in order sorted by key.
MarshalLog is the marshaling function used by the logging system to represent this Resource.
SchemaURL returns the schema URL associated with Resource r.
Set returns the equivalent *attribute.Set of this resource's attributes.
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.
*Resource : encoding/json.Marshaler
*Resource : expvar.Var
*Resource : fmt.Stringer
*Resource : github.com/go-logr/logr.Marshaler
*Resource : github.com/goccy/go-json.Marshaler
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 Detector.Detect(ctx context.Context) (*Resource, error)
func go.opentelemetry.io/otel/sdk/log.(*Record).Resource() *Resource
func go.opentelemetry.io/otel/sdk/trace.ReadOnlySpan.Resource() *Resource
func go.opentelemetry.io/otel/sdk/trace.ReadWriteSpan.Resource() *Resource
func Merge(a, b *Resource) (*Resource, error)
func (*Resource).Equal(o *Resource) bool
func go.opentelemetry.io/otel/sdk/log.WithResource(res *Resource) log.LoggerProviderOption
func go.opentelemetry.io/otel/sdk/trace.WithResource(r *Resource) trace.TracerProviderOption
func go.opentelemetry.io/otel/exporters/otlp/otlptrace/internal/tracetransform.Resource(r *Resource) *resourcepb.Resource
func go.opentelemetry.io/otel/exporters/otlp/otlptrace/internal/tracetransform.ResourceAttributes(res *Resource) []*commonpb.KeyValue
Package-Level Functions (total 30)
Default returns an instance of Resource with a default
"service.name" and OpenTelemetrySDK attributes.
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.
Empty returns an instance of Resource with no attributes. It is
equivalent to a `nil` Resource.
Environment returns an instance of Resource with attributes
extracted from the OTEL_RESOURCE_ATTRIBUTES environment variable.
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.
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.
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.
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.
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.
WithAttributes adds attributes to the configured Resource.
WithContainer adds all the Container attributes to the configured Resource.
See individual WithContainer* functions to configure specific attributes.
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).
WithDetectors adds detectors to be evaluated for the configured resource.
WithFromEnv adds attributes from environment variables to the configured resource.
WithHost adds attributes from the host to the configured resource.
WithHostID adds host ID information to the configured resource.
WithOS adds all the OS attributes to the configured Resource.
See individual WithOS* functions to configure specific attributes.
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.
WithOSType adds an attribute with the operating system type to the configured Resource.
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.
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.
WithProcessExecutableName adds an attribute with the name of the process
executable to the configured Resource.
WithProcessExecutablePath adds an attribute with the full path to the process
executable to the configured Resource.
WithProcessOwner adds an attribute with the username of the user that owns the process
to the configured Resource.
WithProcessPID adds an attribute with the process identifier (PID) to the
configured Resource.
WithProcessRuntimeDescription adds an attribute with an additional description
about the runtime of the process to the configured Resource.
WithProcessRuntimeName adds an attribute with the name of the runtime of this
process to the configured Resource.
WithProcessRuntimeVersion adds an attribute with the version of the runtime of
this process to the configured Resource.
WithSchemaURL sets the schema URL for the configured resource.
WithTelemetrySDK adds TelemetrySDK version info to the configured resource.
Package-Level Variables (total 2)
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.
ErrSchemaURLConflict is an error returned when two Resources are merged
together that contain different, non-empty, schema URLs.
 |
The pages are generated with Golds v0.8.2. (GOOS=linux GOARCH=amd64) Golds is a Go 101 project developed by Tapir Liu. PR and bug reports are welcome and can be submitted to the issue list. Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds. |