Navigation :

EDR Configuration

Enablement

To configure a JSLEE service to have EDR support, add the edr configuration section to the application’s JSLEE configuration, e.g.:

{
  "applications": {
    "app1": {
      "configuration": {      
        "edr": {
          "enabled": true,
          "storage-directory": "/edr",
          "store-via": "nz.co.nsquared.slee.edr.storage.FileEdrStorageService"

The edr section can also be inserted into the global configuration, e.g.:

{
  "edr": {
    "storage-directory": "/edr",
    "store-via": "nz.co.nsquared.slee.edr.storage.FileEdrStorageService"
  },
  "applications": {
    "app1": {
      "configuration": {    
        "edr": {
          "enabled": true,

Global EDR configuration will apply to all services, but parameters specified at the service level will override those defined at the global level.

If no edr configuration is provided at all or if the edr.enabled flag is either not present or set to false, EDRs will not be produced.

EDR Sinks

There are multiple EDR sinks available for EDRs. Choose an appropriate EDR sink for your architecture.

EDRs to an In-Memory Ring Buffer

Primarily for unit testing, EDRs can be pushed to an internal in-memory ring buffer. Software code can access the in-memory ring buffer as a singleton object on the RingBufferEdrStorageService class.

{
  "applications": {
    "app1": {
      "configuration": {      
        "edr": {
          "enabled": true,
          "store-via": "nz.co.nsquared.slee.edr.storage.RingBufferEdrStorageService"

There is no additional configuration available for this EDR sink.

EDRs to the Logfile

Architecturally, the JSLEE uses Slf4J as its logging framework, and the actual logging is done by Logback. To simply log EDRs as info messages out to the log via the Slf4J logging system, use the log file sink. This sink is the default when EDRs are enabled, but can also be explicitly listed:

{
  "applications": {
    "app1": {
      "configuration": {      
        "edr": {
          "enabled": true,
          "store-via": "nz.co.nsquared.slee.edr.storage.LogEdrStorageService"

The following configuration options are available:

Field	Type	Required?	Default	Description
`convert-to-tag-value`	Boolean	No	`false`	Useful for development, debugging and tracing. EDRs are written as TAG=VALUE strings, rather than JSON objects.

EDRs to Disk

To sink EDRs directly to an on-disk file, use the file sink:

{
  "applications": {
    "app1": {
      "configuration": {      
        "edr": {
          "enabled": true,
          "store-via": "nz.co.nsquared.slee.edr.storage.FileEdrStorageService"

The following configuration options are available:

Field	Type	Required?	Default	Description
`storage-directory`	String	Yes	-	The directory in to which the EDR files are stored.
`file-prefix`	String	No	`n2jslee`	The prefix to prepend to the files generated by the EDR sink.
`file-suffix`	String	No	`edr`	The suffix to append to the files generated by the EDR sink.
`max-edrs-per-file`	Integer	No	`5000`	The maximum number of EDRs (lines) to write per file before closing and opening a new file.
`max-bytes-per-file`	Integer	No	`1048576`	The maximum number of bytes per file before closing the file and opening a new one. Note that this does not account for the header nor footer.
`max-seconds-per-file`	Integer	No	`300`	The number of seconds a file may be open before closing and opening a new one. Only relevant in situations where the `max-lines-per-file` or `max-bytes-per-file` limits are not reached.
`expire-empty-files`	Boolean	No	`true`	Whether files without EDR content are closed and re-opened based on `max-seconds-per-file`. Has no effect on files where EDRs exist.
`file-open-retry-seconds`	Integer	No	`15`	If the system fails to open a file to write, how many seconds it should wait before retrying.
`convert-to-tag-value`	Boolean	No	`false`	Useful for development, debugging and tracing. EDRs are written as TAG=VALUE strings, rather than JSON objects.

Note that it is very important to size the max- parameters to appropriate values to avoid a lot of files being opened and closed too often, as this can have an adverse effect on performance. Ideally, files will be closed at regular intervals regardless of which limit is breached.

EDRs output using the file storage option are written to disk periodically, and it is the responsibility of operations management teams to archive written files appropriately.

Files written to disk have their names formatted as:

<prefix>_<server>_<application>_<instance>_<timestamp>.<suffix>

This name information is sourced as:

prefix - set from file-prefix.
server - the hostname of the server the file was generated on.
application - the configured application name.
instance ID - a unique (per SLEE startup) ID for the particular instance of the service writing the file.
timestamp - the timestamp that the file was opened at.
suffix - set from file-suffix.

In-progress EDR files are suffixed with .in_progress, and this is removed when an EDR file is closed.

Each file written is a JSON object that contains an array of single-line EDRs as well as summary information about the EDRs in the file in the format:

{
    "edrs":[
        <EDR records here, one per line>
    ],
    "info":<EDR file information>
}

The EDR file summary information has the following fields:

Field	Description
`file-path`	The filename of the file the header is written to by the EDR-writing application.
`start-time`	The time the EDR file was opened as a UTC timestamp formatted as ISO 8601 with millisecond precision.
`finish-time`	The time the EDR file was closed as a UTC timestamp formatted as ISO 8601 with millisecond precision.
`host-name`	The server name, as determined during process startup.
`edr-count`	The number of EDRs written in the file. This will be the number of lines in the `edrs` array.
`edr-bytes`	The number of bytes written for EDRs in the `edrs` array, including commas and newline characters.