opentelemetry

README

Go Agent for OpenTelemetry

Go Agent provides a set of complementary features for OpenTelemetry instrumentation

Package net/hyperhttp

HTTP server

The server instrumentation relies on the http.Handler component of the server declarations.

import (
    "net/http"

    "github.com/gorilla/mux"
    "github.com/hypertrace/goagent/instrumentation/opentelemetry/net/hyperhttp"
    "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)

func main() {
    // ...

    r := mux.NewRouter()
    r.Handle("/foo/{bar}", otelhttp.NewHandler(
        hyperhttp.WrapHandler(fooHandler),
        "/foo/{bar}",
    ))

    // ...
}

HTTP client

The client instrumentation relies on the http.Transport component of the HTTP client in Go.

import (
    "net/http"
    "github.com/hypertrace/goagent/instrumentation/opentelemetry/net/hyperhttp"
    "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)

// ...

client := http.Client{
    Transport: otelhttp.NewTransport(
        hyperhttp.WrapDefaultTransport(),
        ...
    ),
}

req, _ := http.NewRequest("GET", "http://example.com", nil)

res, err := client.Do(req)

// ...

Running HTTP examples

In terminal 1 run the client:

go run ./net/http/examples/client/main.go

In terminal 2 run the server:

go run ./net/http/examples/server/main.go

Package google.golang.org/hypergrpc

GRPC server

The server instrumentation relies on the grpc.UnaryServerInterceptor component of the server declarations.

server := grpc.NewServer(
    grpc.UnaryInterceptor(
        hypergrpc.WrapUnaryServerInterceptor(
            otelgrpc.UnaryServerInterceptor(myTracer),
        ),
    ),
)

GRPC client

The client instrumentation relies on the http.Transport component of the HTTP client in Go.

import (
    // ...

    hypergrpc "github.com/hypertrace/goagent/instrumentation/opentelemetry/google.golang.org/hypergrpc"
    "go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
    "google.golang.org/grpc"
)

func main() {
    // ...
    conn, err := grpc.Dial(
        address,
        grpc.WithInsecure(),
        grpc.WithBlock(),
        grpc.WithUnaryInterceptor(
            hypergrpc.WrapUnaryClientInterceptor(
                otelgrpc.UnaryClientInterceptor(myTracer),
            ),
        ),
    )
    if err != nil {
        log.Fatalf("could not dial: %v", err)
    }
    defer conn.Close()

    client := pb.NewCustomClient(conn)

    // ...
}

Running GRPC examples

In terminal 1 run the client:

go run ./google.golang.org/hypergrpc/examples/client/main.go

In terminal 2 run the server:

go run ./google.golang.org/hypergrpc/examples/server/main.go

Documentation

Index

• Constants
• Variables
• func Init(cfg *config.AgentConfig) func()
• func InitAsAdditional(cfg *config.AgentConfig) (trace.SpanProcessor, func())
• func InitWithSpanProcessorWrapper(cfg *config.AgentConfig, wrapper SpanProcessorWrapper, ...) func()
• func InitWithSpanProcessorWrapperAndZap(cfg *config.AgentConfig, wrapper SpanProcessorWrapper, ...) func()
• func MakeRemoveGoAgentAttrs(attrsRemovalPrefixes []string) func(sp trace.SpanExporter) trace.SpanExporter
• func NewHttpOperationMetricsHandler(nameGetter func(*http.Request) string) sdk.HttpOperationMetricsHandler
• func RegisterService(key string, resourceAttributes map[string]string, opts ...ServiceOption) (sdk.StartSpan, trace.TracerProvider, error)
• func RegisterServiceWithSpanProcessorWrapper(key string, resourceAttributes map[string]string, wrapper SpanProcessorWrapper, ...) (sdk.StartSpan, trace.TracerProvider, error)
• func SpanFromContext(ctx context.Context) sdk.Span
• type AttributeList
  • func (l *AttributeList) GetValue(key string) interface{}
  • func (l *AttributeList) Iterate(yield func(key string, value interface{}) bool)
  • func (l *AttributeList) Len() int
• type HttpOperationMetricsHandler
  • func (mh *HttpOperationMetricsHandler) AddToRequestCount(n int64, r *http.Request)
• type ServiceOption
  • func WithHeaders(headers map[string]string) ServiceOption
• type ServiceOptions
• type Span
  • func (s *Span) AddEvent(name string, ts time.Time, attributes map[string]interface{})
  • func (s *Span) GetAttributes() sdk.AttributeList
  • func (s *Span) GetSpanId() string
  • func (s *Span) IsNoop() bool
  • func (s *Span) SetAttribute(key string, value interface{})
  • func (s *Span) SetError(err error)
  • func (s *Span) SetStatus(code sdk.Code, description string)
• type SpanProcessorWrapper

Examples

• Init
• RegisterService

Constants

const TracerDomain = "org.hypertrace.goagent"

TracerDomain represents the tracer name for the Hypertrace instrumentation

Variables

var NoopStartSpan = startSpan(trace.NewNoopTracerProvider)

var RemoveGoAgentAttrs = MakeRemoveGoAgentAttrs(attrsRemovalPrefixes)

var StartSpan = startSpan(otel.GetTracerProvider)

Functions

func Init

func Init(cfg *config.AgentConfig) func()

Init initializes opentelemetry tracing and returns a shutdown function to flush data immediately on a termination signal.

Example

cfg := config.Load()
cfg.ServiceName = config.String("my_example_svc")
cfg.DataCapture.HttpHeaders.Request = config.Bool(true)
cfg.Reporting.Endpoint = config.String("http://api.traceable.ai:9411/api/v2/spans")

shutdown := Init(cfg)
defer shutdown()

func InitAsAdditional

func InitAsAdditional(cfg *config.AgentConfig) (trace.SpanProcessor, func())

InitAsAdditional initializes opentelemetry tracing and returns a span processor and a shutdown function to flush data immediately on a termination signal. This is ideal for when we use goagent along with other opentelemetry setups.

func InitWithSpanProcessorWrapper

func InitWithSpanProcessorWrapper(cfg *config.AgentConfig, wrapper SpanProcessorWrapper,
	versionInfoAttrs []attribute.KeyValue) func()

InitWithSpanProcessorWrapper initializes opentelemetry tracing with a wrapper over span processor and returns a shutdown function to flush data immediately on a termination signal.

func InitWithSpanProcessorWrapperAndZap

func InitWithSpanProcessorWrapperAndZap(cfg *config.AgentConfig, wrapper SpanProcessorWrapper,
	versionInfoAttrs []attribute.KeyValue, logger *zap.Logger) func()

InitWithSpanProcessorWrapperAndZap initializes opentelemetry tracing with a wrapper over span processor and returns a shutdown function to flush data immediately on a termination signal. Also sets opentelemetry internal errorhandler to the provider zap errorhandler

func MakeRemoveGoAgentAttrs

func MakeRemoveGoAgentAttrs(attrsRemovalPrefixes []string) func(sp trace.SpanExporter) trace.SpanExporter

RemoveGoAgentAttrs removes custom goagent attributes from the spans so that other tracing servers don't receive them and don't have to handle the load.

func NewHttpOperationMetricsHandler

func NewHttpOperationMetricsHandler(nameGetter func(*http.Request) string) sdk.HttpOperationMetricsHandler

func RegisterService

func RegisterService(key string, resourceAttributes map[string]string, opts ...ServiceOption) (sdk.StartSpan, trace.TracerProvider, error)

RegisterService creates tracerprovider for a new service (represented via a unique key) and returns a func which can be used to create spans and the TracerProvider

Example

cfg := config.Load()
cfg.ServiceName = config.String("my_example_svc")
cfg.DataCapture.HttpHeaders.Request = config.Bool(true)
cfg.Reporting.TraceReporterType = config.TraceReporterType_LOGGING

shutdown := Init(cfg)
defer shutdown()

_, _, err := RegisterService("custom_service", map[string]string{"test1": "val1"})
if err != nil {
	log.Fatalf("Error while initializing service: %v", err)
}

func RegisterServiceWithSpanProcessorWrapper

func RegisterServiceWithSpanProcessorWrapper(key string, resourceAttributes map[string]string,
	wrapper SpanProcessorWrapper, versionInfoAttrs []attribute.KeyValue, opts ...ServiceOption) (sdk.StartSpan, trace.TracerProvider, error)

RegisterServiceWithSpanProcessorWrapper creates a tracerprovider for a new service (represented via a unique key) with a wrapper over opentelemetry span processor and returns a func which can be used to create spans and the TracerProvider

func SpanFromContext

func SpanFromContext(ctx context.Context) sdk.Span

Types

type AttributeList

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

func (*AttributeList) GetValue

func (l *AttributeList) GetValue(key string) interface{}

func (*AttributeList) Iterate

func (l *AttributeList) Iterate(yield func(key string, value interface{}) bool)

func (*AttributeList) Len

func (l *AttributeList) Len() int

type HttpOperationMetricsHandler

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

func (*HttpOperationMetricsHandler) AddToRequestCount

func (mh *HttpOperationMetricsHandler) AddToRequestCount(n int64, r *http.Request)

type ServiceOption

type ServiceOption func(*ServiceOptions)

func WithHeaders

func WithHeaders(headers map[string]string) ServiceOption

type ServiceOptions

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

type Span

type Span struct {
	trace.Span
}

func (*Span) AddEvent

func (s *Span) AddEvent(name string, ts time.Time, attributes map[string]interface{})

func (*Span) GetAttributes

func (s *Span) GetAttributes() sdk.AttributeList

func (*Span) GetSpanId

func (s *Span) GetSpanId() string

func (*Span) IsNoop

func (s *Span) IsNoop() bool

func (*Span) SetAttribute

func (s *Span) SetAttribute(key string, value interface{})

func (*Span) SetError

func (s *Span) SetError(err error)

func (*Span) SetStatus

func (s *Span) SetStatus(code sdk.Code, description string)

type SpanProcessorWrapper

type SpanProcessorWrapper interface {
	OnStart(parent context.Context, s sdktrace.ReadWriteSpan, delegate sdktrace.SpanProcessor)
	OnEnd(s sdktrace.ReadOnlySpan, delegate sdktrace.SpanProcessor)
}

SpanProcessorWrapper wraps otel span processor and is responsible to delegate calls to the wrapped processor