autodetect

Documentation

Overview

Package autodetect provides functionality to configures and use a set of resource detectors at runtime.

Index

• Variables
• func Detector(ids ...ID) (resource.Detector, error)
• func Register(id ID, fn func() resource.Detector)
• type ID
  • func Registered() []ID

Examples

• Detector
• Detector (EnvVar)

Variables

var (
	// IDAWSEC2 is the ID for the AWS EC2 detector that detects resource
	// attributes on Amazon Web Services (AWS) EC2 instances (see
	// ec2.NewResourceDetector for details).
	IDAWSEC2 = ID("aws.ec2")
	// IDAWSECS is the ID for the AWS ECS detector that detects resource
	// attributes on Amazon Web Services (AWS) ECS clusters (see
	// ecs.NewResourceDetector for details).
	IDAWSECS = ID("aws.ecs")
	// IDAWSEKS is the ID for the AWS EKS detector that detects resource
	// attributes on Amazon Web Services (AWS) EKS clusters (see
	// eks.NewResourceDetector for details).
	IDAWSEKS = ID("aws.eks")
	// IDAWSLambda is the ID for the AWS Lambda detector that detects resource
	// attributes on Amazon Web Services (AWS) Lambda functions (see
	// lambda.NewResourceDetector for details).
	IDAWSLambda = ID("aws.lambda")
	// IDAzureVM is the ID for the Azure VM detector that detects resource
	// attributes on Microsoft Azure virtual machines (see azurevm.New for
	// details).
	IDAzureVM = ID("azure.vm")
	// IDGCP is the ID for the GCP detector that detects resource attributes on
	// Google Cloud Platform (GCP) environments (see gcp.NewDetector for
	// details).
	IDGCP = ID("gcp")
	// IDHost is the ID for the host detector. This detector detects the
	// "host.name" attribute from the os.Hostname function.
	IDHost = ID("host")
	// IDHostID is the ID for the host ID detector. This detector detects the
	// "host.id" attribute, which is a unique identifier for the host (e.g.,
	// machine-id, UUID).
	IDHostID = ID("host.id")
	// IDTelemetrySDK is the ID for the telemetry SDK detector. This detector
	// detects the "telemetry.sdk.name", "telemetry.sdk.language", and
	// "telemetry.sdk.version" attributes, which provide information about the
	// SDK being used.
	IDTelemetrySDK = ID("telemetry.sdk")
	// IDOSType is the ID for the OS type detector. This detector detects the
	// "os.type" attribute, which indicates the type of operating system (e.g.,
	// "linux", "windows", "darwin").
	IDOSType = ID("os.type")
	// IDOSDescription is the ID for the OS description detector. This detector
	// detects the "os.description" attribute, which provides a human-readable
	// description of the operating system.
	IDOSDescription = ID("os.description")
	// IDProcessPID is the ID for the process PID detector. This detector
	// detects the "process.pid" attribute, which is the process ID of the
	// current process.
	IDProcessPID = ID("process.pid")
	// IDProcessExecutableName is the ID for the process executable name
	// detector. This detector detects the "process.executable.name" attribute,
	// which is the name of the executable file for the current process.
	IDProcessExecutableName = ID("process.executable.name")
	// IDProcessExecutablePath is the ID for the process executable path
	// detector. This detector detects the "process.executable.path" attribute,
	// which is the full path to the executable file for the current process.
	IDProcessExecutablePath = ID("process.executable.path")
	// IDProcessCommandArgs is the ID for the process command arguments
	// detector. This detector detects the "process.command.args" attribute,
	// which is the command line arguments used to start the current process.
	//
	// Warning! This detector will include process command line arguments. If
	// these contain sensitive information it will be included in the exported
	// resource.
	IDProcessCommandArgs = ID("process.command.args")
	// IDProcessOwner is the ID for the process owner detector. This detector
	// detects the "process.owner" attribute, which is the user who owns the
	// current process.
	IDProcessOwner = ID("process.owner")
	// IDProcessRuntimeName is the ID for the process runtime name detector.
	// This detector detects the "process.runtime.name" attribute, which is the
	// name of the runtime environment for the current process (e.g., "go",
	// "python", "java").
	IDProcessRuntimeName = ID("process.runtime.name")
	// IDProcessRuntimeVersion is the ID for the process runtime version
	// detector. This detector detects the "process.runtime.version" attribute,
	// which is the version of the runtime environment for the current process
	// (e.g., "1.16.3", "3.8.5").
	IDProcessRuntimeVersion = ID("process.runtime.version")
	// IDProcessRuntimeDescription is the ID for the process runtime
	// description detector. This detector detects the
	// "process.runtime.description" attribute, which provides an additional
	// description of the runtime environment for the current process (e.g.,
	// "Go runtime version 1.16.3", "Python 3.8.5").
	IDProcessRuntimeDescription = ID("process.runtime.description")
	// IDContainer is the ID for the container detector. This detector detects
	// the "container.id" attribute, which is a unique identifier for the
	// container in which the process is running. This is useful for
	// identifying the container in which the process is running, especially in
	// containerized environments like Kubernetes or Docker.
	IDContainer = ID("container")
)

var ErrUnknownDetector = errors.New("unknown resource detector")

ErrUnknownDetector is returned when an unknown resource detector ID is requested.

Functions

func Detector

func Detector(ids ...ID) (resource.Detector, error)

Detector returns a resource.Detector composed of the detectors identified by the provided IDs. If an ID is not recognized, ErrUnknownDetector is returned. The returned detector merges all the resource from each detector when Detect is called. The order of the merge is not guaranteed.

Example

package main

import (
	"context"
	"encoding/json"
	"fmt"

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

	"go.opentelemetry.io/contrib/detectors/autodetect"
)

func init() {
	id := autodetect.ID("my.cfg.detector")
	autodetect.Register(id, func() resource.Detector {
		return MyDetector{}
	})
}

var data = []byte(`{
	"detectors": [
		"host",
		"telemetry.sdk",
		"my.cfg.detector"
	]
}`)

type Config struct {
	Detectors []autodetect.ID `json:"detectors"`
}

func main() {
	// This example shows how to parse resource.Detectors from a user defined
	// configuration file.

	cfg := Config{}
	err := json.Unmarshal(data, &cfg)
	if err != nil {
		panic(err)
	}

	detector, err := autodetect.Detector(cfg.Detectors...)
	if err != nil {
		panic(err)
	}

	// Use the detector as needed.

	res, err := detector.Detect(context.Background())
	if err != nil {
		panic(err)
	}
	fmt.Print(enc.Encode(res.Iter()))
}

Output:

  host.name my.key telemetry.sdk.language telemetry.sdk.name telemetry.sdk.version

Example (EnvVar)

package main

import (
	"context"
	"fmt"
	"os"
	"strings"

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

	"go.opentelemetry.io/contrib/detectors/autodetect"
)

// This environment variable is expected to be a comma-separated list of
// detectors the user wants for the purpose of the example. It can take any
// form a user want to parse.
const envVar = "RESOURCE_DETECTORS"

func init() {
	id := autodetect.ID("my.env.var.detector")
	autodetect.Register(id, func() resource.Detector {
		return MyDetector{}
	})

	_ = os.Setenv(envVar, "host,telemetry.sdk,my.env.var.detector")
}

func main() {
	// This example shows how to parse resource.Detectors from an environment
	// variable.

	names := strings.Split(os.Getenv(envVar), ",")
	ids := make([]autodetect.ID, 0, len(names))
	for _, name := range names {
		ids = append(ids, autodetect.ID(name))
	}

	detector, err := autodetect.Detector(ids...)
	if err != nil {
		// Handle the error if parsing fails.
		panic(err)
	}

	// Use the detector as needed.

	res, err := detector.Detect(context.Background())
	if err != nil {
		panic(err)
	}
	fmt.Print(enc.Encode(res.Iter()))
}

Output:

  host.name my.key telemetry.sdk.language telemetry.sdk.name telemetry.sdk.version

func Register

func Register(id ID, fn func() resource.Detector)

Register registers a new resource detector function with the given ID.

Types

type ID

type ID string

ID represents the unique identifier of a resource detector.

func Registered

func Registered() []ID

Registered returns a sorted slice of all registered resource detector IDs.