settings

package
v0.0.0-...-1b6ad0c Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 11, 2020 License: Apache-2.0 Imports: 14 Imported by: 4

Documentation

Overview

Package settings provides a central registry of runtime editable settings and accompanying helper functions for retrieving their current values.

Settings values are stored in the system.settings table (which is gossiped). A gossip-driven worker updates this package's cached value when the table changes (see the `RefreshSettings` worker in the `sql` package).

The package's cache is global -- while all the usual drawbacks of mutable global state obviously apply, it is needed to make the package's functionality available to a wide variety of callsites, that may or may not have a *Server or similar available to access settings.

To add a new setting, call one of the `Register` methods in `registry.go` and save the accessor created by the register function in the package where the setting is to be used. For example, to add an "enterprise" flag, adding into license_check.go:

var enterpriseEnabled = settings.RegisterBoolSetting( 

"enterprise.enabled", "some doc for the setting", false,

)

Then use with `if enterpriseEnabled.Get() ...`

Settings should always be defined with "safe" default values -- until a node receives values via gossip, or even after that, if it cannot read them for some reason, it will use the default values, so define defaults that "fail safe".

In cases where the "safe" default doesn't actually match the desired default, like respecting an opt-*out* setting, we can default to `false` (opted out) and then use a migration to write an explicit `true`: in practice you'd still expect to read `true` unless a preference is expressed, but in the rare cases where you read a default, you don't risk ignoring an expressed opt-out.

Ideally, when passing configuration into some structure or subsystem, e.g. a rate limit into a client or something, passing a `*FooSetting` rather than a `Foo` and waiting to call `.Get()` until the value is actually used ensures observing the latest value.

Settings may become irrelevant over time, especially when introduced to provide a workaround to a system limitation which is later corrected. When deleting a setting's registration from the codebase, add its name to the list of `retiredSettings` in settings/registry.go -- this ensures the name cannot be accidentally reused, and suppresses log spam about the existing value.

That list of retired settings can periodically (i.e. in major versions) be "flushed" by adding a migration that deletes all stored values for those keys at which point the key would be available for reuse in a later version. Is is only safe to run such a migration after the cluster upgrade process ensures no older nodes are still using the values for those old settings though, so such a migration needs to be version gated.

Existing/off-the-shelf systems generally will not be defined in terms of our settings, but if they can either be swapped at runtime or expose some `setFoo` method, that can be used in conjunction with a change callback registered via OnChange.

Index

Constants

View Source 
const MaxSettings = 256

MaxSettings is the maximum number of settings that the system supports. Exported for tests.

Variables

View Source 
var ReadableTypes = map[string]string{
	"s": "string",
	"i": "integer",
	"f": "float",
	"b": "boolean",
	"z": "byte size",
	"d": "duration",
	"e": "enumeration",
	"m": "custom validation",
}

ReadableTypes maps our short type identifiers to friendlier names.

View Source 
var TestOpaque interface{} = testOpaqueType{}

TestOpaque can be passed to Values.Init when we are testing the settings infrastructure.

Functions

func EncodeBool 

func EncodeBool(b bool) string

EncodeBool encodes a bool in the format parseRaw expects.

func EncodeDuration 

func EncodeDuration(d time.Duration) string

EncodeDuration encodes a duration in the format parseRaw expects.

func EncodeFloat 

func EncodeFloat(f float64) string

EncodeFloat encodes a bool in the format parseRaw expects.

func EncodeInt 

func EncodeInt(i int64) string

EncodeInt encodes an int in the format parseRaw expects.

func Keys 

func Keys() (res []string)

Keys returns a sorted string array with all the known keys.

func NumRegisteredSettings 

func NumRegisteredSettings() int

NumRegisteredSettings returns the number of registered settings.

func RedactedValue 

func RedactedValue(name string, values *Values) string

RedactedValue returns a string representation of the value for settings types the are not considered sensitive (numbers, bools, etc) or <redacted> for those with values could store sensitive things (i.e. strings).

func RegisterStateMachineSetting 

func RegisterStateMachineSetting(key, desc string, setting *StateMachineSetting)

RegisterStateMachineSetting registers a StateMachineSetting. See the comment for StateMachineSetting for details.

func SetCanonicalValuesContainer 

func SetCanonicalValuesContainer(v *Values)

SetCanonicalValuesContainer sets the Values container that will be refreshed at runtime -- ideally we should have no other *Values containers floating around, as they will be stale / lies.

func TestingIsReportable 

func TestingIsReportable(s Setting) bool

TestingIsReportable is used in testing for reportability.

func TestingSaveRegistry 

func TestingSaveRegistry() func()

TestingSaveRegistry can be used in tests to save/restore the current contents of the registry.

Types

type BoolSetting 

type BoolSetting struct {
	// contains filtered or unexported fields
}

BoolSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "bool" is updated.

func RegisterBoolSetting 

func RegisterBoolSetting(key, desc string, defaultValue bool) *BoolSetting

RegisterBoolSetting defines a new setting with type bool.

func RegisterPublicBoolSetting 

func RegisterPublicBoolSetting(key, desc string, defaultValue bool) *BoolSetting

RegisterPublicBoolSetting defines a new setting with type bool and makes it public.

func (BoolSetting) Description 

func (i BoolSetting) Description() string

func (*BoolSetting) Encoded 

func (b *BoolSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*BoolSetting) EncodedDefault 

func (b *BoolSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*BoolSetting) ErrorHint 

func (i *BoolSetting) ErrorHint() (bool, string)

func (*BoolSetting) Get 

func (b *BoolSetting) Get(sv *Values) bool

Get retrieves the bool value in the setting.

func (*BoolSetting) Override 

func (b *BoolSetting) Override(sv *Values, v bool)

Override changes the setting without validation and also overrides the default value.

For testing usage only.

func (*BoolSetting) SetOnChange 

func (i *BoolSetting) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*BoolSetting) SetReportable 

func (i *BoolSetting) SetReportable(reportable bool)

SetReportable indicates whether a setting's value can show up in SHOW ALL CLUSTER SETTINGS and telemetry reports.

The setting can still be used with SET and SHOW if the exact setting name is known. Use SetReportable(false) for data that must be hidden from standard setting report, telemetry and troubleshooting screenshots, such as license data or keys.

All string settings are also non-reportable by default and must be opted in to reports manually with SetReportable(true).

func (*BoolSetting) SetRetired 

func (i *BoolSetting) SetRetired()

SetRetired marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*BoolSetting) SetVisibility 

func (i *BoolSetting) SetVisibility(v Visibility)

SetVisibility customizes the visibility of a setting.

func (*BoolSetting) String 

func (b *BoolSetting) String(sv *Values) string

func (*BoolSetting) Typ 

func (*BoolSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (BoolSetting) Visibility 

func (i BoolSetting) Visibility() Visibility

type ByteSizeSetting 

type ByteSizeSetting struct {
	IntSetting
}

ByteSizeSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "bytesize" is updated.

func RegisterByteSizeSetting 

func RegisterByteSizeSetting(key, desc string, defaultValue int64) *ByteSizeSetting

RegisterByteSizeSetting defines a new setting with type bytesize.

func RegisterPublicByteSizeSetting 

func RegisterPublicByteSizeSetting(key, desc string, defaultValue int64) *ByteSizeSetting

RegisterPublicByteSizeSetting defines a new setting with type bytesize and makes it public.

func RegisterPublicValidatedByteSizeSetting 

func RegisterPublicValidatedByteSizeSetting(
	key, desc string, defaultValue int64, validateFn func(int64) error,
) *ByteSizeSetting

RegisterPublicValidatedByteSizeSetting defines a new setting with type bytesize with a validation function and makes it public.

func RegisterValidatedByteSizeSetting 

func RegisterValidatedByteSizeSetting(
	key, desc string, defaultValue int64, validateFn func(int64) error,
) *ByteSizeSetting

RegisterValidatedByteSizeSetting defines a new setting with type bytesize with a validation function.

func (ByteSizeSetting) Description 

func (i ByteSizeSetting) Description() string

func (*ByteSizeSetting) ErrorHint 

func (i *ByteSizeSetting) ErrorHint() (bool, string)

func (*ByteSizeSetting) SetOnChange 

func (i *ByteSizeSetting) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*ByteSizeSetting) SetReportable 

func (i *ByteSizeSetting) SetReportable(reportable bool)

SetReportable indicates whether a setting's value can show up in SHOW ALL CLUSTER SETTINGS and telemetry reports.

The setting can still be used with SET and SHOW if the exact setting name is known. Use SetReportable(false) for data that must be hidden from standard setting report, telemetry and troubleshooting screenshots, such as license data or keys.

All string settings are also non-reportable by default and must be opted in to reports manually with SetReportable(true).

func (*ByteSizeSetting) SetRetired 

func (i *ByteSizeSetting) SetRetired()

SetRetired marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*ByteSizeSetting) SetVisibility 

func (i *ByteSizeSetting) SetVisibility(v Visibility)

SetVisibility customizes the visibility of a setting.

func (*ByteSizeSetting) String 

func (b *ByteSizeSetting) String(sv *Values) string

func (*ByteSizeSetting) Typ 

func (*ByteSizeSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (ByteSizeSetting) Visibility 

func (i ByteSizeSetting) Visibility() Visibility

type DurationSetting 

type DurationSetting struct {
	// contains filtered or unexported fields
}

DurationSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "duration" is updated.

func RegisterDurationSetting 

func RegisterDurationSetting(key, desc string, defaultValue time.Duration) *DurationSetting

RegisterDurationSetting defines a new setting with type duration.

func RegisterNonNegativeDurationSetting 

func RegisterNonNegativeDurationSetting(
	key, desc string, defaultValue time.Duration,
) *DurationSetting

RegisterNonNegativeDurationSetting defines a new setting with type duration.

func RegisterPublicDurationSetting 

func RegisterPublicDurationSetting(key, desc string, defaultValue time.Duration) *DurationSetting

RegisterPublicDurationSetting defines a new setting with type duration and makes it public.

func RegisterPublicNonNegativeDurationSetting 

func RegisterPublicNonNegativeDurationSetting(
	key, desc string, defaultValue time.Duration,
) *DurationSetting

RegisterPublicNonNegativeDurationSetting defines a new setting with type duration and makes it public.

func RegisterPublicNonNegativeDurationSettingWithMaximum 

func RegisterPublicNonNegativeDurationSettingWithMaximum(
	key, desc string, defaultValue time.Duration, maxValue time.Duration,
) *DurationSetting

RegisterPublicNonNegativeDurationSettingWithMaximum defines a new setting with type duration, makes it public, and sets a maximum value. The maximum value is an allowed value.

func RegisterValidatedDurationSetting 

func RegisterValidatedDurationSetting(
	key, desc string, defaultValue time.Duration, validateFn func(time.Duration) error,
) *DurationSetting

RegisterValidatedDurationSetting defines a new setting with type duration.

func (DurationSetting) Description 

func (i DurationSetting) Description() string

func (*DurationSetting) Encoded 

func (d *DurationSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*DurationSetting) EncodedDefault 

func (d *DurationSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*DurationSetting) ErrorHint 

func (i *DurationSetting) ErrorHint() (bool, string)

func (*DurationSetting) Get 

func (d *DurationSetting) Get(sv *Values) time.Duration

Get retrieves the duration value in the setting.

func (*DurationSetting) Override 

func (d *DurationSetting) Override(sv *Values, v time.Duration)

Override changes the setting without validation and also overrides the default value.

For testing usage only.

func (*DurationSetting) SetOnChange 

func (i *DurationSetting) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*DurationSetting) SetReportable 

func (i *DurationSetting) SetReportable(reportable bool)

SetReportable indicates whether a setting's value can show up in SHOW ALL CLUSTER SETTINGS and telemetry reports.

The setting can still be used with SET and SHOW if the exact setting name is known. Use SetReportable(false) for data that must be hidden from standard setting report, telemetry and troubleshooting screenshots, such as license data or keys.

All string settings are also non-reportable by default and must be opted in to reports manually with SetReportable(true).

func (*DurationSetting) SetRetired 

func (i *DurationSetting) SetRetired()

SetRetired marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*DurationSetting) SetVisibility 

func (i *DurationSetting) SetVisibility(v Visibility)

SetVisibility customizes the visibility of a setting.

func (*DurationSetting) String 

func (d *DurationSetting) String(sv *Values) string

func (*DurationSetting) Typ 

func (*DurationSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*DurationSetting) Validate 

func (d *DurationSetting) Validate(v time.Duration) error

Validate that a value conforms with the validation function.

func (DurationSetting) Visibility 

func (i DurationSetting) Visibility() Visibility

type DurationSettingWithExplicitUnit 

type DurationSettingWithExplicitUnit struct {
	DurationSetting
}

DurationSettingWithExplicitUnit is like DurationSetting except it requires an explicit unit when being set. (eg. 1s works, but 1 does not).

func RegisterPublicNonNegativeDurationSettingWithExplicitUnit 

func RegisterPublicNonNegativeDurationSettingWithExplicitUnit(
	key, desc string, defaultValue time.Duration,
) *DurationSettingWithExplicitUnit

RegisterPublicNonNegativeDurationSettingWithExplicitUnit defines a new public setting with type duration which requires an explicit unit when being set.

func (DurationSettingWithExplicitUnit) Description 

func (i DurationSettingWithExplicitUnit) Description() string

func (*DurationSettingWithExplicitUnit) ErrorHint 

func (d *DurationSettingWithExplicitUnit) ErrorHint() (bool, string)

ErrorHint returns a hint message to be displayed on error to the user.

func (*DurationSettingWithExplicitUnit) SetOnChange 

func (i *DurationSettingWithExplicitUnit) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*DurationSettingWithExplicitUnit) SetReportable 

func (i *DurationSettingWithExplicitUnit) SetReportable(reportable bool)

SetReportable indicates whether a setting's value can show up in SHOW ALL CLUSTER SETTINGS and telemetry reports.

The setting can still be used with SET and SHOW if the exact setting name is known. Use SetReportable(false) for data that must be hidden from standard setting report, telemetry and troubleshooting screenshots, such as license data or keys.

All string settings are also non-reportable by default and must be opted in to reports manually with SetReportable(true).

func (*DurationSettingWithExplicitUnit) SetRetired 

func (i *DurationSettingWithExplicitUnit) SetRetired()

SetRetired marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*DurationSettingWithExplicitUnit) SetVisibility 

func (i *DurationSettingWithExplicitUnit) SetVisibility(v Visibility)

SetVisibility customizes the visibility of a setting.

func (DurationSettingWithExplicitUnit) Visibility 

func (i DurationSettingWithExplicitUnit) Visibility() Visibility

type EnumSetting 

type EnumSetting struct {
	IntSetting
	// contains filtered or unexported fields
}

EnumSetting is a StringSetting that restricts the values to be one of the `enumValues`

func RegisterEnumSetting 

func RegisterEnumSetting(
	key, desc string, defaultValue string, enumValues map[int64]string,
) *EnumSetting

RegisterEnumSetting defines a new setting with type int.

func RegisterPublicEnumSetting 

func RegisterPublicEnumSetting(
	key, desc string, defaultValue string, enumValues map[int64]string,
) *EnumSetting

RegisterPublicEnumSetting defines a new setting with type int and makes it public.

func (EnumSetting) Description 

func (i EnumSetting) Description() string

func (*EnumSetting) ErrorHint 

func (i *EnumSetting) ErrorHint() (bool, string)

func (*EnumSetting) GetAvailableValuesAsHint 

func (e *EnumSetting) GetAvailableValuesAsHint() string

GetAvailableValuesAsHint returns the possible enum settings as a string that can be provided as an error hint to a user.

func (*EnumSetting) ParseEnum 

func (e *EnumSetting) ParseEnum(raw string) (int64, bool)

ParseEnum returns the enum value, and a boolean that indicates if it was parseable.

func (*EnumSetting) SetOnChange 

func (i *EnumSetting) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*EnumSetting) SetReportable 

func (i *EnumSetting) SetReportable(reportable bool)

SetReportable indicates whether a setting's value can show up in SHOW ALL CLUSTER SETTINGS and telemetry reports.

The setting can still be used with SET and SHOW if the exact setting name is known. Use SetReportable(false) for data that must be hidden from standard setting report, telemetry and troubleshooting screenshots, such as license data or keys.

All string settings are also non-reportable by default and must be opted in to reports manually with SetReportable(true).

func (*EnumSetting) SetRetired 

func (i *EnumSetting) SetRetired()

SetRetired marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*EnumSetting) SetVisibility 

func (i *EnumSetting) SetVisibility(v Visibility)

SetVisibility customizes the visibility of a setting.

func (*EnumSetting) String 

func (e *EnumSetting) String(sv *Values) string

String returns the enum's string value.

func (*EnumSetting) Typ 

func (e *EnumSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (EnumSetting) Visibility 

func (i EnumSetting) Visibility() Visibility

type FloatSetting 

type FloatSetting struct {
	// contains filtered or unexported fields
}

FloatSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "float" is updated.

func RegisterFloatSetting 

func RegisterFloatSetting(key, desc string, defaultValue float64) *FloatSetting

RegisterFloatSetting defines a new setting with type float.

func RegisterNonNegativeFloatSetting 

func RegisterNonNegativeFloatSetting(key, desc string, defaultValue float64) *FloatSetting

RegisterNonNegativeFloatSetting defines a new setting with type float.

func RegisterPositiveFloatSetting 

func RegisterPositiveFloatSetting(key, desc string, defaultValue float64) *FloatSetting

RegisterPositiveFloatSetting defines a new setting with type float.

func RegisterValidatedFloatSetting 

func RegisterValidatedFloatSetting(
	key, desc string, defaultValue float64, validateFn func(float64) error,
) *FloatSetting

RegisterValidatedFloatSetting defines a new setting with type float.

func (*FloatSetting) Default 

func (f *FloatSetting) Default() float64

Default returns the default value.

func (FloatSetting) Description 

func (i FloatSetting) Description() string

func (*FloatSetting) Encoded 

func (f *FloatSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*FloatSetting) EncodedDefault 

func (f *FloatSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*FloatSetting) ErrorHint 

func (i *FloatSetting) ErrorHint() (bool, string)

func (*FloatSetting) Get 

func (f *FloatSetting) Get(sv *Values) float64

Get retrieves the float value in the setting.

func (*FloatSetting) Override 

func (f *FloatSetting) Override(sv *Values, v float64)

Override changes the setting panicking if validation fails and also overrides the default value.

For testing usage only.

func (*FloatSetting) SetOnChange 

func (i *FloatSetting) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*FloatSetting) SetReportable 

func (i *FloatSetting) SetReportable(reportable bool)

SetReportable indicates whether a setting's value can show up in SHOW ALL CLUSTER SETTINGS and telemetry reports.

The setting can still be used with SET and SHOW if the exact setting name is known. Use SetReportable(false) for data that must be hidden from standard setting report, telemetry and troubleshooting screenshots, such as license data or keys.

All string settings are also non-reportable by default and must be opted in to reports manually with SetReportable(true).

func (*FloatSetting) SetRetired 

func (i *FloatSetting) SetRetired()

SetRetired marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*FloatSetting) SetVisibility 

func (i *FloatSetting) SetVisibility(v Visibility)

SetVisibility customizes the visibility of a setting.

func (*FloatSetting) String 

func (f *FloatSetting) String(sv *Values) string

func (*FloatSetting) Typ 

func (*FloatSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*FloatSetting) Validate 

func (f *FloatSetting) Validate(v float64) error

Validate that a value conforms with the validation function.

func (FloatSetting) Visibility 

func (i FloatSetting) Visibility() Visibility

type IntSetting 

type IntSetting struct {
	// contains filtered or unexported fields
}

IntSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "int" is updated.

func RegisterIntSetting 

func RegisterIntSetting(key, desc string, defaultValue int64) *IntSetting

RegisterIntSetting defines a new setting with type int.

func RegisterNonNegativeIntSetting 

func RegisterNonNegativeIntSetting(key, desc string, defaultValue int64) *IntSetting

RegisterNonNegativeIntSetting defines a new setting with type int.

func RegisterPositiveIntSetting 

func RegisterPositiveIntSetting(key, desc string, defaultValue int64) *IntSetting

RegisterPositiveIntSetting defines a new setting with type int.

func RegisterPublicIntSetting 

func RegisterPublicIntSetting(key, desc string, defaultValue int64) *IntSetting

RegisterPublicIntSetting defines a new setting with type int and makes it public.

func RegisterValidatedIntSetting 

func RegisterValidatedIntSetting(
	key, desc string, defaultValue int64, validateFn func(int64) error,
) *IntSetting

RegisterValidatedIntSetting defines a new setting with type int with a validation function.

func (*IntSetting) Default 

func (i *IntSetting) Default() int64

Default returns the default value.

func (IntSetting) Description 

func (i IntSetting) Description() string

func (*IntSetting) Encoded 

func (i *IntSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*IntSetting) EncodedDefault 

func (i *IntSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*IntSetting) ErrorHint 

func (i *IntSetting) ErrorHint() (bool, string)

func (*IntSetting) Get 

func (i *IntSetting) Get(sv *Values) int64

Get retrieves the int value in the setting.

func (*IntSetting) Override 

func (i *IntSetting) Override(sv *Values, v int64)

Override changes the setting without validation and also overrides the default value.

For testing usage only.

func (*IntSetting) SetOnChange 

func (i *IntSetting) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*IntSetting) SetReportable 

func (i *IntSetting) SetReportable(reportable bool)

SetReportable indicates whether a setting's value can show up in SHOW ALL CLUSTER SETTINGS and telemetry reports.

The setting can still be used with SET and SHOW if the exact setting name is known. Use SetReportable(false) for data that must be hidden from standard setting report, telemetry and troubleshooting screenshots, such as license data or keys.

All string settings are also non-reportable by default and must be opted in to reports manually with SetReportable(true).

func (*IntSetting) SetRetired 

func (i *IntSetting) SetRetired()

SetRetired marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*IntSetting) SetVisibility 

func (i *IntSetting) SetVisibility(v Visibility)

SetVisibility customizes the visibility of a setting.

func (*IntSetting) String 

func (i *IntSetting) String(sv *Values) string

func (*IntSetting) Typ 

func (*IntSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*IntSetting) Validate 

func (i *IntSetting) Validate(v int64) error

Validate that a value conforms with the validation function.

func (IntSetting) Visibility 

func (i IntSetting) Visibility() Visibility

type LookupPurpose 

type LookupPurpose int

LookupPurpose indicates what is being done with the setting. 

const (
	// LookupForReporting indicates that a setting is being retrieved
	// for reporting and sensitive values should be scrubbed.
	LookupForReporting LookupPurpose = iota
	// LookupForLocalAccess indicates that a setting is being
	// retrieved for local processing within the cluster and
	// all values should be accessible
	LookupForLocalAccess
)

type MaskedSetting 

type MaskedSetting struct {
	// contains filtered or unexported fields
}

MaskedSetting is a pseudo-variable constructed on-the-fly by Lookup when the actual setting is non-reportable.

func (*MaskedSetting) Description 

func (s *MaskedSetting) Description() string

Description returns the description string for the underlying setting.

func (*MaskedSetting) String 

func (s *MaskedSetting) String(sv *Values) string

String hides the underlying value.

func (*MaskedSetting) Typ 

func (s *MaskedSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*MaskedSetting) UnderlyingSetting 

func (s *MaskedSetting) UnderlyingSetting() WritableSetting

UnderlyingSetting retrieves the actual setting object.

func (*MaskedSetting) Visibility 

func (s *MaskedSetting) Visibility() Visibility

Visibility returns the visibility setting for the underlying setting.

type NoopUpdater 

type NoopUpdater struct{}

A NoopUpdater ignores all updates.

func (NoopUpdater) ResetRemaining 

func (u NoopUpdater) ResetRemaining()

ResetRemaining implements Updater. It is a no-op.

func (NoopUpdater) Set 

func (u NoopUpdater) Set(_, _, _ string) error

Set implements Updater. It is a no-op.

type Setting 

type Setting interface {
	// Typ returns the short (1 char) string denoting the type of setting.
	Typ() string
	String(sv *Values) string
	Description() string
	Visibility() Visibility
}

Setting is a descriptor for each setting; once it is initialized, it is immutable. The values for the settings are stored separately, in Values. This way we can have a global set of registered settings, each with potentially multiple instances.

func Lookup 

func Lookup(name string, purpose LookupPurpose) (Setting, bool)

Lookup returns a Setting by name along with its description. For non-reportable setting, it instantiates a MaskedSetting to masquerade for the underlying setting.

type StateMachineSetting 

type StateMachineSetting struct {
	// contains filtered or unexported fields
}

A StateMachineSetting is a setting that keeps a state machine driven by user input.

For (a nonsensical) example, a StateMachineSetting can be used to maintain an encoded protobuf containing an integer that the user can only increment by 3 if the int is odd and by two if it is even. More generally, the setting starts from an initial state, and can take the current state into account when determining user input. Initially this is motivated for use in cluster version upgrades.

The state machine as well as its encoding are represented by the StateMachineSettingImpl backing this StateMachineSetting; it is in charge to converting to/from strings and performing validations.

func MakeStateMachineSetting 

func MakeStateMachineSetting(impl StateMachineSettingImpl) StateMachineSetting

MakeStateMachineSetting creates a StateMachineSetting.

func RegisterStateMachineSettingImpl 

func RegisterStateMachineSettingImpl(
	key, desc string, impl StateMachineSettingImpl,
) *StateMachineSetting

RegisterStateMachineSettingImpl is like RegisterStateMachineSetting, but it takes a StateMachineSettingImpl.

func (*StateMachineSetting) Decode 

func (s *StateMachineSetting) Decode(val []byte) (interface{}, error)

Decode takes in an encoded value and returns it as the native type of the setting in question. For the Version setting, this is a ClusterVersion proto.

func (StateMachineSetting) Description 

func (i StateMachineSetting) Description() string

func (*StateMachineSetting) Encoded 

func (s *StateMachineSetting) Encoded(sv *Values) string

Encoded is part of the Setting interface.

func (*StateMachineSetting) EncodedDefault 

func (s *StateMachineSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*StateMachineSetting) ErrorHint 

func (i *StateMachineSetting) ErrorHint() (bool, string)

func (*StateMachineSetting) Get 

func (s *StateMachineSetting) Get(sv *Values) string

Get retrieves the (encoded) value in the setting. Get panics if set( ) has not been previously called.

func (*StateMachineSetting) GetInternal 

func (s *StateMachineSetting) GetInternal(sv *Values) interface{}

GetInternal returns the setting's current value.

func (*StateMachineSetting) SetInternal 

func (s *StateMachineSetting) SetInternal(sv *Values, newVal interface{})

SetInternal updates the setting's value in the sv container.

func (*StateMachineSetting) SetOnChange 

func (i *StateMachineSetting) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*StateMachineSetting) SetReportable 

func (i *StateMachineSetting) SetReportable(reportable bool)

SetReportable indicates whether a setting's value can show up in SHOW ALL CLUSTER SETTINGS and telemetry reports.

The setting can still be used with SET and SHOW if the exact setting name is known. Use SetReportable(false) for data that must be hidden from standard setting report, telemetry and troubleshooting screenshots, such as license data or keys.

All string settings are also non-reportable by default and must be opted in to reports manually with SetReportable(true).

func (*StateMachineSetting) SetRetired 

func (i *StateMachineSetting) SetRetired()

SetRetired marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*StateMachineSetting) SetVisibility 

func (i *StateMachineSetting) SetVisibility(v Visibility)

SetVisibility customizes the visibility of a setting.

func (*StateMachineSetting) SettingsListDefault 

func (s *StateMachineSetting) SettingsListDefault() string

SettingsListDefault returns the value that should be presented by `./cockroach gen settings-list`

func (*StateMachineSetting) String 

func (s *StateMachineSetting) String(sv *Values) string

func (*StateMachineSetting) Typ 

func (*StateMachineSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*StateMachineSetting) Validate 

func (s *StateMachineSetting) Validate(
	ctx context.Context, sv *Values, old []byte, update string,
) ([]byte, error)

Validate that the state machine accepts the user input. Returns new encoded state.

func (StateMachineSetting) Visibility 

func (i StateMachineSetting) Visibility() Visibility

type StateMachineSettingImpl 

type StateMachineSettingImpl interface {
	// Decode takes in an encoded value and returns it as the native type of the
	// setting in question. For the Version setting, this is a ClusterVersion
	// proto.
	Decode(val []byte) (interface{}, error)

	// DecodeToString takes in an encoded value and returns its string
	// representation.
	DecodeToString(val []byte) (string, error)

	// ValidateLogical checks whether an update is permitted. It takes in the old
	// (encoded) value and the proposed new value (as a string to be parsed).
	// This is called by SET CLUSTER SETTING.
	ValidateLogical(ctx context.Context, sv *Values, old []byte, newV string) ([]byte, error)

	// ValidateGossipUpdate performs fewer validations than ValidateLogical.
	// For the cluster version setting, it only checks that the current binary
	// supports the proposed version. This is called when the version is being
	// communicated to us by a different node.
	ValidateGossipUpdate(ctx context.Context, sv *Values, val []byte) error

	// SettingsListDefault returns the value that should be presented by
	// `./cockroach gen settings-list`
	SettingsListDefault() string

	// BeforeChange is called before an updated value for this setting is about to
	// be set on the values container.
	BeforeChange(ctx context.Context, encodedVal []byte, sv *Values)
}

StateMachineSettingImpl provides the setting-specific parts of a StateMachineSetting. The StateMachineSetting is in charge of interacting with the Values (loading and saving state) and StateMachineSettingImpl is in charge to converting to/from strings and performing validations.

type StringSetting 

type StringSetting struct {
	// contains filtered or unexported fields
}

StringSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "string" is updated.

func RegisterPublicStringSetting 

func RegisterPublicStringSetting(key, desc string, defaultValue string) *StringSetting

RegisterPublicStringSetting defines a new setting with type string and makes it public.

func RegisterStringSetting 

func RegisterStringSetting(key, desc string, defaultValue string) *StringSetting

RegisterStringSetting defines a new setting with type string.

func RegisterValidatedStringSetting 

func RegisterValidatedStringSetting(
	key, desc string, defaultValue string, validateFn func(*Values, string) error,
) *StringSetting

RegisterValidatedStringSetting defines a new setting with type string with a validation function.

func (StringSetting) Description 

func (i StringSetting) Description() string

func (*StringSetting) Encoded 

func (s *StringSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*StringSetting) EncodedDefault 

func (s *StringSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*StringSetting) ErrorHint 

func (i *StringSetting) ErrorHint() (bool, string)

func (*StringSetting) Get 

func (s *StringSetting) Get(sv *Values) string

Get retrieves the string value in the setting.

func (*StringSetting) SetOnChange 

func (i *StringSetting) SetOnChange(sv *Values, fn func())

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*StringSetting) SetReportable 

func (i *StringSetting) SetReportable(reportable bool)

SetReportable indicates whether a setting's value can show up in SHOW ALL CLUSTER SETTINGS and telemetry reports.

The setting can still be used with SET and SHOW if the exact setting name is known. Use SetReportable(false) for data that must be hidden from standard setting report, telemetry and troubleshooting screenshots, such as license data or keys.

All string settings are also non-reportable by default and must be opted in to reports manually with SetReportable(true).

func (*StringSetting) SetRetired 

func (i *StringSetting) SetRetired()

SetRetired marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS.

func (*StringSetting) SetVisibility 

func (i *StringSetting) SetVisibility(v Visibility)

SetVisibility customizes the visibility of a setting.

func (*StringSetting) String 

func (s *StringSetting) String(sv *Values) string

func (*StringSetting) Typ 

func (*StringSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*StringSetting) Validate 

func (s *StringSetting) Validate(sv *Values, v string) error

Validate that a value conforms with the validation function.

func (StringSetting) Visibility 

func (i StringSetting) Visibility() Visibility

type Updater 

type Updater interface {
	Set(k, rawValue, valType string) error
	ResetRemaining()
}

Updater is a helper for updating the in-memory settings.

RefreshSettings passes the serialized representations of all individual settings -- e.g. the rows read from the system.settings table. We update the wrapped atomic settings values as we go and note which settings were updated, then set the rest to default in ResetRemaining().

func NewUpdater 

func NewUpdater(sv *Values) Updater

NewUpdater makes an Updater.

type Values 

type Values struct {
	// contains filtered or unexported fields
}

Values is a container that stores values for all registered settings. Each setting is assigned a unique slot (up to MaxSettings). Note that slot indices are 1-based (this is to trigger panics if an uninitialized slot index is used).

func TODO 

func TODO() *Values

TODO is usable at callsites that do not have *settings.Values available. Please don't use this.

func (*Values) Init 

func (sv *Values) Init(opaque interface{})

Init must be called before using a Values instance; it initializes all variables to their defaults.

The opaque argument can be retrieved later via Opaque().

func (*Values) Opaque 

func (sv *Values) Opaque() interface{}

Opaque returns the argument passed to Init.

type Visibility 

type Visibility int

Visibility describes how a user should feel confident that they can customize the setting. See the constant definitions below for details. 

const (
	// Reserved - which is the default - indicates that a setting is
	// not documented and the CockroachDB team has not developed
	// internal experience about the impact of customizing it to other
	// values.
	// In short: "Use at your own risk."
	Reserved Visibility = iota
	// Public indicates that a setting is documented, the range of
	// possible values yields predictable results, and the CockroachDB
	// team is there to assist if issues occur as a result of the
	// customization.
	// In short: "Go ahead but be careful."
	Public
)

type WritableSetting 

type WritableSetting interface {
	Setting

	// Encoded returns the encoded value of the current value of the setting.
	Encoded(sv *Values) string
	EncodedDefault() string
	SetOnChange(sv *Values, fn func())
	ErrorHint() (bool, string)
}

WritableSetting is the exported interface of non-masked settings.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.