public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add feature toggles to docs (#59483)

Browse Source
This commit is contained in:
Mitch Seaman
2022-11-30 16:50:20 -05:00
committed by GitHub
parent 5dc7b01f9d
commit 240c77bb42
4 changed files with 273 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
pkg/services/featuremgmt/registry.go
+22 -16
View File
@@ -16,7 +16,7 @@ var (
},
{
Name: "promQueryBuilder",
Description: "Show prometheus query builder",
Description: "Show Prometheus query builder",
State: FeatureStateStable,
Expression: "true", // on by default
FrontendOnly: true,
@@ -33,7 +33,7 @@ var (
},
{
Name: "database_metrics",
Description: "Add prometheus metrics for database tables",
Description: "Add Prometheus metrics for database tables",
State: FeatureStateStable,
},
{
@@ -49,12 +49,12 @@ var (
},
{
Name: "live-config",
Description: "Save grafana live configuration in SQL tables",
Description: "Save Grafana Live configuration in SQL tables",
State: FeatureStateAlpha,
},
{
Name: "live-pipeline",
Description: "enable a generic live processing pipeline",
Description: "Enable a generic live processing pipeline",
State: FeatureStateAlpha,
},
{
@@ -65,14 +65,14 @@ var (
},
{
Name: "queryOverLive",
Description: "Use grafana live websocket to execute backend queries",
Description: "Use Grafana Live WebSocket to execute backend queries",
State: FeatureStateAlpha,
FrontendOnly: true,
},
{
Name: "panelTitleSearch",
Description: "Search for dashboards using panel title",
State: FeatureStateAlpha,
State: FeatureStateBeta,
},
{
Name: "tempoApmTable",
@@ -99,23 +99,23 @@ var (
},
{
Name: "publicDashboards",
Description: "enables public access to dashboards",
Description: "Enables public access to dashboards",
State: FeatureStateAlpha,
},
{
Name: "lokiLive",
Description: "support websocket streaming for loki (early prototype)",
Description: "Support WebSocket streaming for loki (early prototype)",
State: FeatureStateAlpha,
},
{
Name: "lokiDataframeApi",
Description: "use experimental loki api for websocket streaming (early prototype)",
Description: "Use experimental loki api for WebSocket streaming (early prototype)",
State: FeatureStateAlpha,
},
{
Name: "lokiMonacoEditor",
Description: "Access to Monaco query editor for Loki",
State: FeatureStateAlpha,
State: FeatureStateStable,
Expression: "true",
FrontendOnly: true,
},
@@ -126,7 +126,7 @@ var (
},
{
Name: "featureHighlights",
Description: "Highlight Enterprise features",
Description: "Highlight Grafana Enterprise features",
State: FeatureStateStable,
},
{
@@ -222,7 +222,7 @@ var (
{
Name: "validateDashboardsOnSave",
Description: "Validate dashboard JSON POSTed to api/dashboards/db",
State: FeatureStateAlpha,
State: FeatureStateBeta,
RequiresRestart: true,
},
{
@@ -257,10 +257,11 @@ var (
{
Name: "logRequestsInstrumentedAsUnknown",
Description: "Logs the path for requests that are instrumented as unknown",
State: FeatureStateAlpha,
},
{
Name: "dataConnectionsConsole",
Description: "Enables a new top-level page called Connections. This page is an experiment for better grouping of installing / configuring data sources and other plugins.",
Description: "Enables a new top-level page called Connections. This page is an experiment that provides a better experience when you install and configure data sources and other plugins.",
State: FeatureStateAlpha,
},
{
@@ -281,7 +282,7 @@ var (
},
{
Name: "objectStore",
Description: "SQL based object store",
Description: "SQL-based object store",
State: FeatureStateAlpha,
RequiresDevMode: true,
},
@@ -315,10 +316,12 @@ var (
{
Name: "increaseInMemDatabaseQueryCache",
Description: "Enable more in memory caching for database queries",
State: FeatureStateAlpha,
},
{
Name: "interFont",
Description: "Switch to inter font",
State: FeatureStateBeta,
},
{
Name: "newPanelChromeUI",
@@ -334,16 +337,18 @@ var (
},
{
Name: "showDashboardValidationWarnings",
Description: "Show warnings when Dashboards do not validate against the schema",
Description: "Show warnings when dashboards do not validate against the schema",
State: FeatureStateAlpha,
},
{
Name: "mysqlAnsiQuotes",
Description: "Use double quote to escape keyword in Mysql query",
Description: "Use double quotes to escape keyword in a MySQL query",
State: FeatureStateAlpha,
},
{
Name: "datasourceLogger",
Description: "Logs all datasource requests",
State: FeatureStateBeta,
},
{
Name: "accessControlOnCall",
@@ -370,6 +375,7 @@ var (
{
Name: "secureSocksDatasourceProxy",
Description: "Enable secure socks tunneling for supported core datasources",
State: FeatureStateAlpha,
},
{
Name: "authnService",
pkg/services/featuremgmt/toggles_gen.go
+13 -13
View File
@@ -12,7 +12,7 @@ const (
FlagAlertingBigTransactions = "alertingBigTransactions"
// FlagPromQueryBuilder
// Show prometheus query builder
// Show Prometheus query builder
FlagPromQueryBuilder = "promQueryBuilder"
// FlagTrimDefaults
@@ -24,7 +24,7 @@ const (
FlagDisableEnvelopeEncryption = "disableEnvelopeEncryption"
// FlagDatabaseMetrics
// Add prometheus metrics for database tables
// Add Prometheus metrics for database tables
FlagDatabaseMetrics = "database_metrics"
// FlagDashboardPreviews
@@ -36,11 +36,11 @@ const (
FlagDashboardPreviewsAdmin = "dashboardPreviewsAdmin"
// FlagLiveConfig
// Save grafana live configuration in SQL tables
// Save Grafana Live configuration in SQL tables
FlagLiveConfig = "live-config"
// FlagLivePipeline
// enable a generic live processing pipeline
// Enable a generic live processing pipeline
FlagLivePipeline = "live-pipeline"
// FlagLiveServiceWebWorker
@@ -48,7 +48,7 @@ const (
FlagLiveServiceWebWorker = "live-service-web-worker"
// FlagQueryOverLive
// Use grafana live websocket to execute backend queries
// Use Grafana Live WebSocket to execute backend queries
FlagQueryOverLive = "queryOverLive"
// FlagPanelTitleSearch
@@ -72,15 +72,15 @@ const (
FlagShowFeatureFlagsInUI = "showFeatureFlagsInUI"
// FlagPublicDashboards
// enables public access to dashboards
// Enables public access to dashboards
FlagPublicDashboards = "publicDashboards"
// FlagLokiLive
// support websocket streaming for loki (early prototype)
// Support WebSocket streaming for loki (early prototype)
FlagLokiLive = "lokiLive"
// FlagLokiDataframeApi
// use experimental loki api for websocket streaming (early prototype)
// Use experimental loki api for WebSocket streaming (early prototype)
FlagLokiDataframeApi = "lokiDataframeApi"
// FlagLokiMonacoEditor
@@ -92,7 +92,7 @@ const (
FlagSwaggerUi = "swaggerUi"
// FlagFeatureHighlights
// Highlight Enterprise features
// Highlight Grafana Enterprise features
FlagFeatureHighlights = "featureHighlights"
// FlagDashboardComments
@@ -188,7 +188,7 @@ const (
FlagLogRequestsInstrumentedAsUnknown = "logRequestsInstrumentedAsUnknown"
// FlagDataConnectionsConsole
// Enables a new top-level page called Connections. This page is an experiment for better grouping of installing / configuring data sources and other plugins.
// Enables a new top-level page called Connections. This page is an experiment that provides a better experience when you install and configure data sources and other plugins.
FlagDataConnectionsConsole = "dataConnectionsConsole"
// FlagInternationalization
@@ -204,7 +204,7 @@ const (
FlagGrpcServer = "grpcServer"
// FlagObjectStore
// SQL based object store
// SQL-based object store
FlagObjectStore = "objectStore"
// FlagTraceqlEditor
@@ -244,11 +244,11 @@ const (
FlagQueryLibrary = "queryLibrary"
// FlagShowDashboardValidationWarnings
// Show warnings when Dashboards do not validate against the schema
// Show warnings when dashboards do not validate against the schema
FlagShowDashboardValidationWarnings = "showDashboardValidationWarnings"
// FlagMysqlAnsiQuotes
// Use double quote to escape keyword in Mysql query
// Use double quotes to escape keyword in a MySQL query
FlagMysqlAnsiQuotes = "mysqlAnsiQuotes"
// FlagDatasourceLogger
pkg/services/featuremgmt/toggles_gen_test.go
+127
View File
@@ -11,6 +11,7 @@ import (
"unicode"
"github.com/google/go-cmp/cmp"
"github.com/olekukonko/tablewriter"
"github.com/stretchr/testify/require"
"github.com/grafana/grafana/pkg/services/featuremgmt/strcase"
@@ -26,6 +27,20 @@ func TestFeatureToggleFiles(t *testing.T) {
"live-service-web-worker": true,
}
t.Run("check registry constraints", func(t *testing.T) {
for _, flag := range standardFeatureFlags {
if flag.Expression == "true" && flag.State != FeatureStateStable {
t.Errorf("only stable features can be enabled by default. See: %s", flag.Name)
}
if flag.RequiresDevMode && flag.State != FeatureStateAlpha {
t.Errorf("only alpha features can require dev mode. See: %s", flag.Name)
}
if flag.State == FeatureStateUnknown {
t.Errorf("standard toggles should not have an unknown state. See: %s", flag.Name)
}
}
})
t.Run("verify files", func(t *testing.T) {
// Typescript files
verifyAndGenerateFile(t,
@@ -38,6 +53,12 @@ func TestFeatureToggleFiles(t *testing.T) {
"toggles_gen.go",
generateRegistry(t),
)
// Docs files
verifyAndGenerateFile(t,
"../../../docs/sources/setup-grafana/configure-grafana/feature-toggles/index.md",
generateDocsMD(),
)
})
t.Run("check feature naming convention", func(t *testing.T) {
@@ -171,3 +192,109 @@ const (`)
return buff.String()
}
func generateDocsMD() string {
hasDeprecatedFlags := false
buf := `---
aliases:
- /docs/grafana/latest/setup-grafana/configure-grafana/feature-toggles/
description: Learn about toggles for experimental and beta features, which you can enable or disable.
title: Configure feature toggles
weight: 150
---
<!-- DO NOT EDIT THIS PAGE, it is machine generated by running the test in -->
<!-- https://github.com/grafana/grafana/blob/main/pkg/services/featuremgmt/toggles_gen_test.go#L19 -->
# Configure feature toggles
You use feature toggles, also known as feature flags, to turn experimental or beta features on and off in Grafana. Although we do not recommend using these features in production, you can turn on feature toggles to try out new functionality in development or test environments.
This page contains a list of available feature toggles. To learn how to turn on feature toggles, refer to our [Configure Grafana documentation]({{< relref "../_index.md/#feature_toggles" >}}). Feature toggles are also available to Grafana Cloud Advanced customers. If you use Grafana Cloud Advanced, you can open a support ticket and specify the feature toggles and stack for which you want them enabled.
## Stable feature toggles
Some stable features are enabled by default. You can disable a stable feature by setting the feature flag to "false" in the configuration.
` + writeToggleDocsTable(func(flag FeatureFlag) bool {
return flag.State == FeatureStateStable
}, true)
buf += `
## Beta feature toggles
` + writeToggleDocsTable(func(flag FeatureFlag) bool {
return flag.State == FeatureStateBeta
}, false)
if hasDeprecatedFlags {
buf += `
## Deprecated feature toggles
When stable or beta features are slated for removal, they will be marked as Deprecated first.
` + writeToggleDocsTable(func(flag FeatureFlag) bool {
return flag.State == FeatureStateDeprecated
}, false)
}
buf += `
## Alpha feature toggles
These features are early in their development lifecycle and so are not yet supported in Grafana Cloud.
Alpha features might be changed or removed without prior notice.
` + writeToggleDocsTable(func(flag FeatureFlag) bool {
return flag.State == FeatureStateAlpha && !flag.RequiresDevMode
}, false)
buf += `
## Development feature toggles
The following toggles require explicitly setting Grafana's [app mode]({{< relref "../_index.md/#app_mode" >}}) to 'development' before you can enable this feature toggle. These features tend to be experimental.
` + writeToggleDocsTable(func(flag FeatureFlag) bool {
return flag.RequiresDevMode
}, false)
return buf
}
func writeToggleDocsTable(include func(FeatureFlag) bool, showEnableByDefault bool) string {
data := [][]string{}
for _, flag := range standardFeatureFlags {
if include(flag) {
row := []string{"`" + flag.Name + "`", flag.Description}
if showEnableByDefault {
on := ""
if flag.Expression == "true" {
on = "Yes"
}
row = append(row, on)
}
data = append(data, row)
}
}
header := []string{"Feature toggle name", "Description"}
if showEnableByDefault {
header = append(header, "Enabled by default")
}
sb := &strings.Builder{}
table := tablewriter.NewWriter(sb)
table.SetHeader(header)
table.SetBorders(tablewriter.Border{Left: true, Top: false, Right: true, Bottom: false})
table.SetCenterSeparator("|")
table.SetAutoFormatHeaders(false)
table.SetHeaderAlignment(tablewriter.ALIGN_LEFT)
table.SetAutoWrapText(false)
table.SetAlignment(tablewriter.ALIGN_LEFT)
table.AppendBulk(data) // Add Bulk Data
table.Render()
// Markdown table formatting (from prittier)
v := strings.ReplaceAll(sb.String(), "|--", "| -")
return strings.ReplaceAll(v, "--|", "- |")
}