Skip to content

Commit c0dfd8c

Browse files
gofeatureflag-botkodiakhq[bot]
gofeatureflag-bot
and
kodiakhq[bot]
authored
Create a new documentation version v1.52.0 (#4988)
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
1 parent b77b736 commit c0dfd8c

File tree

110 files changed

+9464
-3
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

110 files changed

+9464
-3
lines changed

‎website/versioned_docs/version-v1.52.0/_category_.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"position": 0,
3+
"collapsible": true,
4+
"collapsed": false
5+
}

‎website/versioned_docs/version-v1.52.0/concepts/_category_.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"position": 30,
3+
"collapsible": true,
4+
"collapsed": true,
5+
"label": "💡 Concepts",
6+
"link": {
7+
"title": "💡 Concepts"
8+
}
9+
}

‎website/versioned_docs/version-v1.52.0/concepts/architecture.mdx‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
sidebar_position: 40
3+
description: What is the GO Feature Flag architecture
4+
---
5+
# 🏗️ Architecture
6+
7+
## Overview
8+
GO Feature Flag is a feature flagging system that allows you to manage feature flags in your application.
9+
The architecture is really simple and efficient with the goal to be easy to use and let you experiment with feature flags in your application as fast as possible.
10+
11+
In most cases you have 1 microservice running the `relay-proxy` and multiple applications running the SDKs, nothing else.
12+
13+
:::note
14+
GO Feature Flag can also be run without the `relay-proxy` if you only use the GO Module.
15+
16+
The relay-proxy is an API layer on top of the GO Module, so it has the same logic inside.
17+
:::
18+
19+
## Architecture concepts
20+
21+
![GO Feature Flag architecture](/docs/openfeature/architecture.svg)
22+
23+
### 🧩 OpenFeature Providers
24+
GO Feature Flag is working in collaboration with OpenFeature to be integrated with all the languages supported by GO Feature Flag.
25+
To achieve this goal, we have created the OpenFeature providers that combines with OpenFeature SDKs to allow you to use GO Feature Flag in your application.
26+
27+
> **OpenFeature Providers**
28+
> An SDK-compliant implementation which resolves flag values from a particular flag management system, allowing the use of the Evaluation API as an abstraction for the system in question.
29+
30+
This is what developers will use to interact with GO Feature Flag in their application.
31+
32+
### ↔️ Relay-Proxy
33+
The relay-proxy is the only component you have to run in your infrastructure to use GO Feature Flag with the different SDKs.
34+
This is a standalone GO binary that you can run in your infrastructure to expose the GO Feature Flag API to your applications.
35+
36+
:::info
37+
Want to know more about the relay-proxy? [Check the relay-proxy documentation](../relay-proxy).
38+
:::
39+
40+
The relay-proxy is designed to be simple, lightweight, and stateless. It operates without the need for any databases or complex systems, as it loads feature flag configuration files from a specified location and stores them in memory.
41+
42+
### ⬇️ Internal concepts
43+
**You have 3 main concepts in GO Feature Flag architecture:**
44+
- [retrievers](./retriever): This is the component in charge of fetching the feature flag configuration.
45+
- [notifiers](./notifier): This is the component in charge of notifying external systems that a flag configuration has changed.
46+
- [exporters](./exporter): This is the component in charge of exporting the flag evaluation results for analytics or monitoring.
47+
48+
Those 3 concepts are the core of GO Feature Flag and allows you to integrate GO Feature Flag in your current ecosystem with a minimum of effort.
49+
Every component is designed to be as lightweight as possible and to be easy to configure.
50+
51+
## 🧑‍💻 Technologies
52+
53+
- GO Feature Flag is written in `golang`.
54+
- The `retrievers`, `notifiers`, and `exporters` are using official libraries to interact with external systems.
55+
- Providers are written in the language of the system they are interacting with and we are limiting the dependencies to the minimum to be as lightweight as possible.

‎website/versioned_docs/version-v1.52.0/concepts/evaluation-context.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
sidebar_position: 20
3+
description: An evaluation context in a feature flagging system is crucial for determining the output of a feature flag evaluation. It's a collection of pertinent data about the conditions under which the evaluation is being made.
4+
---
5+
# 🔎 Evaluation Context
6+
7+
## Overview
8+
All GO Feature Flag SDKs use an evaluation context to determine which variation of a feature flag to serve.
9+
10+
An evaluation context in a feature flagging system is crucial for determining the output of a feature flag evaluation.
11+
12+
It's a collection of pertinent data about the conditions under which the evaluation is being made.
13+
his data can be supplied through a mix of static information _(server name, IP, etc ...)_ and dynamic inputs
14+
_(information about the user performing the action, etc ...)_, along with state information that is implicitly carried
15+
through the execution of the program.
16+
17+
## About contexts
18+
GO Feature Flag evaluation contexts are data objects representing users, devices, organizations, and other entities that are used to determine which variation of a feature flag to serve.
19+
20+
The context is used to evaluate the [targeting queries](../configure_flag/target-with-flags.mdx) and determine which variation of a feature flag to serve to a user.
21+
22+
:::info
23+
**Only the evaluation context attributes you provide are available for targeting queries.**
24+
25+
If you want to use a specific attribute in your targeting queries, you must include it in the evaluation context.
26+
If not present the query will not apply.
27+
:::
28+
29+
## Example context: Mike Wazowski at Monsters, Inc.
30+
31+
As an example, let's assume Mike Wazowski is one of your end users. He is a scare assistant who works on the scare floor at Monsters, Inc with James P. Sullivan.
32+
Mike has two mobile devices, an Android phone and an iPad tablet. Mike uses your application on both devices as part of his work.
33+
34+
Given this information, you may know the following things about Mike Wazowski:
35+
36+
- his name, email and job title _("Scare assistant")_
37+
- his employee ID _(used for the targetingKey)_
38+
- his work station position _("scare floor")_
39+
- his organization's name _("Monsters, Inc."),_
40+
- his device's type _("iPad")_
41+
- his coworker's name _("James P. Sullivan")_
42+
43+
Here is an example of what the data structure for Mike Wazowski evaluation context object might look like:
44+
45+
```json title="evaluation context"
46+
{
47+
"targetingKey": "34c7f8ab-6d14-4aa6-a77f-effc6245da6f",
48+
"firstname": "Mike",
49+
"lastname": "Wazowski",
50+
"email": "mike.wazowski@monster.inc",
51+
"organization": "Monsters, Inc.",
52+
"jobFunction": "Scare assistant",
53+
"location": "scare floor",
54+
"coworker": "James P. Sullivan",
55+
"device": "iPad"
56+
}
57+
```
58+
## Targeting Key
59+
:::info
60+
**Targeting Key is a mandatory field in GO Feature Flag.**
61+
:::
62+
63+
A **targeting key** is a unique identifier that represents the context of the evaluation _(email, session id, a fingerprint or anything that is consistent)_,
64+
ensuring that they are consistently exposed to the same variation of a feature, even across multiple visits or sessions.
65+
66+
The targeting key is used to ensure that a user consistently receives the same variation of a feature flag over time.
67+
For instance, **GO Feature Flag** ensures that in cases where a feature is being rolled out to a percentage of users, based on the targeting key, they will see the same variation each time they encounter the feature flag.
68+
69+
## Reserved properties in the evaluation context
70+
:::danger
71+
If you put a key named `gofeatureflag` in your evaluation context, it may break internal features of GO Feature Flag.
72+
This property name is reserved for internal use.
73+
:::
74+
75+
When you create an evaluation context some fields are reserved for GO Feature Flag.
76+
Those fields are used by GO Feature Flag directly, you can use them as will in your targeting queries, but you should be aware that they are used internally for GO Feature Flag.
77+
78+
| Field | Description |
79+
|----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
80+
| `gofeatureflag.currentDateTime` | If this property is set, we will use this date as base for all the rollout strategies which implies dates _(experimentation, progressive and scheduled)_.<br/>**Format:** Date following the RF3339 format. |
81+
| `gofeatureflag.flagList` | If this property is set, in the bulk evaluation mode (for the client SDK) we will only evaluate the flags in this list.<br/>If empty or not set the default behavior is too evaluate all the flags.<br/>**Format:** []string |
82+
| `gofeatureflag.exporterMetadata` | If this property is set, we will add all the fields in the feature event send to the provider.<br/>**Format:** map[string]string\|number\|bool |

‎website/versioned_docs/version-v1.52.0/concepts/exporter.mdx‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
sidebar_position: 60
3+
description: Exporter are used to export your evaluation data to a remote source.
4+
---
5+
import {integrations} from "@site/data/integrations";
6+
7+
# 🚚 Exporter
8+
9+
## Overview
10+
In GO Feature Flag, an **exporter** is a component that sends flag evaluation results to external systems.
11+
This allows you to track how your feature flags are being used, gather data for analysis, and monitor their impact on your application.
12+
13+
## About exporters
14+
We have built the concept of **exporter** to allow you to export your evaluation data to a remote source, this can be useful in several occasion:
15+
- **Analytics and Monitoring**: Exporters enable you to collect data on feature flag usage, such as how often a flag is evaluated, the percentage of users receiving a specific variation, and the context in which flags are evaluated. This data can be used for A/B testing, performance monitoring, and understanding user behavior.
16+
- **Debugging and Troubleshooting**: By logging flag evaluations, exporters can help you identify issues related to feature flags, such as unexpected behavior or incorrect flag configurations.
17+
- **Integration with External Systems**: Exporters facilitate integration with various monitoring, logging, and analytics platforms, allowing you to centralize your data and gain comprehensive insights.
18+
19+
## Synchronous vs Asynchronous exporters
20+
Considering the volume of information to process and the potential impact on your application's performance, exporters can be synchronous or asynchronous depending on where the data is send.
21+
22+
<ul>
23+
<li>
24+
<span><strong>Synchronous exporters</strong>: These exporters send data immediately <i>(or near immediately)</i> after a flag evaluation. This is used for queue system or almost 0 latency write systems.</span>
25+
<div className="flex gap-x-1 mt-1">
26+
{
27+
integrations.exporters.filter(exporter => exporter.type === 'sync').map((exporter) => (
28+
<span className="inline-flex items-center rounded-md bg-gray-50 px-2 py-1 text-xs font-medium text-gray-600 ring-1 ring-inset ring-gray-500/10">{exporter.name}</span>
29+
))}
30+
</div>
31+
</li>
32+
<li className={"pt-5"}>
33+
<span><strong>Asynchronous exporters</strong>: These exporters send data in batch, this is useful when you have a lot of data to send and you don't want to impact the performance of your application. This is used for all exporters writing files <i>(locally or remotely)</i>.</span>
34+
<br /><span>Those exporters are using a buffer to store the data in memory before sending it. If for any reason the exporter can't send the data, the buffer will be used to store the data until the exporter can send it.</span>
35+
<div className="flex gap-x-1 mt-1">
36+
{
37+
integrations.exporters.filter(exporter => exporter.type === 'async').map((exporter) => (
38+
<span className="inline-flex items-center rounded-md bg-gray-50 px-2 py-1 text-xs font-medium text-gray-600 ring-1 ring-inset ring-gray-500/10">{exporter.name}</span>
39+
))}
40+
</div>
41+
</li>
42+
</ul>
43+
44+
## Supported exporters
45+
46+
<ul>
47+
{integrations.exporters.map((exporter) => (
48+
<li>{exporter.name}</li>
49+
))}
50+
</ul>
51+
52+
[Check how to configure the exporters](../integrations/export-evaluation-data)
53+
54+
55+
## Feature vs Tracking exporters
56+
57+
Exporters can be configured to receive one of two event types:
58+
59+
- **Feature exporters** (default): They receive **feature events**—one event per flag evaluation. Each event describes which flag was evaluated, which variation was returned, and for which user/context. Use this to understand flag usage, power analytics, and feed A/B or experimentation tools. See [flag usage tracking](../tracking/flag-usage-tracking) for details.
60+
- **Tracking exporters**: They receive **tracking events**—custom actions or outcomes you record via the [OpenFeature Tracking API](https://openfeature.dev/specification/sections/tracking/) (e.g. "user completed checkout", "clicked CTA"). Use this to measure the impact of flags (e.g. conversion per variation) and run experiments. See [Tracking API](../tracking/tracking-api) for details.
61+
62+
You choose the event type per exporter with the `eventType` option (`"feature"` or `"tracking"`).
63+
The default is `"feature"` when omitted. You can send both kinds of events to the same backend by defining two exporter entries—one for feature events, one for tracking events—if your pipeline accepts both.
64+
65+
For more information, see the [tracking section](../tracking/flag-usage-tracking) (flag usage and [Tracking API](../tracking/tracking-api)).
66+
67+
## How Exporters Work
68+
69+
When a feature flag is evaluated using any of the SDK, GO Feature Flag notifies the configured exporters with the evaluation result. This result typically includes:
70+
71+
- The name of the flag.
72+
- The variation returned.
73+
- The targetingKey.
74+
- The source of the evaluation (e.g., SERVER or PROVIDER).
75+
- Exporter metadata (e.g., source provider, etc ...), see [blog post about exporter metadata](/blog/2025/01/21/exporter-metadata).
76+
77+
The exporter then formats and sends this data to the configured destination.

0 commit comments

Comments
 (0)