Go installation instructions

Use the installation instructions below if you're installing Helios in a standard Go service.

Get your Golang services auto-instrumented with Helios by following the installation instructions provided below. Once complete, the instrumentation is seamless and does not require further manual adjustments.

In order to instrument your Go service with Helios, you need to perform the following couple of steps:

  1. Configure Helios as your tracer provider
  2. Setup the instrumentation

Configure a tracer provider

The first step when instrumenting your Go service is to configure a trace provider, so that traces are sent to the Helios backend.

Since instrumentation in Go cannot be done automatically, you have to manually create and set a tracer provider that creates spans containing the token provided by Helios, and sends these spans to the Helios collector.

Start by installing the OpenTelemetry dependencies.

From your project's root directory run:

go get github.com/helios/go-sdk

Now you can define the trace provider by using:

import (
	"github.com/helios/go-sdk/sdk"
)

sdk.Initialize("your-service-name-goes-here","YOUR HELIOS TOKEN GOES HERE", sdk.WithEnvironment("your-env-name-goes-here"));
// Service name will be overriden with function name when initialized for AWS Lambda

Setup the instrumentation

The instrumentation will take place at build time.

The instrumentor will wrap the supported packages with helios packages (proxy-libraries) to allow instrumentation.

Instrumentation using Docker

Run the Helios Go instrumentor (supported for Linux and macOS) from your project root folder by calling:

docker run -v $(pwd):/app gethelios/go-instrumentor

Note that the instrumentor is using gofmt printer by default. You can disable and use the default printer with custom indentation with:

docker run -e FORMAT_USE_GOFMT=false -e PRINTER_INDENTATION=<YOUR_CUSTOMER_INDENTATION> -v $(pwd):/app gethelios/go-instrumentor

Instrumentation using the instrumentor executable

Alternatively, you can download the instrumentor executable (Linux / macOS (ARM) / macOS (x86) / Windows) to your project root folder and run it directly. Make sure to update the executable's permissions with: chmod a+x <FILE_PATH>.
Once the instrumentor finishes running, run go mod tidy & go build.

Note that the instrumentor is using gofmt printer by default. You can disable and use the default printer with custom indentation with:

./helios-instrumentor --format_usegofmt true --printer_indentation <YOUR_CUSTOMER_INDENTATION>

Additional instructions

PostgreSQL instrumentation

Helios supports auto instrumentation for the github.com/go-pg/pg library.

After running the Helios instrumentor, make sure to pass context to the DB after initializing it by using
db.WithContext(ctx) - in order to associate the queries with the relevant trace.

๐Ÿ‘

All set

After setup is complete and once the service is up and running, it will show up in the Helios application.