---
title: "Go"
slug: "go"
updated: 2023-05-16T09:32:27Z
published: 2023-05-16T09:32:27Z
canonical: "traceabledocs.document360.io/go"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_go_deployment_architecture.png)

---

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

| Servers | Clients |
| --- | --- |
| Net HTTP net/http | Net Http net/http |
| GRPC Server google.golang.org/grpc | GRPC Client google.golang.org/grpc |
| Gorilla Mux github.com/gorilla/mux | SQL database/sql |

---

## Download Go agent

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

```actionscript
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:

```actionscript
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:

```actionscript
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:

```actionscript
# 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.

```actionscript
# 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](https://github.com/Traceableai/goagent#go-agent)
- [Examples](https://github.com/Traceableai/goagent/tree/main/_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.

```actionscript
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](https://github.com/hypertrace/agent-config/blob/main/ENV_VARS.md)
- [TA environment variables](https://github.com/Traceableai/agent-config/blob/main/ENV_VARS.md)

### 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:

```actionscript
// 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.

```yaml
// 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.