States Configuration

How to set the config

Previously, in order to set the config, it was necessary to modify the appsettings file (which is located in the solution). It was annoying, since it meant that all the configuration was in one file, and the appsettings was overridden at every new release.

Using environment Variable

Any parameter can be specified using Environment variable (complete documentation can be found here). The environment variable should be prefixed by DFAKTO_STATES_.

Example

Let’s say we want to modify this default configuration (as present in the appsettings)

CODE

{
  "stateCore": {
        "RedisOptions": "localhost:6379",
        "ExecutionRetentionDays": 90,
        "ExecutionsCountLimit": 1000
    }
}

You can set environment variable like this :

CODE

DFAKTO_STATES_STATECORE__REDISOPTIONS = “otherserver:6379”
DFAKTO_STATES_STATECORE__ExecutionRetentionDays = 50
DFAKTO_STATES_STATECORE__ExecutionsCountLimit = 10

Using Json Configuration file

The config is located inside a config folder, which is located in the AppDataPath (which is decided when installing the solution). The configuration can also be spread among multiple file. The name of the files does not matter, as long as they reside in the config folder.

The order in which the configuration is decided is as follow : The field that are set in a file located in the config folder have a higher “priority” than the fields set in the appsettings. If multiple file set the same field, than it will be decided by the file name alphabetical order which field is kept. If a field is not set in any file

Example

Let’s say we want to modify this default configuration (as present in the appsettings)

CODE

{
  "stateCore": {
        "RedisOptions": "localhost:6379",
        "ExecutionRetentionDays": 90,
        "ExecutionsCountLimit": 1000
    }
}

Let’s say we are happy with this default configuration, except for the “RedisOptions” field, which we want to change to use the port 7000 (in this example). in this case, we will create a file in the “config” folder, with this content

CODE

{
  "stateCore": {
        "RedisOptions": "localhost:7000",
    },
}

Configuration Sections

logs

By default all applications are sending reasonable logs to console, the configuration can be updated using Serilog configuration section.

JSON

{
    "Serilog": {
        "MinimumLevel": {
            "Default": "Information",
            "Override": {
                "Microsoft": "Warning",
                "System": "Warning"
            }
        },
        "WriteTo": [
            {
                "Name": "Console",
                "Args": {
                    "theme": "Serilog.Sinks.SystemConsole.Themes.AnsiConsoleTheme::Code, Serilog.Sinks.Console",
                    "outputTemplate": "[{Timestamp:yyyy-MM-dd HH:mm:ss.fff} {Level:u3}] {Message:lj} <s:{SourceContext}>{NewLine}{Exception}"
                }
            },
            { 
                "Name": "File",
                "Args":{ 
                    "path": "/var/log/testlog_.txt", 
                    "rollingInterval": "Day",
                    "fileSizeLimitBytes": 10000000,
                    "rollOnFileSizeLimit": true,
                    "retainedFileCountLimit": 10
                }
            }
        ]
    }
}

By default all applications are sending reasonable logs to console, the configuration can be updated using Serilog configuration section.

Here is the configuration of the logs. The most useful field to set is probably the path field, which set where the logs are going to be stored on the disk.

for the others options :

MinimumLevel: Indicate the level of log we want to store. From low to high, these are Verbose, Debug, Information, Warning, Error and Fatal
rollOnfileSizeLimit: Indicate if we want to create a new log file when the current one reach its size limit
fileSizeLimitByte: Indicate the size limit of a log file. once this size is reached, a new file will be created if the rollOnfileSizeLimit is set to true
retainedFileCountLimit: Indicate how much file we should have we start overriding the first log file.
option : formatter: The formatter decide the format of the logs (text, json, ..)

For more option, see https://github.com/serilog/serilog-settings-configuration

Sentry

Sentry (https://sentry.io/) is an application monitoring platform

CODE

{
  "Sentry": {
      "Dsn": "",
      "IncludeRequestPayload": true,
      "SendDefaultPii": true,
      "MinimumBreadcrumbLevel": "Debug",
      "MinimumEventLevel": "Warning",
      "AttachStackTrace": true,
      "Debug": true,
      "DiagnosticsLevel": "Error",
      "DefaultTags": {
          "client": "XXX"
      }
  }
}

DNS: where to send events so the events are associated with the correct project.
IncludeRequestPayload: whether or not we should send the request body to Sentry. This is done so that the request data can be read at a later point in case an error happens while processing the request.
SendDefaultPii: Whether or not we should we report the user that made the request
MinimumBreadcrumbLevel: Configure the lowest level a message has to be to become a breadcrumb. Breadcrumbs are the last (by default 100) log that were send before the event was fired to Sentry.
MinimumEventLevel: A LogLevel which indicates the minimum level a log message has to be to be sent to Sentry as an event. By default this value is Error.
AttachStackTrace: Configures whether Sentry should generate and attach stacktraces to capture message calls.
Debug: Turns debug mode on or off. If debug is enabled Sentry will attempt to print out useful debugging information if something goes wrong with sending the event. The default is always false. It's generally not recommended to turn it on in production, though turning debug mode on will not cause any safety concerns.
DiagnosticsLevel: Debug by default.
DefaultTags: Defaults tags to add to all events.

State Core

CODE

"stateCore": {
    "RedisOptions": "localhost:6379",
    "ExecutionRetentionDays": 90,
    "ExecutionsCountLimit": 1000,
    "AwsAccessKey":"",
    "AwsSecretKey":""
},

RedisOptions: The location of the redis instance
ExecutionRetentionDays: After how many days the info about execution already finished should be deleted. Default to 90 days
ExecutionCountLimit: After how many execution should we start to clean up finished execution. Default to 1000 executions.
AwsAccessKey, AwsSecretKey: >= 1.5.0 if specified, a user will be created with this access key and corresponding secret key

If the ExecutionRetentionDays and ExecutionCountLimit options are both set, the first condition that is met will trigger the deletion of executions.

Authentication

CODE

{
  "Authentication": {
      "Authority": "",
      "ClientId": "",
      "Audience": ""
      "Scope":""
  }
}

The claim authority, for example https://accounts.dfakto.com/auth/realms/dFakto.
The default Scope are : “profile email openid”
Audience : see https://github.com/keycloak/keycloak-documentation/blob/master/server_admin/topics/clients/oidc/audience.adoc

Prometheus integration

Prometheus (https://prometheus.io/) is an open-source systems monitoring and alerting

CODE

 {
    "MetricsOptions": {
        "DefaultContextLabel": "dFakto States",
        "Enabled": true
    },
    "MetricsWebTrackingOptions": {
        "ApdexTrackingEnabled": true,
        "ApdexTSeconds": 0.1,
        "IgnoredHttpStatusCodes": [ 404 ],
        "IgnoredRoutesRegexPatterns": [],
        "OAuth2TrackingEnabled": true
    },
    "MetricEndpointsOptions": {
        "MetricsEndpointEnabled": true,
        "MetricsTextEndpointEnabled": false,
        "EnvironmentInfoEndpointEnabled": true
    }
}

DefaultContextLabel: Metrics recorded are grouped into “Contexts”, for example a database context or application context. Metrics names should be unique per context. default is “Application”.
Enabled: Allows recording of all metrics to be enabled/disabled, default is true.
ApdexTrackingEnabled: Allows enabling/disabling of calculating the apdex score on the overall responses times. Defaults to true. the Apdex (Application Performance Index) is used to monitor end-user satisfaction. It is an open industry standard that estimates the end user’s satisfaction level on an application’s response time through a score between 0 and 1.
apdexTSeconds: The Apdex T seconds value used in calculating the score on the samples collected.
IgnoredHttpStatusCode: Allows specific http status codes to be ignored when reporting on response related information, e.g. You might not want to monitor 404 status codes.
IngoredRoutesRegexPatterns: An list of regex patterns used to ignore matching routes from metrics tracking.
Oauth2TrackingEnabled: Allows recording of all OAuth2 Client tracking to be enabled/disabled. Defaults to true.
MetricsEndPointEnabled: Allows enabling/disabling of the /metrics endpoint, when disabled will result in a 404 status code, the default is true.
MetrucsTextEndpointEnabled: Allows enabling/disabling of the /metrics-text endpoint, when disabled will result in a 404 status code, the default is true.
EnvironmentInfoEndpointEnabled: Allows enabling/disabling of the /env endpoint, when disabled will result in a 404 status code, the default is true.

Other

CODE

{
  "Hsts": {
        "MaxAge": "00.00:05:00",
        "Preload": true
    }
}

HTTP Strict Transport Security (HSTS) is a simple and widely supported standard to protect visitors by ensuring that their browsers always connect to a website over HTTPS.

MaxAge: The time, that the browser should remember that a site is only to be accessed using HTTPS.
Preload: it is possible to enforce secure connections on a higher level, even before visiting a website for the first time: the HSTS preload list. This is a list, managed by google, with domain names that by default support HSTS:

CODE

{
  "Urls": "http://localhost:5000",
  "ForwardedHeadersOptions": {
      "ForwardedHeaders": "All"
  }
}

The ForwardedHeadersOptions set the behavior of proxied headers onto the requests. You can most likely leave it to the default All value.

The accepted values are :

All : Process X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Proto.
None : Do not process any forwarders
XForwardedFor : Process X-Forwarded-For, which identifies the originating IP address of the client.
XForwardedHost : Process X-Forwarded-Host, which identifies the original host requested by the client.
XForwardedProto : Process X-Forwarded-Proto, which identifies the protocol (HTTP or HTTPS) the client used to connect.

IpRateLimiting >= 1.5.0

It is possible to limit the number of requests sent to the api to avoid DDoS. All options are described here. Here is a sample configuration section.

Ip Rate Limiting is disabled by default (if no configuration is provided)

CODE

  "IpRateLimiting": {
    "EnableEndpointRateLimiting": false,
    "StackBlockedRequests": false,
    "RealIpHeader": "X-Real-IP",
    "ClientIdHeader": "X-ClientId",
    "HttpStatusCode": 429,
    "IpWhitelist": [ "127.0.0.1", "::1/10" ],
    "EndpointWhitelist": [ "get:/health/live","get:/health/ready" ],
    "ClientWhitelist": [ ],
    "GeneralRules": [
      {
        "Endpoint": "*",
        "Period": "1s",
        "Limit": 2
      },
      {
        "Endpoint": "*",
        "Period": "15m",
        "Limit": 100
      },
      {
        "Endpoint": "*",
        "Period": "12h",
        "Limit": 1000
      },
      {
        "Endpoint": "*",
        "Period": "7d",
        "Limit": 10000
      }
    ]
  }