Go Agent

[DEPRECATED] This repo is deprecated and new changes will no longer be made to this repo.

Please use Traceableai/goagent.

goagent provides a set of complementary instrumentation features for collecting relevant data to be processed by Hypertrace.

Getting started

Setting up Go Agent can be done with a few lines:

import"github.com/hypertrace/goagent/config"...funcmain() {
cfg:=config.Load()
cfg.ServiceName=config.String("myservice")
shutdown:=hypertrace.Init(cfg)
defershutdown
}

Config values can be declared in config file, env variables or code. For further information about config check this section.

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/hypertrace/net/hyperhttp"
)
funcmain() {
// ...r:=mux.NewRouter()
r.Handle("/foo/{bar}", hyperhttp.NewHandler(
fooHandler,
"/foo/{bar}",
))
// ...
}

Options

Filter

Filtering can be added as part of options. Multiple filters can be added and they will be run in sequence until a filter returns true (request is blocked), or all filters are run.

// ...r.Handle("/foo/{bar}", hyperhttp.NewHandler(
fooHandler,
"/foo/{bar}",
hyperhttp.WithFilter(filter.NewMultiFilter(filter1, filter2)),
))
// ...

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/hypertrace/net/hyperhttp"
)
// ...client:= http.Client{
Transport: hyperhttp.NewTransport(
http.DefaultTransport,
),
}
req, _:=http.NewRequest("GET", "http://example.com", nil)
res, err:=client.Do(req)
// ...

Running HTTP examples

In terminal 1 run the client:

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

In terminal 2 run the server:

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

Gin-Gonic Server

Gin server instrumentation relies on adding the hypergin.Middleware middleware to the gin server.

r:=gin.Default()
cfg:=config.Load()
cfg.ServiceName=config.String("http-gin-server")
flusher:=hypertrace.Init(cfg)
deferflusher()
r.Use(hypergin.Middleware())

To run an example gin server with the hypertrace middleware:

go run ./examples/gin-server/main.go

Then make a request to localhost:8080/ping

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.UnaryServerInterceptor(),
),
)

Options

Filter

Filtering can be added as part of options. Multiple filters can be added and they will be run in sequence until a filter returns true (request is blocked), or all filters are run.

// ...grpc.UnaryInterceptor(
hypergrpc.UnaryServerInterceptor(
hypergrpc.WithFilter(filter.NewMultiFilter(filter1, filter2))
),
),
// ...

GRPC client

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

import (
// ...
hypergrpc "github.com/hypertrace/goagent/instrumentation/hypertrace/google.golang.org/hypergrpc""google.golang.org/grpc"
)
funcmain() {
// ...conn, err:=grpc.Dial(
address,
grpc.WithInsecure(),
grpc.WithBlock(),
grpc.WithUnaryInterceptor(
hypergrpc.UnaryClientInterceptor(),
),
)
iferr!=nil {
log.Fatalf("could not dial: %v", err)
}
deferconn.Close()
client:=pb.NewCustomClient(conn)
// ...
}

Running GRPC examples

In terminal 1 run the client:

go run ./examples/grpc-client/main.go

In terminal 2 run the server:

go run ./examples/grpc-server/main.go

Other instrumentations

• database/hypersql
• github.com/gorilla/hypermux

Contributing

Running tests

Tests can be run with (requires docker)

make test

for unit tests only

make test-unit

Releasing

Run ./release.sh <version_number> (<version_number> should follow semver, e.g. 1.2.3). The script will change the hardcoded version, commit it, push a tag and prepare the hardcoded version for the next release. After that go to the releases page and draft a new release based on the new tag.

Further Reference

Read more about goagent in the 'Yet Another Go Agent' blog post.