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 MakeRemoveGoAgentAttrs(attrsRemovalPrefixes []string) func(sp trace.SpanExporter) trace.SpanExporter
• func RegisterService(serviceName string, resourceAttributes map[string]string) (sdk.StartSpan, trace.TracerProvider, error)
• func RegisterServiceWithSpanProcessorWrapper(serviceName string, resourceAttributes map[string]string, ...) (sdk.StartSpan, trace.TracerProvider, error)
• func SpanFromContext(ctx context.Context) sdk.Span
• type AttributeList
  • func (l *AttributeList) GetValue(key string) interface{}
• type Span
  • func (s *Span) AddEvent(name string, ts time.Time, attributes map[string]interface{})
  • func (s *Span) GetAttributes() sdk.AttributeList
  • 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) 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 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 RegisterService

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

RegisterService creates tracerprovider for a new service 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(serviceName string, resourceAttributes map[string]string,
	wrapper SpanProcessorWrapper) (sdk.StartSpan, trace.TracerProvider, error)

RegisterServiceWithSpanProcessorWrapper creates a tracerprovider for a new service 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{}

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