> ## Documentation Index
> Fetch the complete documentation index at: https://statsig-4b2ff144-serverless-cloudflare.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Go Server Core SDK (Beta)
> Statsig's next-gen Go Server SDK built on our [Server Core](/server-core) framework
Go Core on Github
## Setup the SDK
via the `go get` CLI:
You can install the latest version of the SDK:
```
go get github.com/statsig-io/statsig-server-core/statsig-go@latest
```
or a specific version of the SDK:
```
go get github.com/statsig-io/statsig-server-core/statsig-go@v0.7.2
```
Or, add a dependency on the most recent version of the SDK in go.mod:
```
require (
github.com/statsig-io/statsig-server-core/statsig-go v0.7.2
)
```
See the [Releases tab in GitHub](https://github.com/statsig-io/statsig-server-core/releases) for the latest versions.
:::note
Running `go get` will only work if you're working inside a module project with a go.mod file. If working outside of a module project, you can clone the repo here: [https://github.com/statsig-io/statsig-server-core/tree/main/statsig-go](https://github.com/statsig-io/statsig-server-core/tree/main/statsig-go) instead.
:::
Run the following commands to install the necessary binaries and set environment variables:
```
go install github.com/statsig-io/statsig-server-core/statsig-go/cmd/post-install@latest
// Run the following commands based on your OS:
// macOS:
export PATH="$PATH:$(go env GOPATH)/bin"
source ~/.zshrc
// Linux:
export PATH="$PATH:$(go env GOPATH)/bin"
source ~/.bashrc
// Windows (PowerShell):
$env:PATH += ";$env:USERPROFILE\.statsig\bin"
post-install
```
The system should prompt you to set the environment variables using a statsig.env or statsig.env.ps1 file that was generated during the post-install script.
Follow the instructions to set the environment variables.
```
// E.g. - the command will look something like this:
macOS:
source /Users/Your-User-Name/.statsig_env
Windows (PowerShell):
. "C:\Users\Your-User-Name\.statsig_env.ps1"
```
Users can also add in the variables to their .bashrc, .zshrc, or .ps1 file to load them automatically.
:::note
You may need to have gcc installed on your system in order to run the SDK on Windows.
See [FAQ](/server-core/go-core#faq) if you run into any issues with installation.
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Server Secret Keys should always be kept private. If you expose one, you can disable and recreate it in the Statsig console.
There is also an optional parameter named `options` that allows you to pass in a StatsigOptions to customize the SDK.
```go expandable theme={null}
import (
statsig "github.com/statsig-io/statsig-server-core/statsig-go/src"
)
options := statsig.NewStatsigOptionsBuilder().WithOutputLogLevel("DEBUG").Build()
s, err := statsig.NewStatsig("secret-key", *options)
if err != nil {
// Initialize the SDK with the secret key and options
s.Initialize()
}
// Or if you want to initialize the Statsig client with more details
details, err := s.InitializeWithDetails()
json, err := json.MarshalIndent(details, "", " ")
fmt.Println("Initialize With Details:", string(json))
/*
*** Sample Output ***
Initialize With Details: {
"duration": 95,
"init_success": true,
"is_config_spec_ready": true,
"is_id_list_ready": null,
"source": "Network",
"failure_details": null
}
*/
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to create logic branches in code that can be rolled out to different users from the Statsig Console. Gates are always **CLOSED** or **OFF** (think `return false;`) by default.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```go theme={null}
user := statsig.NewStatsigUserBuilder().WithUserID("a-user").Build()
if s.CheckGate(*user, "a_gate", nil) {
// Gate is on, enable new feature
} else {
// Gate is off
}
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```go theme={null}
user := statsig.NewStatsigUserBuilder().WithUserID("a-user").Build()
// You can disable exposure logging for this specific check
dynamicConfigOptions := &statsig.GetDynamicConfigOptions{DisableExposureLogging: false}
dynamic_config := "a_config"
config := s.GetDynamicConfig(*user, dynamic_config, dynamicConfigOptions)
// Access the config values
str_val := config.GetString("str_val", "default_str_val") // returns String
int_val := config.GetNumber("number_val", 100) // returns float64
bool_val := config.GetBool("bool_val", false) // returns bool
interface_val := config.GetSlice("interface_val", "default_interface_val") // returns interface{}
map_val := config.GetMap("map_val", "default_map_val") // returns map[string]interface{}
// The config object also provides metadata about the evaluation
fmt.Println(config.RuleID) // The ID of the rule that served this config
fmt.Println(config.IDType) // The type of the evaluation (experiment, config, etc)
```
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but often recommend the use of [layers](/layers), which make parameters reusable and let you run mutually exclusive experiments.
```go theme={null}
user := statsig.NewStatsigUserBuilder().WithUserID("a-user").Build()
// Getting values with GetExperiment
experimentOptions := &statsig.GetExperimentOptions{DisableExposureLogging: false}
experiment := s.GetExperiment(*user, "a_test_experiment", experimentOptions)
str_val := experiment.GetString("str_val", "default_str_val") // returns String
int_val := experiment.GetNumber("number_val", 100) // returns float64
// Getting values with GetLayer
layerOptions := &statsig.GetLayerOptions{DisableExposureLogging: false}
layer := s.GetLayer(user, "a_test_experiment", layerOptions)
str_val := layer.GetString("str_val", "default_str_val") // returns String
int_val := layer.GetNumber("number_val", 100) // returns float64
```
### Retrieving Feature Gate Metadata
In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object:
```go theme={null}
user := statsig.NewStatsigUserBuilder().WithUserID("a-user").Build()
checkGateOptions := &statsig.CheckGateOptions{DisableExposureLogging: false}
featureGate := s.GetFeatureGate(*user, "a gate", checkGateOptions)
```
### Parameter Stores
Sometimes you don't know whether you want a value to be a Feature Gate, Experiment, or Dynamic Config yet. If you want on-the-fly control of that outside of your deployment cycle, you can use Parameter Stores to define a parameter that can be changed into at any point in the Statsig console. Parameter Stores are optional, but parameterizing your application can prove very useful for future flexibility and can even allow non-technical Statsig users to turn parameters into experiments.
### Getting a Parameter Store
```go theme={null}
// Get a Parameter Store by name
s, _ := statsig.NewStatsig("secret-key", options)
user := statsig.NewStatsigUserBuilder().WithUserID("a-user").Build()
options := statsig.ParameterStoreOptions{DisableExposureLogging: false}
paramStore := s.GetParameterStore(*user, "paramStore", &options)
```
### Retrieving Parameter Values
Parameter Store provides methods for retrieving values of different types with fallback defaults.
```go theme={null}
//String parameters
stringVal := paramStore.GetString("str_param", "default_value")
//Boolean parameters
boolVal := paramStore.GetBoolean("bool_param", false)
//Numeric parameters
intVal := paramStore.GetInt("int_param", 0)
int64Val := paramStore.GetInt64("int64_param", 0)
float64Val := paramStore.GetFloat64("float64_param", 0.0)
//Complex parameters
objectParam := map[string]interface{}{
"value1": "string",
"value2": 1,
"value3": 1.0,
}
objectVal := paramStore.GetMap("obj_param", objectParam)
arrayParam := []interface{}{"val1", "val2", "val3"}
arrayVal := paramStore.GetInterface("array_param", arrayParam)
```
### Evaluation Options
You can disable exposure logging when retrieving a parameter store:
```go theme={null}
options := statsig.ParameterStoreOptions{DisableExposureLogging: false}
paramStore := s.GetParameterStore(*user, "param_store", &options)
```
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig—simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```go theme={null}
event := map[string]interface{}{
"name": "sample event",
"value": "event",
"metadata": map[string]string{
"val_1": "log val 1",
},
}
user := statsig.NewStatsigUserBuilder().WithUserID("a-user").Build()
s.LogEvent(*user, event)
```
## Manual Exposures
By default, the SDK will automatically log an exposure event when you check a gate, get a config, get an experiment, or get a layer. However, there are times when you may want to log an exposure event manually. For example, if you're using a gate to control access to a feature, but you don't want to log an exposure until the user actually uses the feature, you can use manual exposures.
All of the main SDK functions (`CheckGate`, `GetDynamicConfig`, `GetExperiment`, `GetLayer`) accept an optional options parameter with `DisableExposureLogging` field. When this is set to `true`, the SDK will not automatically log an exposure event. You can then manually log the exposure at a later time using the corresponding manual exposure logging method:
```go theme={null}
result := statsig.CheckGate(aUser, "a_gate_name", statsig.CheckGateOptions{DisableExposureLogging: true})
```
```go theme={null}
statsig.ManuallyLogGateExposure(aUser, "gate_name")
```
```go theme={null}
config := statsig.GetDynamicConfig(aUser, "config_name", statsig.GetDynamicConfigOptions{DisableExposureLogging: true})
```
```go theme={null}
statsig.ManuallyLogDynamicConfigExposure(aUser, "config_name")
```
```go theme={null}
experiment := statsig.GetExperiment(aUser, "experiment_name", statsig.GetExperimentOptions{DisableExposureLogging: true})
```
```go theme={null}
statsig.ManuallyLogExperimentExposure(aUser, "experiment_name")
```
```go theme={null}
layer := statsig.GetLayer(aUser, "layer_name", statsig.GetLayerOptions{DisableExposureLogging: true})
paramValue := layer.Get(aUser, "param_name")
```
```go theme={null}
statsig.ManuallyLogLayerParameterExposure(aUser, "layer_name", "param_name")
```
## Statsig User
The `StatsigUser` object represents a user in Statsig. You must provide a `userID` or at least one of the `customIDs` to identify the user.
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. At least one ID (userID or customID) is required because it's needed to provide a consistent experience for a given user (click here)
Besides userID, we also have email, ip, userAgent, country, locale and appVersion as top-level fields on StatsigUser. In addition, you can pass any key-value pairs in an object/dictionary to the custom field and be able to create targeting based on them.
### Private Attributes
Private attributes are user attributes that are used for evaluation but are not forwarded to any integrations. They are useful for PII or sensitive data that you don't want to send to third-party services.
## Statsig Options
You can pass in an optional parameter `options` in addition to `sdkKey` during initialization to customize the Statsig client. Here are the available options that you can configure.
### Parameters
Custom URL for fetching feature specifications.
Custom URL for logging events.
Environment parameter for evaluation.
How often events are flushed to Statsig servers (in milliseconds).
Maximum number of events to queue before forcing a flush.
How often the SDK updates specifications from Statsig servers (in milliseconds).
Controls the verbosity of SDK logs.
Disables country lookup based on IP address. Set to `true` to improve performance if country-based targeting is not needed.
Disables user agent parsing. Set to `true` to improve performance if device/browser-based targeting is not needed.
When set to true, the SDK will wait for country lookup data (e.g., GeoIP or YAML files) to fully load during initialization. This may slow down by \~1 second startup but ensures that IP-to-country parsing is ready at evaluation time.
When set to true, the SDK will wait until user agent parsing data is fully loaded during initialization. This may slow down by \~1 second startup but ensures that parsing of the user's userAgent string into fields like browserName, browserVersion, systemName, systemVersion, and appVersion is ready before any evaluations.
When set to true, the SDK will not log any events or exposures.
Maximum time in milliseconds to wait for SDK initialization to complete. If initialization takes longer than this timeout, the SDK will continue to operate but may return default values until initialization completes.
When set to true, the SDK will fallback to using the Statsig API directly if custom adapters (like local file adapters) fail to load configurations.
***
### Example Options Usage
```go expandable theme={null}
import (
statsig "github.com/statsig-io/statsig-server-core/statsig-go/src"
)
// Initialize StatsigOptions with custom parameters
options := statsig.NewStatsigOptionsBuilder().
WithSpecsUrl("https://example.com/specsUrl").
WithLogEventUrl("https://example.com/logUrl").
WithEnvironment("production").
WithEventLoggingFlushIntervalMs(2000).
WithEventLoggingMaxQueueSize(5000).
WithSpecsSyncIntervalMs(1000).
WithOutputLogLevel("DEBUG").
WithDisableCountryLookup(true).
WithDisableUserAgentParsing(true).
WithWaitForCountryLookupInit(false).
WithInitTimeoutMs(3000).
WithFallbackToStatsigApi(false).
Build()
// Pass the options object when initializing the Statsig client
s, err := statsig.NewStatsig("secret-key", *options)
s.Initialize()
```
## Shutting Statsig Down
Because we batch and periodically flush events, some events may not have been sent when your app/server shuts down. To make sure all logged events are properly flushed, you should call `shutdown()` before your app/server shuts down:
```go theme={null}
// Method signature
func (s *Statsig) Shutdown() {}
// example usage
s, err := statsig.NewStatsig("secret-key", statsig.StatsigOptions{})
s.Shutdown()
```
### Flush Events
```go theme={null}
// Method signature
func (s *Statsig) FlushEvents() {}
// example usage
s, err := statsig.NewStatsig("secret-key", statsig.StatsigOptions{})
s.FlushEvents()
```
## Local Overrides
Local Overrides are a way to override the values of gates, configs, experiments, and layers for testing purposes. This is useful for local development or testing scenarios where you want to force a specific value without having to change the configuration in the Statsig console.
```go theme={null}
import (
statsig "github.com/statsig-io/statsig-server-core/statsig-go/src"
)
options := statsig.NewStatsigOptionsBuilder().WithOutputLogLevel("DEBUG").Build()
s, _ := statsig.NewStatsig("secret-key", *options)
s.OverrideLayer("layer_name", map[string]interface{}{"key": "value"}, "test-user-id")
s.OverrideGate("gate_name", true, "test-user-id")
s.OverrideDynamicConfig("config_name", map[string]interface{}{"key": "value"}, "test-user-id")
s.OverrideExperiment("experiment_name", map[string]interface{}{"key": "value"}, "test-user-id")
s.OverrideExperimentByGroupName("experiment_name", "group_name", "test-user-id")
```
## FAQ
##### Installation FAQs
#### How do I fix undefined symbol errors/linker errors?
You may need to reset your environment variables to those found in the statsig.env or statsig.env.ps1 file which was generated during the post-install script. Running the command sets the environment variables for the current terminal session. Users may need to add in the variables to their .bashrc, .zshrc, or .ps1 file to load them automatically.