Configuration

Using configuration

From version 3.0.0 Mjolnir supports strongly typed configuration. See MjolnirConfiguration file.

Configuration should be initialized on application start. See Installing and Configuring. Configuration setting can be changed later see Updating configuration.

An instance of MjolnirConfiguration class should be treated as a singleton and ideally be provided by Dependency Injection mechanism.

Configuring Timeouts

^{See also Timeouts and Cancellation.}

• Per-Command Timeout - Timeouts are configurable per-command. See Command Names to understand how the command-name component is generated from the Command's group and class name.

  MjolnirConfiguration.CommandConfigurations[<command-name>].Timeout = 2000
  

  Example: A Command class called FileExistsInS3Command with the command group s3 would use the configuration:

  MjolnirConfiguration.CommandConfigurations["s3.FileExistsInS3"].Timeout=2000
  

  Note: MjolnirConfiguration.CommandConfigurations is a dictionary where key is a command-name string and value is a CommandConfiguration instance.

• Global Ignore - Timeouts can be globally ignored. Only recommended for use in local/testing environments.

  MjolnirConfiguration.IgnoreTimeouts=false
  

• Default value - For commands not defined in configuration default value will be used

  MjolnirConfiguration.DefaultCommandConfiguration.Timeout = 0
  

Configuring Bulkheads

^{See also Bulkheads.}

• Bulkhead Maximum - The number of Commands that can execute in the Bulkhead concurrently before subsequent Command attempts are rejected.

  _{Per-bulkhead configuration. bulkhead-key is the argument passed to the Command constructor.}

  MjolnirConfiguration.BulkheadConfigurations[<bulkhead-key>].MaxConcurrent=10
  

  Note: MjolnirConfiguration.BulkheadConfigurations is a dictionary where the key is a command-name string and value is a BulkheadConfiguration instance.

• Default value System-wide default. Used if a per-bulkhead maxConcurrent isn't configured.

  MjolnirConfiguration.DefaultBulkheadConfiguration.MaxConcurrent = 10
  

Configuring Circuit Breakers

^{See also Circuit Breakers.}

• Global Enable/Disable - Circuit Breakers can be globally disabled.

  MjolnirConfiguration.UseCircuitBreakers=true
  

• Counting Window - A Breakers monitors error counts within a short, non-rolling window of time, resetting counts when the window ends.

  _{Per-breaker configuration. breaker-key is the argument passed to the Command constructor.}

  MjolnirConfiguration.BreakerConfigurations[<breaker-key>].WindowMillis=30000
  

  Note: MjolnirConfiguration.BreakerConfigurations is a dictionary where key is a command-name string and value is a BreakerConfiguration instance.

  _{System-wide default. Used if a per-breaker WindowMillis isn't configured.}

  MjolnirConfiguration.DefaultBreakerConfiguration.WindowMillis=30000
  

• Minimum Operations - a Breaker won't trip until it sees at least this many operations come through in the configured WindowMillis.

  _{Per-breaker configuration. breaker-key is the argument passed to the Command constructor.}

  MjolnirConfiguration.BreakerConfigurations[<breaker-key>].MinimumOperations=10
  

  Note: MjolnirConfiguration.BreakerConfigurations is a dictionary where key is a command-name string and value is a BreakerConfiguration instance.

  _{System-wide default. Used if a per-breaker MinimumOperations isn't configured.}

  MjolnirConfiguration.DefaultBreakerConfiguration.MinimumOperations=10
  

• Threshold Percentage - If the error rate within the window meets or exceeds this percentage, the Breaker will trip.

  _{Per-breaker configuration. breaker-key is the argument passed to the Command constructor.}

  MjolnirConfiguration.BreakerConfigurations[<breaker-key>].ThresholdPercentage=50
  

  Note: MjolnirConfiguration.BreakerConfigurations is a dictionary where key is a command-name string and value is a BreakerConfiguration instance.

  _{System-wide default. Used if a per-breaker ThresholdPercentage isn't configured.}

  MjolnirConfiguration.DefaultBreakerConfiguration.ThresholdPercentage=50
  

• Tripped Duration - When the Breaker trips, it will wait this long before attempting a test operation to see if it should close and fix itself.

  _{Per-breaker configuration. breaker-key is the argument passed to the Command constructor.}

  MjolnirConfiguration.BreakerConfigurations[<breaker-key>].TrippedDurationMillis=10000
  

  Note: MjolnirConfiguration.BreakerConfigurations is a dictionary where key is a command-name string and value is a BreakerConfiguration instance.

  _{System-wide default. Used if a per-breaker TrippedDurationMillis isn't configured.}

  MjolnirConfiguration.DefaultBreakerConfiguration.TrippedDurationMillis=10000
  

• Force Tripped/Fixed - Forces a Breaker tripped (open) or fixed (closed), regardless of its current error count. If both are true, the Breaker will be tripped.

  _{Per-breaker configurations. breaker-key is the argument passed to the Command constructor.}

  MjolnirConfiguration.BreakerConfigurations[<breaker-key>].ForceTripped=false
  MjolnirConfiguration.BreakerConfigurations[<breaker-key>].ForceFixed=false
  

  Note: MjolnirConfiguration.BreakerConfigurations is a dictionary where key is a command-name string and value is a BreakerConfiguration instance.

  _{System-wide default. Used if a per-breaker ForceTripped/ForceFixed isn't configured.}

  MjolnirConfiguration.DefaultBreakerConfiguration.ForceTripped=false
  MjolnirConfiguration.DefaultBreakerConfiguration.ForceFixed=false
  

Other Configuration

• Global Killswitch - Mjolnir can be turned off entirely if needed (though it's certainly not recommended). If isEnabled is set to false, Mjolnir will still do some initial work (like ensuring a single invoke per Command), but will then just execute the Command (calling Execute() or ExecuteAsync()) instead of passing it through Bulkheads and Circuit Breakers. No timeouts will be applied; a CancellationToken.None will be passed to any method that supports cancellation.

  MjolnirConfiguration.IsEnabled=true
  

JSON-file based config

You can see an example of JSON file based config implementation in tests project ExampleJsonConfigProvider. This implementation uses Microsoft.Extensions.Configuration to bind JSON config into MjolnirConfiguration class.

Example MjolnirConfiguration json file:

{
    "MjolnirConfiguration": {
        "IsEnabled": true,
        "IgnoreTimeouts": true,
        "UseCircuitBreakers": true,
        "DefaultCommandConfiguration": {
            "Timeout": 1000
        },
        "CommandConfigurations": {
            "TestKey": {
                "Timeout": 1050
            },
            "TestKey2": {
                "Timeout": 1030
            }
        },
        "DefaultBulkheadConfiguration": {
            "MaxConcurrent": 10
        },
        "BulkheadConfigurations": {
            "TestGroupKey": {
                "MaxConcurrent": 5
            }
        },
        "DefaultBreakerConfiguration": {
            "WindowMillis": 1000,
            "MinimumOperations": 10,
            "ThresholdPercentage": 50,
            "TrippedDurationMillis": 1000,
            "ForceTripped": false,
            "ForceFixed": false
        },
        "BreakerConfigurations": {
            "TestKey": {
                "WindowMillis": 1000,
                "MinimumOperations": 10,
                "ThresholdPercentage": 50,
                "TrippedDurationMillis": 1000,
                "ForceTripped": false,
                "ForceFixed": false
            },
            "TestKey2": {
                "WindowMillis": 500,
                "MinimumOperations": 5,
                "ThresholdPercentage": 500,
                "TrippedDurationMillis": 2000,
                "ForceTripped": true,
                "ForceFixed": true
            }
        }
    }
}

Updating configuration

Mjolnir configuration supports dynamic changes. In order to notify Mjolnir library that configuration has changed you should call NotifyAfterConfigUpdate() function on MjolnirConfiguration.

Internally Mjolnir will reload all timers which are affected by the changes to the configuration. Not changing the config and calling NotifyAfterConfigUpdate() will not do anything.

Multi-threading

Note that you should not manipulate configuration dictionaries (e.g. MjolnirConfiguration.BreakerConfigurations) in multiple threads as those are not thread-safe. Instead just replace the whole dictionary. See ExampleJsonConfigProvider for example of config reloading implementation.