Go

Go language, or Go lang, is used in a wide range of applications, including web servers, database systems, networking tools, and distributed systems. It is also popular for building microservices and for developing command-line tools and utilities. Traceable’s Go agent is based on OpenTelemetery and enhances the spans within a Trace with security-focused attributes. Traceable’s agent can capture all the traffic that flows through your Go application, including request and response headers along with the body of the request and response. 

The following diagram shows a high-level deployment architecture for your Go application with Traceable's Go agent:

Before you begin

Make a note of the following points before you start with the deployment:

• Operating System – Traceable's Go agent supports Debian, CentOS, Amazon Linux 2, and Alpine operating systems.
• Go version – Traceable's Go agent is supported for Go 1.15 and later versions.
• Make sure that you have already installed Traceable's Platform agent. The Go agent sends the traces to Traceable's Platform agent and also fetches the OPA and blocking configuration from it.
• Traceable's Go agent is an SDK based Go package. Installing the Go agent requires some code change in the application where you wish to inject the Go agent. Make sure that you have reasonable knowledge of Go language.

Supported Frameworks

Download Go agent

Traceable's Go agent is available in Traceable's git repository. Enter the following command to download the latest Go agent:

go get github.com/Traceableai/goagent

Installation

To make Traceable's Go agent available, you need to make it available in your go.mod file. For example:

module github.com/example/myapp

go 1.15

require (
	github.com/Traceableai/goagent v0.3.1
	github.com/gorilla/mux v1.8.0
)

You can set up the Go agent in a few lines as shown below:

import (
    "github.com/Traceableai/goagent"
    "github.com/Traceableai/goagent/config"
)

//...

func main() {
    cfg := config.Load()
    
    cfg.Tracing.ServiceName = config.String("myservice")

    shutdown := goagent.Init(cfg)
    defer shutdown()
}

Traceable filter

Traceable filter inspects your traffic and identifies and blocks (optional) any requests that fail to meet your security configuration. By default, Traceable's Go agent includes the Traceable filter into the server instrumentation, for example, HTTP server or GRPC server. To run the Traceable filter, you need to first compile the binary using the build tag traceable_filter. For example:

# Change /path-to-app to the location of your app
go build -tags 'traceable_filter' -o /path-to-app/myapp

Copy the library to the same directory as the compiled binary.

# Change /path-to-app to the location of your app
curl -sSL https://raw.githubusercontent.com/Traceableai/goagent/main/filter/traceable/copy-library.sh | bash -s -- /path-to-app

Applying the SDK

Follow the following two links to understand what code to add along with examples to instrument:

• Go agent
• Examples

Configuration

You can configure Go agent in multiples ways, such as making changes in the code, configuring the environment variables, or using a configuration file.

In code

You can configure Traceable’s Go module with a few lines as shown below. Following is a snippet with only a few configurations in the main.go file.

import(
// ...
  github.com/Traceableai/goagent/config
// ...
)
// loads the config from the config file configured with the TA_CONFIG_FILE
// env var and env vars. The env vars override the values in the file.
cfg := config.Load()

// overrides statically the service name. If you do not specify a service name, you
// will not see traces.
// If you have set the service name in the file configured with the env var
// TA_CONFIG_FILE, there's no need to set this.
cfg.Tracing.ServiceName = config.String("myservice")
// An example of how to override the http headers request data capture.
cfg.Tracing.DataCapture.HTTPHeaders.Request = config.Bool(true)

You can define the configuration variables in a JSON or YAML file, for example, config.yml. Alternatively, you can use environment variables to define the configuration variables or in the code as shown above. In the above snippet:

• myservice is the name of the service with which you would want it to be identified on Traceable’s Platform 
• cfg.Tracing.DataCapture.HTTPHeaders.Request is set to true. This captures the HTTP request headers. 

Environment variables

The environment variable can also be used to overwrite the default values. For example, you can set the environment variable to TA_DATA_CAPTURE_HTTP_HEADERS_RESPONSE=false to overwrite the value set in the configuration file or through the code. To check the entire list of environment variables, refer to these links:

• HT environment variables
• TA environment variables

Configuration file

You can overwrite the location of the configuration JSON or YAML file by providing the path in the environment variable TA_CONFIG_FILE. The path of the configuration file can also be set in the code, as shown in the snippet below:

// loads the config from the specified file and env vars
cfg := config.LoadFromFile("path/to/config.yml")
...

Sample YAML file

The following is a sample YAML file to configure the various values like collector and OPA address. You can configure based on your environment’s requirements.

// used to identify your service on the platform UI. Rename this to the service name
// you want to identify your app.
service_name: my-go-service
// agent enabled
enabled: true
// otel trace propagation formats. allowed types are TRACECONTEXT and B3
propagation_formats:
  - TRACECONTEXT
// request and response data capture.
data_capture:
  http_headers:
    request: true
    response: true
  http_body:
    request: true
    response: true
  rpc_metadata:
    request: true
    response: true
  rpc_body:
    request: true
    response: true
  // maximum body size captured. default is 128KiB
  body_max_size_bytes: 131072
  // maximum body size involved in processing such as blocking evaluation.
  body_max_processing_size_bytes: 1048576
// traces reporting endpoint config.
reporting:
  endpoint: localhost:4317
  secure: false
  trace_reporter_type: OTLP
opa:
  enabled: true
  endpoint: http://localhost:8181/
  poll_period_seconds: 30
blocking_config:
  enabled: true
  debug_log: false
  modsecurity:
    enabled: true
  // whether to consider the request body when doing blocking evaluation.
  evaluate_body: true
  region_blocking:
    enabled: true
  // skip internal requests to this service when doing blocking evaluation. i.e
  // requests originating from private IPs
  skip_internal_request: true
  // config for Traceable Platform Agent endpoint to fetch blocking evaluation rules 
  remote_config:
    enabled: true
    endpoint: localhost:5441
    poll_period_seconds: 30

You can check more documentation on configuration option by navigating to the proto files defining the configurations:

Verify deployment

To verify the deployment of the Go agent, log into your Traceable Dashboard and click on Services. If the deployment was successful, you will see your service listed under the Name column. If you have enabled blocking you should be able to see additional attributes on your spans such as traceableai.blocked, traceableai.blocked.exemptions.count and traceableai.blocked.violations.count.

Upgrade

To upgrade the agent, run go get github.com/Traceableai/goagent && go mod tidy in your Go app directory. This upgrades to the latest version. Since the Go agent is SDK based, you might need to fix any compile issues. You can also navigate to the releases page and get the version you want and change it in your go.mod file. Then run go mod tidy.

Uninstall

Complete the following steps to uninstall the Go agent:

1. Comment out or remove the instrumentation code added to your app.
2. Remove the Traceable Go agent package from the go.mod file.
3. Rerun go mod tidy in the same folder as your go.mod.
4. Rebuild your go app.