- 16 May 2023
- 5 Minutes to read
- Print
- PDF
Go
- Updated on 16 May 2023
- 5 Minutes to read
- Print
- PDF
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
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:
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:
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 Platformcfg.Tracing.DataCapture.HTTPHeaders.Request
is set totrue
. 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:
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:
- Comment out or remove the instrumentation code added to your app.
- Remove the Traceable Go agent package from the
go.mod
file. - Rerun
go mod tidy
in the same folder as yourgo.mod
.
- Rebuild your go app.