Install the Go microagent

Install from examples

Instead of following the instructions below to install the microagent, you may wish to install using an example Docker image, Heroku app, or Google App Engine app. Access Install from examples to do so.

1. Review Go microagent compatibility to confirm that the Sqreen Microagent for Go is compatible with your Go application.

2. Sign up to create your Sqreen account.

3. Add Sqreen's HTTP middleware for your web framework. If your web framework is not included below, please report an issue on Github.

// Code snippet for net/http
package main
import (
    "github.com/gin-gonic/gin"
    "github.com/sqreen/go-agent/sdk/middleware/sqhttp"
)
func main() {
    mux := http.NewServeMux()
    // ...
    // Wrap your ServeMux with Sqreen's middleware function
    http.ListenAndServe(":http", sqhttp.Middleware(mux))
}
// Code snippet for gin
package main
import (
    "github.com/gin-gonic/gin"
    "github.com/sqreen/go-agent/sdk/middleware/sqgin"
)
func main() {
    router := gin.New()
    router.Use(sqgin.Middleware())
    // ...
}
// Code snippet for echo
package main
import (
    "github.com/labstack/echo"
    "github.com/sqreen/go-agent/sdk/middleware/sqecho"
)
func main() {
    router := echo.New()
    router.Use(sqgin.Middleware())
    // ...
}
// Code snippet for gorilla/mux
package main
import (
    "github.com/gorilla/mux"
    "github.com/sqreen/go-agent/sdk/middleware/sqhttp"
)
func main() {
    router := mux.NewRouter()
    // Wrap your Gorilla Mux with Sqreen's middleware function
    router.Use(sqhttp.Middleware)
    // ...
}
// Code snippet for beego
package main
import (
    "github.com/astaxie/beego"
    "github.com/sqreen/go-agent/sdk/middleware/sqhttp"
)
func main() {
    app := beego.NewApp()
    // ...
    app.Run(sqhttp.Middleware)
}

4. The Sqreen Microagent uses compile-time instrumentation to add safe runtime instrumentation capabilities to your Go app. To install the instrumentation tool, use go get to download, compile and install. Refer to Microagent compilation requirements below.

$ go get -v github.com/sqreen/go-agent/sdk/sqreen-instrumentation-tool

Instrumented packages

Use the -v flag to set the instrumentation tool to verbose mode to learn which packages the microagent instruments.

5. The sqreen-instrumentation-tool tool installs in the bin directory of the GOPATH in your app. Verify the install using go env GOPATH.

6. Configure the Go toolchain to use the instrumentation tool you just installed using one of the following methods:

$ go build -a -toolexec $(go env GOPATH)/bin/sqreen-instrumentation-tool my-project
$ GOFLAGS="-a -toolexec $(go env GOPATH)/bin/sqreen-instrumentation-tool"
$ go build my-project
# Compiling a Go module with Docker
FROM golang
WORKDIR /app
COPY . .
RUN go build -v github.com/sqreen/go-agent/sdk/sqreen-instrumentation-tool
RUN go build -v -a -toolexec ./sqreen-instrumentation-tool my-project

7. From the Sqreen Dashboard, add a new host to retrieve the token.

8. Set the Sqreen token and application using environment variables or the sqreen.yaml file.

app_name: "Your Go Service Name"
token: "Your Token"

If you encounter any issues, refer to the Troubleshoot the Go microagent documentation.

Microagent compilation requirements

The microagent compilation involves cgo which requires the following to function:

  • the gcc compiler for the target GOOS and GOARCH
  • the C library headers
  • the cgo bindings enabled (uses CGO_ENABLED environment variable which is enabled by default when compiling natively)

Note that the go toolchain disables cgo when cross-compiling. Refer to Cross-compilation section below.

The following are examples of requirements installations:

$ apt install gcc libc6-dev
$ apk add gcc musl-dev
$ yum install gcc glibc-devel
$ xcode-select --install 

Cross-compilation

Cross-compiling with cgo requires the gcc compiler and C headers for the target GOOS and GOARCH.

The following are examples from a Debian system which provides pre-compiled commonly-used cross-compilers:

$ sudo apt install gcc-mingw-w64-x86-64
$ env GOOS=windows GOARCH=amd64 CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc go build your-go-app
$ sudo apt install gcc-aarch64-linux-gnu
$ env GOOS=linux GOARCH=arm64 CGO_ENABLED=1 CC=aarch64-linux-gnu-gcc go build your-go-app

If a target compiler is not available on your system, please create an issue in Github.

Uninstall

To uninstall the Go microagent, remove the package from your imported packages.