mirror of
https://github.com/Unleash/unleash.git
synced 2024-12-22 19:07:54 +01:00
35fbd8f271
This change updates the playground reference docs with some new images and an explanation of how the results work now. I have not removed any of the old images because I think they still illustrate well how the playground works. And because they're not direct screenshots anyway, that sounds like a fair trade-off to me.
118 lines
8.9 KiB
Plaintext
118 lines
8.9 KiB
Plaintext
---
|
|
title: The Playground
|
|
---
|
|
import Figure from '@site/src/components/Figure/Figure.tsx'
|
|
|
|
:::info Availability
|
|
|
|
The Unleash playground is available in all Unleash versions from Unleash 4.14 onwards. Unleash 5.3 introduced a more advanced playground that allows you to query multiple environments and multiple values for a single context value at the same time.
|
|
|
|
:::
|
|
|
|
|
|
|
|
The unleash playground is a part of the Unleash Admin UI and an accompanying API. The playground lets you see which of your instance's feature toggles would be enabled for a given Unleash context. It has multiple uses, such as:
|
|
|
|
- Understanding how Unleash evaluates strategies, constraints, and segments.
|
|
- Debugging Unleash contexts and toggles behaving differently from what you expect.
|
|
- Tailoring a set of strategies for given contexts.
|
|
|
|
Each feature toggle will contain info on whether it was enabled or not and which variant it was assigned. Later versions of the playground also contain [detailed evaluation results](#detailed-evaluation-results) to help you understand exactly why the feature was enabled or disabled.
|
|
|
|
## Configuring the query
|
|
|
|
This section describes what information the playground needs to evaluate your Unleash context against your existing features.
|
|
|
|
### Environments and projects
|
|
|
|
The playground needs to know which environments and which projects to use when evaluating features. The playground UI will default to using the first environment in your list of instance environments and all projects.
|
|
|
|
You can select as many of your environments as you want. All environments must be environments that exist in your Unleash instance. Prior to Unleash 5.3, features could only be evaluated against a single environment at a time.
|
|
|
|
The playground will only evaluate features belonging to the projects you specify. The projects parameter can either be a list of projects **or** _all_ projects.
|
|
|
|
### The Unleash context
|
|
|
|
The [Unleash context](../reference/unleash-context.md) represents a client SDK's configuration and used for evaluating your features. You can construct your own context or use a JSON version of a context from a client.
|
|
|
|
#### Multiple values for a single context field
|
|
|
|
:::info Availability
|
|
|
|
The ability to specifiy multiple values for a single context field was introduced in Unleash 5.3.
|
|
|
|
:::
|
|
|
|
You can specify multiple values for a single context field by separating the values with a comma. For instance: `"value1, value2"`.
|
|
|
|
When you specify multiple values for context field, each value will be used to populate one variant of the response.
|
|
|
|
#### Implicit context fields
|
|
|
|
You can add any fields you want to the context used for the evaluation, and you can also leave out any fields you want. However, there are some fields that will be set for you if don't provide them:
|
|
|
|
- **`appName`**: Unleash clients all require an `appName` to start up. If you do not provide an `appName`, the playground will assign a default value to this property instead.
|
|
- **`currentTime`**: The `currentTime` property of the [Unleash context](../reference/unleash-context.md) gets auto-populated with the current time. You can override this manually by providing a value of your own.
|
|
|
|
## The response
|
|
|
|
|
|
|
|
The playground's response contains a list of all the feature toggles that have been evaluated based on your configured [environments, projects](#environments-and-projects) and [context](#the-unleash-context). The full response will contain results for all combinations of context fields and all environments that you selected.
|
|
|
|
In the UI, the playground displays the features in a table. Each row of the table corresponds to a single feature. The table has a separate column for each of the environments that you selected for your query.
|
|
|
|
<Figure caption='Each row contains a feature and columns for the selected environments. In this screenshot, the "development" and "production" environments have been selected.' img="/img/playground-results-row.png"/>
|
|
|
|
Because you can add multiple values for each context field, each feature-environment cell contains the number of combinations that evaluated to `true` and `false` for the feature in the given environment. This can be expanded into a more detailed overview over what combinations of context fields evaluated to `true` and `false` along with any [variants](../reference/feature-toggle-variants.md).
|
|
|
|
<Figure caption='A small table showing the detailed evaluation for a feature in the "development" environment. The provided context contained three values for the "userId" property, so the table contains three rows, showing all different combinations of the context.' img="/img/playground-results-development.png"/>
|
|
|
|
As with all of Unleash's client SDKs, the playground respects [stickiness](../reference/stickiness.md). The [stickiness algorithm](../reference/stickiness.md#calculation) guarantees that you'll always get the same variants and the same gradual rollout results if you provide the same context, as long as you provide the context field used for calculating stickiness.
|
|
|
|
### The diff view
|
|
|
|
You can compare how a feature evaluates in different environments. If you select more than one environment for your playground query, the table will have an additional "Diff" column in each row. Using the "preview diff" button, you can open a table that gives an overview over how the feature evaluated for each context combination in each environment.
|
|
|
|
<Figure caption='A table with three rows. Each row contains a context combination and results in the form of `true` and `false` each environment. In this case, it shows that when the "userId" context field is "2", then the feature is enabled in development, but not in production.' img="/img/playground-results-diff.png"/>
|
|
|
|
|
|
### Detailed evaluation results
|
|
|
|
:::info Availability
|
|
|
|
Detailed evaluation results were added to the playground in Unleash 4.15.
|
|
|
|
:::
|
|
|
|
|
|
|
|
Each feature in the response contains information about all of its evaluated strategies. Each of a feature's strategies lists all of the strategies constraints and segments and how it all evaluated (as best as the playground can, as mentioned in the [unknown strategies](#unknown-strategies) section).
|
|
|
|
In addition to the results of individual strategies, each strategy is also assigned an overall strategy evaluation result: one of `true`, `false`, and _unknown_. The rules for the overall result are:
|
|
|
|
- If _at least one_ strategy evaluates to `true`, then the overall result is `true`.
|
|
- If _all_ strategies evaluate to `false`, the overall result is `false`.
|
|
- If _one or more_ strategies evaluate to _unknown_ and _all other strategies evaluate to `false`_, then the overall result is `unknown`.
|
|
|
|
## Unknown strategies
|
|
|
|
Not all strategies can be correctly evaluated by the playground. Strategies that cannot be fully evaluated will be given an evaluation result status of 'unknown'.
|
|
|
|
There's currently two cases where the playground can't evaluate the strategy:
|
|
|
|
1. The [strategy is a custom strategy](#custom-strategies) and the playground doesn't have an implementation for the strategy.
|
|
2. The [strategy is the 'Application Hostname' strategy](#application-hostname).
|
|
|
|
Even if the playground doesn't recognize or otherwise can't evaluate a specific strategy, it _may_ still evaluate the overall strategy result to `false` (and be certain that it is the right result). If a strategy has [constraints](../reference/strategy-constraints.md) or [segments](segments.mdx) that are not satisfied, the playground knows that the strategy result wouldn't be `true`, regardless of the actual strategy implementation. As such, if a strategy can't be evaluated, it can be **either** _unknown_ or _`false`_.
|
|
|
|
### Custom Strategies
|
|
|
|
The playground does not have any implementations for [custom strategies](../reference/custom-activation-strategies.md) and adding custom strategy implementations to Unleash is not currently supported. Because of this, custom strategies will never be evaluated as `true`.
|
|
|
|
### The Application Hostname strategy {#application-hostname}
|
|
|
|
The [application hostname strategy](../reference/activation-strategies.md#hostnames) is a little different from the other built-in strategies: it depends on external state and _not_ on the Unleash context to evaluate. In short, the strategy checks its application environment to get the hostname, so the Unleash context has no effect on the result of this strategy.
|
|
|
|
Because the application hostname strategy depends on external state, the playground can't guarantee whether the strategy would be true or false in a client. Further, the result in the playground would most likely be different from what you'd see in a client. Because of this, the playground does not evaluate this strategy.
|