• SDKS
No results for ""


Reading flags from a file

Read time: 2 minutes
Last edited: Jul 15, 2020


This topic explains how to run feature flags from a file when you're using a server-side SDK.

If you're performing automated tests or prototyping, you might want to run application code that uses feature flags without connecting to LaunchDarkly. LaunchDarkly SDKs in offline mode return the default value for each flag evaluation. Default is not an actual property of the flag. It is the value that you specified as a fallback in your program code when you evaluated the flag.

However, in the server-side SDKs, you can also use files to configure the feature flag state you desire.

This feature is currently available in the following server-side SDKs:

  • Go (version 4.4.0 and up)
  • Java (4.5.0 and up)
  • .NET (5.5.0 and up)
  • Ruby (5.4.0 and up)
  • Python (6.6.0 and up)
  • Node.js (5.7.0 and up)
  • PHP (5.3.0 and up)
Do not use file-based flag values in production environments
Always configure production environments to receive flag updates from LaunchDarkly. Only use file-based flags in testing and pre-production environments.

Creating a flag data file

Flag data files can be either JSON or YAML.

They contain up to three properties:

  • flags: Feature flag definitions. These can contain all the same kinds of rules and targets that you can define in a LaunchDarkly feature flag, which allows the flag to produce different values for different users.
  • flagValues: Simplified feature flags that specify only a value, and produce the same value for all users.
  • segments: User segment definitions. You will only use this property if you have feature flags that use segments.
YAML files have limitations
In some of the SDKs, YAML support requires an additional dependency. YAML is not available in PHP.

The format of the data in flags and segments is defined by the LaunchDarkly application and is subject to change. Rather than trying to construct these objects yourself, it's simpler to request existing flags directly from the LaunchDarkly server in JSON format and use this output as the starting point for your file.

Get the flags from https://app.launchdarkly.com/sdk/latest-all. Pass your SDK key in the Authorization header.

For instance, in Linux, you could use this command:

1curl -H "Authorization: EXAMPLE_SDK_KEY" https://app.launchdarkly.com/sdk/latest-all >flagdata.json

The output will look something like this, with many more properties:

2 "flags": {
3 "flag-key-1": {
4 "key": "flag-key-1",
5 "on": true,
6 "variations": [ "a", "b" ]
7 }
8 },
9 "segments": {
10 "segment-key-1": {
11 "key": "segment-key-1",
12 "includes": [ "user-key-1" ]
13 }
14 }

Data in this format allows the SDK to exactly duplicate all the kinds of flag behavior LaunchDarkly supports. However, in many cases you do not need this complexity. You may want to simply set specific flag keys to specific values.

For that, you can use a much simpler format:

2 "flagValues": {
3 "my-string-flag-key": "value-1",
4 "my-boolean-flag-key": true,
5 "my-integer-flag-key": 3
6 }

It is also possible to specify both flags and flagValues, if you want some flags to have simple values and others to have complex behavior. However, it is an error to use the same flag key or segment key more than once, either in a single file or across multiple files.

Configuring the client to use a file

In all of the SDKs that have this feature, you can specify either a single file or multiple files. In all of them except PHP, you can also specify whether the SDK should reload the file data if it detects that you have modified a file. For instance, you could verify that your application behaves correctly when a flag changes.

The examples below show how to configure the client to use two data files called file1.json and file2.json. The client assumes these two files are in the current working directory, but you can specify any relative or absolute file path. It also enables automatic reloading, if supported.

1import (
2 ld "gopkg.in/launchdarkly/go-server-sdk.v4"
3 "gopkg.in/launchdarkly/go-server-sdk.v4/ldfiledata"
4 "gopkg.in/launchdarkly/go-server-sdk.v4/ldfilewatch"
7fileSource, err := ldfiledata.NewFileDataSourceFactory(
8 ldfiledata.FilePaths("file1.json", "file2.json"),
9 ldfiledata.UseReloader(ldfilewatch.WatchFiles))
11config := ld.DefaultConfig
12config.UpdateProcessorFactory = fileSource
13config.SendEvents = false
15client := ld.MakeCustomClient("sdk key", config, 5*time.Second)

If you do not want your code to connect to LaunchDarkly at all, you will normally want to prevent the SDK from trying to send analytics events, so the option for disabling events is also included in these examples. Also, since there will be no LaunchDarkly connection, you do not have to use a valid SDK key; the SDK key parameter is still required but can be any string.

If any of the specified files is missing or invalid, the SDK does not use any of the file data and logs an error message instead.