userver: Dynamic configs
⚠️ This is the documentation for an old userver version. Click here to switch to the latest version.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages Concepts
Dynamic configs

Here you can find the description of dynamic configs - options that can be changed at run-time without stopping the service.

For an information on how to write a service that distributes dynamic configs see Writing your own configs server.

Adding and using your own dynamic configs

Dynamic config values could be obtained via the dynamic_config::Source client that could be retrieved from components::DynamicConfig:

#include <userver/dynamic_config/value.hpp>
namespace myservice::smth {
Component::Component(const components::ComponentConfig& config,
: components::LoggableComponentBase(config, context),
config_(
// Searching for some component to initialize members
context.FindComponent<components::DynamicConfig>()
.GetSource() // getting "client" from a component
) {
// Reading config values from static config
[[maybe_unused]] auto url = config["some-url"].As<std::string>();
const auto fs_tp_name = config["fs-task-processor"].As<std::string>();
// Starting a task on a separate task processor from config
auto& fs_task_processor = context.GetTaskProcessor(fs_tp_name);
utils::Async(fs_task_processor, "my-component/fs-work", [] { /*...*/ }).Get();
// ...
}
} // namespace myservice::smth

To get a specific value you need a parser for it. For example, here's how you could parse and get the SAMPLE_INTEGER_FROM_RUNTIME_CONFIG option:

namespace myservice::smth {
namespace {
int ParseRuntimeCfg(const dynamic_config::DocsMap& docs_map) {
return docs_map.Get("SAMPLE_INTEGER_FROM_RUNTIME_CONFIG").As<int>();
}
} // namespace
int Component::DoSomething() const {
// Getting a snapshot of dynamic config.
const auto runtime_config = config_.GetSnapshot();
return runtime_config[kMyConfig];
}
} // namespace myservice::smth

HTTP_CLIENT_CONNECT_THROTTLE

Token bucket throttling options for new connections (socket(3)).

  • *-limit - token bucket size, set to 0 to disable the limit
  • *-per-second - token bucket size refill speed
schema:
    type: object
    properties:
        http-limit:
            type: integer
            minimum: 0
        http-per-second:
            type: integer
            minimum: 0
        https-limit:
            type: integer
            minimum: 0
        https-per-second:
            type: integer
            minimum: 0
        per-host-limit:
            type: integer
            minimum: 0
        per-host-per-second:
            type: integer
            minimum: 0
    additionalProperties: false
    required:
      - http-limit
      - https-limit
      - per-host-limit

Example:

{
"http-limit": 6000,
"http-per-second": 1500,
"https-limit": 100,
"https-per-second": 25,
"per-host-limit": 3000,
"per-host-per-second": 500
}

Used by components::HttpClient, affects the behavior of clients::http::Client and all the clients that use it.

HTTP_CLIENT_CONNECTION_POOL_SIZE

Open connections pool size for curl (CURLMOPT_MAXCONNECTS). -1 means "detect by multiplying easy handles count on 4".

schema:
type: integer

Example:

5000

Used by components::HttpClient, affects the behavior of clients::http::Client and all the clients that use it.

MONGO_DEFAULT_MAX_TIME_MS

Dynamic config that controls default $maxTimeMS for mongo requests (0 - disables default timeout).

schema:
    type: integer
    minimum: 0

Example:

200

Used by components::Mongo, components::MultiMongo.

MONGO_DEADLINE_PROPAGATION_ENABLED_V2

Dynamic config that controls whether task-inherited deadline is accounted for while executing mongodb queries.

schema:
    type: boolean

Example:

false

Used by components::Mongo, components::MultiMongo.

POSTGRES_DEFAULT_COMMAND_CONTROL

Dynamic config that controls default network and statement timeouts. Overrides the built-in timeouts from components::Postgres::kDefaultCommandControl, but could be overridden by POSTGRES_HANDLERS_COMMAND_CONTROL, POSTGRES_QUERIES_COMMAND_CONTROL and storages::postgres::CommandControl.

type: object
additionalProperties: false
properties:
  network_timeout_ms:
    type: integer
    minimum: 1
  statement_timeout_ms:
    type: integer
    minimum: 1

Example:

{
"network_timeout_ms": 750,
"statement_timeout_ms": 500
}

Used by components::Postgres.

POSTGRES_HANDLERS_COMMAND_CONTROL

Dynamic config that controls per-handle statement and network timeouts. Overrides POSTGRES_DEFAULT_COMMAND_CONTROL and built-in timeouts from components::Postgres::kDefaultCommandControl, but may be overridden by POSTGRES_QUERIES_COMMAND_CONTROL and storages::postgres::CommandControl.

type: object
additionalProperties:
  $ref: "#/definitions/CommandControlByMethodMap"
definitions:
  CommandControlByMethodMap:
    type: object
    additionalProperties:
      $ref: "#/definitions/CommandControl"
  CommandControl:
    type: object
    additionalProperties: false
    properties:
      network_timeout_ms:
        type: integer
        minimum: 1
      statement_timeout_ms:
        type: integer
        minimum: 1

Example:

{
"/v2/rules/create": {
"POST": {
"network_timeout_ms": 500,
"statement_timeout_ms": 250
}
},
"/v2/rules/select": {
"POST": {
"network_timeout_ms": 70,
"statement_timeout_ms": 30
}
}
}

Used by components::Postgres.

POSTGRES_QUERIES_COMMAND_CONTROL

Dynamic config that controls per-query/per-transaction statement and network timeouts, if those were not explicitly set via storages::postgres::CommandControl. Overrides the POSTGRES_HANDLERS_COMMAND_CONTROL, POSTGRES_QUERIES_COMMAND_CONTROL, POSTGRES_DEFAULT_COMMAND_CONTROL, and built-in timeouts from components::Postgres::kDefaultCommandControl.

Transaction timeouts in POSTGRES_QUERIES_COMMAND_CONTROL override the per-query timeouts in POSTGRES_QUERIES_COMMAND_CONTROL, so the latter are ignored if transaction timeouts are set.

type: object
additionalProperties:
  $ref: "#/definitions/CommandControl"
definitions:
  CommandControl:
    type: object
    additionalProperties: false
    properties:
      network_timeout_ms:
        type: integer
        minimum: 1
      statement_timeout_ms:
        type: integer
        minimum: 1

Example:

{
"cleanup_processed_data": {
"network_timeout_ms": 92000,
"statement_timeout_ms": 90000
},
"select_recent_users": {
"network_timeout_ms": 70,
"statement_timeout_ms": 30
}
}

Used by components::Postgres.

POSTGRES_CONNECTION_POOL_SETTINGS

Dynamic config that controls connection pool settings of PostgreSQL driver.

Take note that it overrides the static configuration values of the service!

type: object
additionalProperties:
  $ref: "#/definitions/PoolSettings"
definitions:
  PoolSettings:
    type: object
    additionalProperties: false
    properties:
      min_pool_size:
        type: integer
        minimum: 0
      max_pool_size:
        type: integer
        minimum: 1
      max_queue_size:
        type: integer
        minimum: 1
      connecting_limit:
        type: integer
        minimum: 0
    required:
      - min_pool_size
      - max_pool_size
      - max_queue_size

Example:

{
"__default__": {
"min_pool_size": 4,
"max_pool_size": 15,
"max_queue_size": 200,
"connecting_limit": 10
},
"postgresql-orders": {
"min_pool_size": 8,
"max_pool_size": 50,
"max_queue_size": 200,
"connecting_limit": 8
}
}

Used by components::Postgres.

POSTGRES_CONNECTION_SETTINGS

Dynamic config that controls settings for newly created connections of PostgreSQL driver.

Take note that it overrides the static configuration values of the service!

type: object
additionalProperties: false
properties:
  persistent-prepared-statements:
    type: boolean
    default: true
  user-types-enabled:
    type: boolean
    default: true
  max-prepared-cache-size:
    type: integer
    minimum: 1
    default: 5000
  recent-errors-threshold:
    type: integer
    minimum: 1
  ignore-unused-query-params:
    type: boolean
    default: false

Example:

{
"__default__": {
"persistent-prepared-statements": true,
"user-types-enabled": true,
"max-prepared-cache-size": 5000,
"ignore-unused-query-params": false,
"recent-errors-threshold": 2
}
}

Used by components::Postgres.

POSTGRES_CONNLIMIT_MODE_AUTO_ENABLED

Dynamic config that enables connlimit_mode: auto for PostgreSQL connections. Auto mode ignores static and dynamic max_connections configs and verifies that the cluster services use max_connections equals to PostgreSQL server's max_connections divided by service instance count.

default: false
schema:
  type: boolean

POSTGRES_STATEMENT_METRICS_SETTINGS

Dynamic config that controls statement metrics settings for specific service.

Dictionary keys can be either the service component names or __default__. The latter configuration will be applied for every PostgreSQL component of the service.

The value of max_statement_metrics controls the maximum size of LRU-cache for named statement metrics. When set to 0 (default) no metrics are being exported.

The exported data can be found as postgresql.statement_timings.

type: object
additionalProperties:
  $ref: "#/definitions/StatementMetricsSettings"
definitions:
  StatementMetricsSettings:
    type: object
    additionalProperties: false
    properties:
      max_statement_metrics:
        type: integer
        minimum: 0
{
"postgresql-database_name": {
"max_statement_metrics": 50
}
}

Used by components::Postgres.

REDIS_COMMANDS_BUFFERING_SETTINGS

Dynamic config that controls command buffering for specific service.

Command buffering is disabled by default.

type: object
additionalProperties: false
properties:
  buffering_enabled:
    type: boolean
  commands_buffering_threshold:
    type: integer
    minimum: 1
  watch_command_timer_interval_us:
    type: integer
    minimum: 0
required:
  - buffering_enabled
  - watch_command_timer_interval_us
{
"buffering_enabled": true,
"commands_buffering_threshold": 10,
"watch_command_timer_interval_us": 1000
}

Used by components::Redis.

REDIS_DEFAULT_COMMAND_CONTROL

Dynamic config that overrides the default timeouts, number of retries and server selection strategy for redis commands.

type: object
additionalProperties: false
properties:
  best_dc_count:
    type: integer
  max_ping_latency_ms:
    type: integer
  max_retries:
    type: integer
  strategy:
    enum:
      - default
      - every_dc
      - local_dc_conductor
      - nearest_server_ping
    type: string
  timeout_all_ms:
    type: integer
  timeout_single_ms:
    type: integer
{
"best_dc_count": 0,
"max_ping_latency_ms": 0,
"max_retries": 4,
"strategy": "default",
"timeout_all_ms": 2000,
"timeout_single_ms": 500
}

Used by components::Redis.

REDIS_METRICS_SETTINGS

Dynamic config that controls the metric settings for specific service.

type: object
additionalProperties:
  $ref: "#/definitions/MetricsSettings"
definitions:
  MetricsSettings:
    type: object
    additionalProperties: false
    properties:
      timings-enabled:
        type: boolean
        default: true
        description: enable timings statistics
      command-timings-enabled:
        type: boolean
        default: false
        description: enable statistics for individual commands
      request-sizes-enabled:
        type: boolean
        default: false
        description: enable request sizes statistics
      reply-sizes-enabled:
        type: boolean
        default: false
        description: enable response sizes statistics
{
"redis-database_name": {
"timings-enabled": true,
"command-timings-enabled": false,
"request-sizes-enabled": false,
"reply-sizes-enabled": false
}
}

Used by components::Redis.

REDIS_PUBSUB_METRICS_SETTINGS

Dynamic config that controls the redis pubsub metric settings for specific service.

type: object
additionalProperties:
  $ref: "#/definitions/PubsubMetricsSettings"
definitions:
  PubsubMetricsSettings:
    type: object
    additionalProperties: false
    properties:
      per-shard-stats-enabled:
        type: boolean
        default: true
        description: enable collecting statistics by shard
{
"redis-database_name": {
"per-shard-stats-enabled": true
}
}

Used by components::Redis.

REDIS_SUBSCRIBER_DEFAULT_COMMAND_CONTROL

The same as REDIS_DEFAULT_COMMAND_CONTROL but for subscription clients.

type: object
additionalProperties: false
properties:
  timeout_single_ms:
    type: integer
    minimum: 1
  timeout_all_ms:
    type: integer
    minimum: 1
  best_dc_count:
    type: integer
    minimum: 1
  max_ping_latency_ms:
    type: integer
    minimum: 1
  strategy:
    type: string
    enum:
      - default
      - every_dc
      - local_dc_conductor
      - nearest_server_ping
{
"best_dc_count": 0,
"max_ping_latency_ms": 0,
"strategy": "default",
"timeout_all_ms": 2000,
"timeout_single_ms": 500
}

Used by components::Redis.

REDIS_SUBSCRIPTIONS_REBALANCE_MIN_INTERVAL_SECONDS

Dynamic config that controls the minimal interval between redis subscription clients rebalancing.

minimum: 0
type: integer
default: 30

Used by components::Redis.

REDIS_WAIT_CONNECTED

Dynamic config that controls if services will wait for connections with redis instances.

type: object
additionalProperties: false
properties:
  mode:
    type: string
    enum:
      - no_wait
      - master
      - slave
      - master_or_slave
      - master_and_slave
  throw_on_fail:
    type: boolean
  timeout-ms:
    type: integer
    minimum: 1
    x-taxi-cpp-type: std::chrono::milliseconds
required:
  - mode
  - throw_on_fail
  - timeout-ms
{
"mode": "master_or_slave",
"throw_on_fail": false,
"timeout-ms": 11000
}

Used by components::Redis.

USERVER_CACHES

Cache update dynamic parameters.

schema:
    type: object
    additionalProperties:
        type: object
        additionalProperties: false
        properties:
            update-interval-ms:
                type: integer
                minimum: 1
            update-jitter-ms:
                type: integer
                minimum: 0
            full-update-interval-ms:
                type: integer
                minimum: 0
        required:
          - update-interval-ms
          - update-jitter-ms
          - full-update-interval-ms

Example:

{
"some-cache-name": {
"full-update-interval-ms": 86400000,
"update-interval-ms": 30000,
"update-jitter-ms": 1000
}
}

Used by all the caches derived from components::CachingComponentBase.

USERVER_CHECK_AUTH_IN_HANDLERS

Controls whether authentication checks are performed in handlers.

schema:
    type: boolean

Example:

true

Used by components::Server.

USERVER_CANCEL_HANDLE_REQUEST_BY_DEADLINE

Controls whether the http request task should be cancelled when the deadline received from the client is reached.

schema:
    type: boolean

Example:

true

Used by components::Server.

USERVER_DEADLINE_PROPAGATION_ENABLED

When false, disables deadline propagation in the service. This includes:

  • reading the task-inherited deadline from HTTP headers and gRPC metadata;
  • interrupting operations when deadline expires;
  • propagating the deadline to downstream services and databases.
schema:
    type: boolean

Example:

true

Used by components::Server and ugrpc::server::ServerComponent.

USERVER_DUMPS

Dynamic dump configuration. If the options are set for some dump then those options override the static configuration.

schema:
    type: object
    additionalProperties:
        type: object
        additionalProperties: false
        properties:
            dumps-enabled:
                type: boolean
            min-dump-interval:
                description: dump interval in milliseconds
                type: integer
                minimum: 0

Example:

{
"some-cache-name": {
"dumps-enabled": true,
"update-interval-ms": 30000,
"min-dump-interval": 100000
}
}

Used by dump::Dumper, especially by all the caches derived from components::CachingComponentBase.

USERVER_HANDLER_STREAM_API_ENABLED

Sets whether Stream API should be enabled for HTTP handlers.

schema:
    type: boolean

Example:

true

USERVER_HTTP_PROXY

Proxy for all the HTTP and HTTPS clients. Empty string disables proxy usage.

Proxy string may be prefixed with [scheme]:// to specify which kind of proxy is used. Schemes match the libcurl supported ones. A proxy host string can also embed user and password.

schema:
    type: string

Example:

localhost:8090

Used by components::HttpClient, affects the behavior of clients::http::Client and all the clients that use it.

USERVER_LOG_DYNAMIC_DEBUG

Logging per line and file overrides.

default:
    force-enabled: []
    force-disabled: []
 
schema:
    type: object
    additionalProperties: false
    required:
      - force-enabled
      - force-disabled
    properties:
        force-enabled:
            type: array
            description: logs to turn on
            items:
                type: string
 
        force-disabled:
            type: array
            description: logs to turn off
            items:
                type: string

Used by components::LoggingConfigurator.

USERVER_LOG_REQUEST

Controls HTTP requests and responses logging.

schema:
    type: boolean

Example:

false

Used by components::Server.

USERVER_LOG_REQUEST_HEADERS

Controls whether the logging of HTTP headers in handlers is performed.

schema:
    type: boolean

Example:

false

Used by components::Server.

USERVER_LRU_CACHES

Dynamic config for controlling size and cache entry lifetime of the LRU based caches.

schema:
    type: object
    additionalProperties:
        $ref: '#/definitions/CacheSettings'
    definitions:
        CacheSettings:
            type: object
            properties:
                size:
                    type: integer
                lifetime-ms:
                    type: integer
            required:
              - size
              - lifetime-ms
            additionalProperties: false

Example:

{
"some-cache-name": {
"lifetime-ms": 5000,
"size": 100000
},
"some-other-cache-name": {
"lifetime-ms": 5000,
"size": 400000
}
}

Used by all the caches derived from cache::LruCacheComponent.

USERVER_NO_LOG_SPANS

Prefixes or full names of tracing::Span instances to not log.

schema:
    type: object
    additionalProperties: false
    required:
      - prefixes
      - names
    properties:
        prefixes:
            type: array
            items:
                type: string
        names:
            type: array
            items:
                type: string

Example:

{
"names": [
"mongo_find"
],
"prefixes": [
"http",
"handler"
]
}

Used by components::LoggingConfigurator and all the logging facilities.

USERVER_RPS_CCONTROL

Dynamic config for components::Server congestion control.

schema:
    type: object
    additionalProperties: false
    properties:
        min-limit:
            type: integer
            minimum: 1
            description: |
                Minimal RPS limit value.
 
        up-rate-percent:
            type: number
            minimum: 0
            exclusiveMinimum: true
            description: |
                On how many percents increase the RPS limit every second if not in overloaded state.
 
        down-rate-percent:
            type: number
            minimum: 0
            maximum: 100
            exclusiveMinimum: true
            description: |
                On how many percents decrease the RPS limit every second if in overloaded state.
 
        overload-on-seconds:
            type: integer
            minimum: 1
            description: |
                How many seconds overload should be higher than `up-level`,
                to switch to overload state and start limiting RPS.
 
        overload-off-seconds:
            type: integer
            minimum: 1
            description: |
                How many seconds overload should be higher than `down-level`,
                to switch from overload state and the RPS limit start increasing.
 
        up-level:
            type: integer
            minimum: 1
            description: |
                Overload level that should least for `overload-on-seconds` to switch to
                overloaded state.
 
        down-level:
            type: integer
            minimum: 1
            description: |
                Overload level that should least for `overload-on-seconds` to
                increase RPS limits.
 
        no-limit-seconds:
            type: integer
            minimum: 1
            description: |
                Seconds without overload to switch from overloaded state and
                remove all the RPS limits.
 
       load-limit-crit-percent:
            type: integer
            description: |
                On reaching this load percent immediately switch to overloaded state.

Example:

{
"down-level": 8,
"down-rate-percent": 1,
"load-limit-crit-percent": 70,
"min-limit": 2,
"no-limit-seconds": 120,
"overload-off-seconds": 8,
"overload-on-seconds": 8,
"up-level": 2,
"up-rate-percent": 1
}

Used by congestion_control::Component.

USERVER_RPS_CCONTROL_ENABLED

Controls whether congestion control limiting of RPS is performed (if main task processor is overloaded, then the server starts rejecting some requests).

schema:
    type: boolean

Example:

true

Used by congestion_control::Component.

USERVER_TASK_PROCESSOR_PROFILER_DEBUG

Dynamic config for profiling the coroutine based engine of userver. Dictionary key names are the names of engine::TaskProcessor.

schema:
    type: object
    properties: {}
    additionalProperties:
        $ref: '#/definitions/TaskProcessorSettings'
    definitions:
        TaskProcessorSettings:
            type: object
            required:
              - enabled
              - execution-slice-threshold-us
            additionalProperties: false
            properties:
                enabled:
                    type: boolean
                    description: |
                        Set to `true` to turn on the profiling
                execution-slice-threshold-us:
                    type: integer
                    description: |
                        Execution threshold of a coroutine on a thread without context switch.
                        If the threshold is reached then the coroutine is logged, otherwise
                        does nothing.
                    minimum: 1

Example:

{
"fs-task-processor": {
"enabled": false,
"execution-slice-threshold-us": 1000000
},
"main-task-processor": {
"enabled": false,
"execution-slice-threshold-us": 2000
}
}

Used by components::ManagerControllerComponent.

USERVER_TASK_PROCESSOR_QOS

Controls engine::TaskProcessor quality of service dynamic config.

schema:
    type: object
    required:
      - default-service
    additionalProperties: false
    properties:
        default-service:
            type: object
            additionalProperties: false
            required:
              - default-task-processor
            properties:
                default-task-processor:
                    type: object
                    additionalProperties: false
                    required:
                      - wait_queue_overload
                    properties:
                        wait_queue_overload:
                            type: object
                            additionalProperties: false
                            required:
                              - time_limit_us
                              - length_limit
                              - action
                            properties:
                                time_limit_us:
                                    type: integer
                                    minimum: 0
                                    description: |
                                        Wait in queue time after which the `action is applied`.
                                length_limit:
                                    type: integer
                                    minimum: 0
                                    description: |
                                        Queue size after which the `action` is applied.
                                        action
                                action:
                                    type: string
                                    enum:
                                      - ignore
                                      - cancel
                                    description: |
                                        Action to perform on tasks on queue overload.
                                        `cancel` - cancels the tasks
                                sensor_time_limit_us:
                                    type: integer
                                    minimum: 0
                                    description: |
                                        Wait in queue time after which the overload events for
                                        RPS congestion control are generated.

Example:

{
"default-service": {
"default-task-processor": {
"wait_queue_overload": {
"action": "cancel",
"length_limit": 5000,
"sensor_time_limit_us": 12000,
"time_limit_us": 0
}
}
}
}

Used by components::ManagerControllerComponent.

USERVER_FILES_CONTENT_TYPE_MAP

Dynamic config for mapping extension files with http header content type

schema:
    type: object
    additionalProperties:
        type: string

Example:

{
".css": "text/css",
".gif": "image/gif",
".htm": "text/html",
".html": "text/html",
".jpeg": "image/jpeg",
".js": "application/javascript",
".json": "application/json",
".md": "text/markdown",
".png": "image/png",
".svg": "image/svg+xml",
"__default__": "text/plain"
}

Used by server::handlers::HttpHandlerStatic