Tracing

Tracing

Tracing involves specialised logging to record information about the system's execution. Programmers typically use this information for debugging purposes and to diagnose common issues within the system. The tracing used here does have a small impact on performance, so it should only be used when necessary. Typically, tracing is not in use.

The tracing comes with different level types and is set according to the information needed.

SeriLog

This system uses a tracing facility called SeriLog, which will write the trace log into a file. The file might be in Text or JSON format. SeriLog operates on the concept of minimum trace level. If a minimum level is specified, all levels above will be used.

The Trace levels

SeriLog comes with the following options, where Verbose is the lowest level. Specifying verbose will enable complete tracing. Fatal is the highest level, and selecting it will trace only that level. No options exist to turn SeriLog off, so the Fatal level will be specified when no or limited logging should occur.

1. Verbose
2. Debug
3. Information
4. Warning
5. Error
6. Fatal

The Filename

The filename will include the location and the name with the extension.

1. The file location - It is important that the system can write to the file at the specified location.
2. The filename - The name of the file may include a placeholder for the date when the file was created; this has the syntax {Date}
3. The extension - The file extensions supported are .txt or .json and will define the file content format.

The Safran Log

The system is divided into various areas, and each area may be specified to be traced individually. The Safran log builds on the SeriLog information level, meaning tracing offers a more granular details setting.

The areas

The areas are layers built on top of each other, where API is the outer level, and data is the inner level.

1. API - the outer level capturing any input and output from the system
2. Controller - a level to capture any action/instructions provided to the system
3. Service - internal level
4. Repositories - internal level
5. Data - internal level

The trace options

The Safran Log offers options to specify what SeriLog information details to trace per area. Not all areas will perform the provided trace as specified. DBConnection will not be traced for the API area, as no database connection is performed within that area.

1. Information - An information-specified trace.
2. SQL - The SQL command is sent to the database.
3. DBConnection - Connection and disconnection of the database.
4. Data - The data result of an action performed.

The Safran Log offers options to specify what SeriLog debug details to trace per area.

1. Call - The internal method enters and exits actions.

Setup

The "appsettings.json" file defines the tracing configuration within the "tracelog" section.

"tracelog": {
  "serilog": {
    "_comment_serilog": "Valid values for serilog: Verbose, Debug, Information, Warning, Error, Fatal",
    "minimum_level": "Debug",
    "write_to_file_path": "c:\\temp\\SafranAPI.{Date}.Log.txt"
  },
  "safranlog": {
    "_comment_safranlog": "Valid values for area: info, sql, dbconnection, data, call.",
    "api": "info,call",
    "controller": "info,sql,dbconnection,data",
    "service": "info,sql,dbconnection,data",
    "repositories": "info,sql,dbconnection,data",
    "data": "info,sql,dbconnection,data"
  }
}

<!--Valid values for serilog: Verbose, Debug, Information, Warning, Error, Fatal.-->
<add key="serilog:minimum-level" value="Debug" />
<add key="serilog:write-to:File.path" value="c:\temp\SafranAPI.{Date}.Log.txt" />
<!-- Valid values for area: info, sql, dbconnection, data, call -->
<add key="safranlog.api"          value="info,call" />
<add key="safranlog.controller"   value="info,sql,dbconnection,data" />
<add key="safranlog.service"      value="info,sql,dbconnection,data" />
<add key="safranlog.repositories" value="info,sql,dbconnection,data" />
<add key="safranlog.data"         value="info,sql,dbconnection,data" />