Go SDK reference
Read time: 2 minutes
Last edited: Aug 12, 2022
Overview
This topic documents how to get started with the Go SDK, and links to reference information on all of the supported features.
LaunchDarkly's SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and a sample application:
Resource | Location |
---|---|
SDK API documentation | SDK API docs |
GitHub repository | go-server-sdk |
Sample application | hello-go |
Published module | gopkg.in |
The LaunchDarkly Go SDK, version 5.0 and higher, is compatible with Go 1.14 and higher.
Getting started
After you complete the Getting Started process, follow these instructions to start using the LaunchDarkly SDK in your Go application.
First, install the LaunchDarkly SDK as a dependency in your application. How you do this depends on what dependency management system you are using:
- If you are using the standard Go modules system, import the SDK packages in your code and
go build
will automatically download them. The SDK and its dependencies are modules. - If you are using
dep
, import the SDK packages in your code and rundep ensure
. - Otherwise, use the
go get
command and specify the SDK version, such asgo get gopkg.in/launchdarkly/go-server-sdk.v5
.
There are several packages that you can import, depending on which features you are using. You usually need the following:
import (// go-sdk-common.v2/lduser defines LaunchDarkly's model for user properties"gopkg.in/launchdarkly/go-sdk-common.v2/lduser"// go-server-sdk.v5 is the main SDK package - here we are aliasing it to "ld"ld "gopkg.in/launchdarkly/go-server-sdk.v5"// go-server-sdk.v5/ldcomponents is for advanced configuration options"gopkg.in/launchdarkly/go-server-sdk.v5/ldcomponents")
It is good practice to pin your dependencies to a specific version. Refer to the SDK releases page to identify the latest version. When you update your version of go-server-sdk
, you should also update go-sdk-common
.
After you install and import the SDK, create a single, shared instance of LDClient
. Specify your SDK key here to authorize your application to connect to a particular environment within LaunchDarkly.
It's important to make LDClient
a singleton. The client instance maintains internal state that allows LaunchDarkly to serve feature flags without making any remote requests. Do not instantiate a new client with every request.
This example assumes you've imported the LaunchDarkly SDK package as ld
, as shown above.
client, _ := ld.MakeClient("YOUR_SDK_KEY", 5 * time.Second)
The second argument to MakeClient
is a timeout parameter. In this example, you are telling the SDK that it can spend up to five seconds attempting to connect to LaunchDarkly services before returning to your application. For more details about what the timeout means and what happens if initialization fails, read MakeClient
.
The second return type in these code samples ( _
) represents an error in case the LaunchDarkly client does not initialize. Consider naming the return value and using it with proper error handling.
Using the LDClient
methods, you can check which variation a particular user should receive for a given feature flag. To learn more, read Evaluating flags and Flag evaluation reasons. For more information about how user properties are specified, read User configuration.
In this example, the user key is an email address:
import ("gopkg.in/launchdarkly/go-sdk-common.v2/lduser")flagKey := "some-flag-key"user := lduser.NewUserBuilder("example-user-key").Name("Sandy").Build()showFeature, _ := client.BoolVariation(flagKey, user, false)if showFeature {// Application code to show the feature} else {// The code to run if the feature is off}
HTTPS Proxy
Go's standard HTTP library provides a built-in HTTPS proxy. If the HTTPS_PROXY
environment variable is present, then the SDK will proxy all network requests through the URL provided.
Here is an example:
export HTTPS_PROXY=https://web-proxy.domain.com:8080
You can also specify a proxy programmatically through the SDK configuration:
import (ld "gopkg.in/launchdarkly/go-server-sdk.v5""gopkg.in/launchdarkly/go-server-sdk.v5/ldcomponents")var config ld.Configconfig.HTTP = ldcomponents.HTTPConfiguration().ProxyURL("https://web-proxy.domain.com:8080")
Shutting down
Lastly, shut down the client when your application terminates. To learn more, read Shutting down.
Supported features
This SDK supports the following features:
- Aliasing users
- Big Segments
- Configuration
- Evaluating flags
- Flag evaluation reasons
- Flushing events
- Getting all flags
- Identifying and changing users
- Logging configuration
- Monitoring SDK status
- Offline mode
- Reading flags from a file
- Relay Proxy configuration
- Secure mode
- Sending custom events
- Shutting down
- Storing data
- Subscribing to flag changes
- Test data sources
- User configuration
- Web proxy configuration