Go SDK reference

Overview

This topic documents how to get started with the Go SDK, and links to reference information on all of the supported features.

Get started

After you complete the Getting Started process, follow these instructions to start using the LaunchDarkly SDK in your Go application.

Install the SDK

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.
• Otherwise, use the go get command and specify the SDK version, such as go get github.com/launchdarkly/go-server-sdk/v7.

There are several packages that you can import, depending on which features you are using. We recommend following:

1
import (
2
    // go-sdk-common/v3/ldcontext defines LaunchDarkly's model for contexts
3
    "github.com/launchdarkly/go-sdk-common/v3/ldcontext"
4
5
    // go-sdk-common/v3/ldmigration defines LaunchDarkly's model for migration feature flags
6
    // (only needed if you are working with migration flags)
7
    "github.com/launchdarkly/go-sdk-common/v3/ldmigration"
8
9
    // go-server-sdk/v7 is the main SDK package - here we are aliasing it to "ld"
10
    ld "github.com/launchdarkly/go-server-sdk/v7"
11
12
    // go-server-sdk/v7/ldcomponents is for advanced configuration options
13
    "github.com/launchdarkly/go-server-sdk/v7/ldcomponents"
14
15
    // go-server-sdk/v7/ldplugins allows you to add plugins to the main SDK
16
    "github.com/launchdarkly/go-server-sdk/v7/ldplugins"
17
18
    // observability-sdk/go is the observability plugin - here we are aliasing it to "ldobserve"
19
    // this package requires go-server-sdk/v7 version 7.11 or later
20
    ldobserve "github.com/launchdarkly/observability-sdk/go"
21
)

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.

Initialize the client

After you install and import the SDK, you have two options:

• Create an instance of LDScopedClient. This is a wrapper around LDClient that lets you specify the evaluation context to use for all operations, so you do not need to specify a context for each method call. The scoped client’s context is a multi-context, and you can update the multi-context with additional or updated associated contexts any time.
• Create a single, shared instance of LDClient. This client requires that you specify an evaluation context in each method call.

Both options require that you specify your SDK key. The SDK key authorizes your application to connect to a particular environment within LaunchDarkly.

This example assumes you’ve imported the LaunchDarkly SDK package as ld, as shown above.

1
client, _ := ld.MakeCustomClient("sdk-key-123abc",
2
  ld.Config{
3
    // optional observability plugin, requires Go SDK v7.11+
4
    Plugins: []ldplugins.Plugin{
5
      ldobserve.NewObservabilityPlugin()
6
    },
7
  }, 5*time.Second)
8
9
context := ldcontext.NewBuilder("context-key-123abc").
10
    Name("Sandy").
11
    Build()
12
13
scopedClient := ld.NewScopedClient(client, context)

The final argument to MakeClient or MakeCustomClient is a timeout parameter. In these examples, 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 and MakeCustomClient.

To learn more about the observability plugin, read Go SDK observability reference. To learn more about the specific configuration options available for this SDK, read Config.

Evaluate a context

After you initialize the client, you can check which variation a particular context should receive for a given feature flag. If you are using LDScopedClient, you create the scoped client with the context, and then evaluate the flag. If you are using LDClient, you pass the context to the flag evaluation method.

Here’s how:

1
import (
2
    "github.com/launchdarkly/go-sdk-common/v3/ldcontext"
3
)
4
5
flagKey := "flag-key-123abc"
6
context := ldcontext.NewBuilder("context-key-123abc").
7
    Name("Sandy").
8
    Build()
9
10
scopedClient := ld.NewScopedClient(client, context)
11
// LDScopedClient is in beta and may change without notice.
12
13
showFeature, _ := scopedClient.BoolVariation(flagKey, false)
14
if showFeature {
15
    // Application code to show the feature
16
} else {
17
    // The code to run if the feature is off
18
}

To learn more, read Evaluating flags and Flag evaluation reasons. For more information about how contexts are specified, read Context configuration.

Use Go contexts with LDScopedClient

As described above, one advantage of using LDScopedClient is that you can specify the evaluation context to use for all operations, and do not need to specify a context for each method call. You can update the scoped client’s current context with additional or updated associated contexts any time.

After you create a scoped client, we recommend adding it your Go context. Another advantage of using LDScopedClient is that you can pass the scoped client to any logic that already takes a Go context (context.Context), using utility methods provided in the SDK. This means the scoped client is implicitly passed around through all of your code that uses context.Context, and you can access the scoped client anywhere in your application logic.

Here’s how to add and retrieve your LDScopedClient from your Go context:

1
scopedClient := ld.NewScopedClient(client, ldContext)
2
ctx := ld.GoContextWithScopedClient(context.Background(), scopedClient)
3
otherFunction(ctx)
4
// LDScopedClient is in beta and may change without notice.

An example of how this might apply in your application is if you have HTTP middleware, and you want to pass an LDScopedClient into the http.Request’s Go context:

1
func LDScopedClientMiddleware(client *LDClient) func(http.Handler) http.Handler {
2
  return func(next http.Handler) http.Handler {
3
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
4
        scopedClient := NewScopedClient(client, ldcontext.New("context-key-123abc"))
5
        ctx := GoContextWithScopedClient(r.Context(), scopedClient)
6
        next.ServeHTTP(w, r.WithContext(ctx))
7
    })
8
  }
9
}
10
11
func requestLogic(r *http.Request) {
12
  featureFlagEnabled := MustGetScopedClient(r.Context()).BoolVariation("flag-key-123abc", false)
13
  // use featureFlagEnabled...
14
}

To learn more, read GoContextWithScopedClient, GetScopedClient, and MustGetScopedClient.

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:

1
var config ld.Config
2
config.HTTP = ldcomponents.HTTPConfiguration().
3
    ProxyURL("https://web-proxy.domain.com:8080")

Shut down the client

Shut down the client when your application terminates. To learn more, read Shutting down.

Supported features

This SDK supports the following features:

• Anonymous contexts and users
• Big segments
• Configuration, including
  • Application metadata configuration
  • Migration configuration
  • Service endpoint configuration
• Context configuration
• Data saving mode
• Evaluating flags
• Flag evaluation reasons
• Flushing events
• Getting all flags
• Hooks
• Identifying and changing contexts
• Logging configuration
• Migrations
• Monitoring SDK status
• Observability
• Offline mode
• OpenTelemetry
• Private attributes
• Reading flags from a file
• Relay Proxy configuration
  • Using proxy mode
  • Using daemon mode
• Secure mode
• Sending custom events
• Shutting down
• Storing data
• Subscribing to flag changes
• Test data sources
• Web proxy configuration