auto

README

OpenTelemetry Go Automatic Instrumentation

This repository provides OpenTelemetry instrumentation for Go libraries using eBPF.

🚧 This project is currently work in progress.

Compatibility

OpenTelemetry Go Automatic Instrumentation is compatible with all current supported versions of the Go language.

Each major Go release is supported until there are two newer major releases. For example, Go 1.5 was supported until the Go 1.7 release, and Go 1.6 was supported until the Go 1.8 release.

For versions of Go that are no longer supported upstream, this repository will stop ensuring compatibility with these versions in the following manner:

• A minor release will be made to add support for the new supported release of Go.
• The following minor release will remove compatibility testing for the oldest (now archived upstream) version of Go. This, and future, releases may include features only supported by the currently supported versions of Go.

Currently, OpenTelemetry Go Automatic Instrumentation is tested for the following environments.

OS	Go Version	Architecture
Ubuntu	1.21	amd64
Ubuntu	1.20	amd64

Automatic instrumentation should work on any Linux kernel above 4.4.

OpenTelemetry Go Automatic Instrumentation supports the arm64 architecture. However, there is no automated testing for this platform. Be sure to validate support on your own ARM based system.

Users of non-Linux operating systems can use the Docker images or create a virtual machine to compile and run OpenTelemetry Go Automatic Instrumentation.

Get started

You can instrument a Go executable using OpenTelemetry without having to write additional code. All you need to do is configure a few environment variables and run the instrumentation with elevated privileges.

The following example shows how to instrument a Go application automatically on a Linux host, through Docker, and using Kubernetes.

Prerequisites

To instrument an application automatically, you need the following:

• Linux with kernel version 4.19 or higher
• x64 or ARM processor
• Docker image or compiled binary of OpenTelemetry Go Automatic Instrumentation

To compile the instrumentation binary, use Go 1.18 or higher.

Instrument an application on the same host

To instrument an application on the same host, follow these steps:

1. Run the target application.

2. Set the following environment variables before running the instrumentation:

• OTEL_GO_AUTO_TARGET_EXE: Full path of the executable you want to instrument. For example, /home/bin/service_executable
• OTEL_SERVICE_NAME: Name of your service or application
• OTEL_EXPORTER_OTLP_ENDPOINT: Your observability backend. For example, http://localhost:4318.

For example:

sudo OTEL_GO_AUTO_TARGET_EXE=/home/bin/service_executable OTEL_SERVICE_NAME=my_service OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318./otel-go-instrumentation`

1. Run the OpenTelemetry Go Automatic Instrumentation with root privileges.

Note If the target application isn't running yet, the instrumentation waits for the process to start.

Instrument an application in Docker Compose

To instrument a containerized application, follow these steps:

1. Create or edit the docker-compose.yaml file. Make sure to add a Docker network, a shared volume, and a service for the application.

2. Edit the docker-compose file to add a new service for the instrumentation:

  go-auto:
    image: otel/autoinstrumentation-go
    privileged: true
    pid: "host"
    environment:
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://<address_in_docker_network>:4318
      - OTEL_GO_AUTO_TARGET_EXE=<location_of_target_application_binary>
      - OTEL_SERVICE_NAME=<name_of_your_application>
      - OTEL_PROPAGATORS=tracecontext,baggage
    volumes:
      - <shared_volume_of_application>
      - /proc:/host/proc

1. Run docker compose up.

Instrument an application in Kubernetes

To instrument an application running in Kubernetes, follow these steps:

1. Add the container image of the OpenTelemetry Go Automatic Instrumentation to your manifest. Make sure that runAsUser is set to 0, privileged is set to true:

   - name: autoinstrumentation-go
     image: otel/autoinstrumentation-go
     imagePullPolicy: IfNotPresent
     env:
       - name: OTEL_GO_AUTO_TARGET_EXE
         value: <location_of_target_application_binary>
       - name: OTEL_EXPORTER_OTLP_ENDPOINT
         value: "http://<address_in_network>:4318"
       - name: OTEL_SERVICE_NAME
         value: "<name_of_service>"
     securityContext:
       runAsUser: 0
       privileged: true
   

2. Check if the configuration shareProcessNamespace is present in the pod spec, if not, please add it.

3. Deploy the application and the instrumentation using the manifest.

Configuration

See the documentation for InstrumentationOption factory functions for information about how to configure the OpenTelemetry Go Automatic Instrumentation.

Contributing

See the contributing documentation.

License

OpenTelemetry Go Automatic Instrumentation is licensed under the terms of the Apache Software License version 2.0. See the license file for more details.

Third-party licesnes and copyright notices can be found in the LICENSES directory.

Documentation

Index

• func Version() string
• type Instrumentation
  • func NewInstrumentation(ctx context.Context, opts ...InstrumentationOption) (*Instrumentation, error)
  • func (i *Instrumentation) Close() error
  • func (i *Instrumentation) Run(ctx context.Context) error
• type InstrumentationOption
  • func WithEnv() InstrumentationOption
  • func WithGlobal() InstrumentationOption
  • func WithPID(pid int) InstrumentationOption
  • func WithResourceAttributes(attrs ...attribute.KeyValue) InstrumentationOption
  • func WithSampler(sampler trace.Sampler) InstrumentationOption
  • func WithServiceName(serviceName string) InstrumentationOption
  • func WithTarget(path string) InstrumentationOption
  • func WithTraceExporter(exp trace.SpanExporter) InstrumentationOption

Functions

func Version

func Version() string

Version is the current release version of OpenTelemetry Go auto-instrumentation in use.

Types

type Instrumentation

type Instrumentation struct {
	// contains filtered or unexported fields
}

Instrumentation manages and controls all OpenTelemetry Go auto-instrumentation.

func NewInstrumentation

func NewInstrumentation(ctx context.Context, opts ...InstrumentationOption) (*Instrumentation, error)

NewInstrumentation returns a new Instrumentation configured with the provided opts.

If conflicting or duplicate options are provided, the last one will have precedence and be used.

func (*Instrumentation) Close

func (i *Instrumentation) Close() error

Close closes the Instrumentation, cleaning up all used resources.

func (*Instrumentation) Run

func (i *Instrumentation) Run(ctx context.Context) error

Run starts the instrumentation.

type InstrumentationOption

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

InstrumentationOption applies a configuration option to Instrumentation.

func WithEnv

func WithEnv() InstrumentationOption

WithEnv returns an InstrumentationOption that will configure Instrumentation using the values defined by the following environment variables:

• OTEL_GO_AUTO_TARGET_EXE: sets the target binary
• OTEL_SERVICE_NAME (or OTEL_RESOURCE_ATTRIBUTES): sets the service name
• OTEL_TRACES_EXPORTER: sets the trace exporter

This option may conflict with WithTarget, WithPID, WithTraceExporter, and WithServiceName if their respective environment variable is defined. If more than one of these options are used, the last one provided to an Instrumentation will be used.

The OTEL_TRACES_EXPORTER environment variable value is resolved using the autoexport package. See that package's documentation for information on supported values and registration of custom exporters.

func WithGlobal

func WithGlobal() InstrumentationOption

WithGlobal returns an InstrumentationOption that will configure an Instrumentation to record telemetry from the OpenTelemetry default global implementation. By default, the OpenTelemetry global implementation is a no-op implementation of the OpenTelemetry API. However, by using this option, all telemetry that would have been dropped by the global implementation will be recorded using telemetry pipelines from the configured Instrumentation.

If the target process overrides the default global implementation (e.g. [otel.SetTracerProvider]), the telemetry from that process will go to the set implementation. It will not be recorded using the telemetry pipelines from the configured Instrumentation even if this option is used.

The OpenTelemetry default global implementation is left unchanged (i.e. it remains a no-op implementation) if this options is not used.

func WithPID

func WithPID(pid int) InstrumentationOption

WithPID returns an InstrumentationOption defining the target binary for Instrumentation that is being run with the provided PID.

This option conflicts with WithTarget. If both are used, the last one provided to an Instrumentation will be used.

If multiple of these options are provided to an Instrumentation, the last one will be used.

If OTEL_GO_AUTO_TARGET_EXE is defined, this option will conflict with WithEnv. If both are used, the last one provided to an Instrumentation will be used.

func WithResourceAttributes

func WithResourceAttributes(attrs ...attribute.KeyValue) InstrumentationOption

WithResourceAttributes returns an InstrumentationOption that will configure an Instrumentation to add the provided attributes to the OpenTelemetry resource.

func WithSampler

func WithSampler(sampler trace.Sampler) InstrumentationOption

WithSampler returns an InstrumentationOption that will configure an Instrumentation to use the provided sampler to sample OpenTelemetry traces.

func WithServiceName

func WithServiceName(serviceName string) InstrumentationOption

WithServiceName returns an InstrumentationOption defining the name of the service running.

If multiple of these options are provided to an Instrumentation, the last one will be used.

If OTEL_SERVICE_NAME is defined or the service name is defined in OTEL_RESOURCE_ATTRIBUTES, this option will conflict with WithEnv. If both are used, the last one provided to an Instrumentation will be used.

func WithTarget

func WithTarget(path string) InstrumentationOption

WithTarget returns an InstrumentationOption defining the target binary for Instrumentation that is being executed at the provided path.

This option conflicts with WithPID. If both are used, the last one provided to an Instrumentation will be used.

If multiple of these options are provided to an Instrumentation, the last one will be used.

If OTEL_GO_AUTO_TARGET_EXE is defined, this option will conflict with WithEnv. If both are used, the last one provided to an Instrumentation will be used.

func WithTraceExporter

func WithTraceExporter(exp trace.SpanExporter) InstrumentationOption

WithTraceExporter returns an InstrumentationOption that will configure an Instrumentation to use the provided exp to export OpenTelemetry tracing telemetry.

If OTEL_TRACES_EXPORTER is defined, this option will conflict with WithEnv. If both are used, the last one provided to an Instrumentation will be used.