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.

Selective Endpoint Logging

Description

The API supports selective logging of API endpoints, allowing detailed logs to be captured only for chosen controllers, routes, and HTTP methods.
All code executed as part of a matching request (controller, services, repositories) is logged automatically.
The feature is configuration‑driven and controlled through appsettings.json. If the feature is disabled or not configured, the system continues to use the existing logging behavior, as defined in the Safran Log.

Configuration

Selective logging is configured under the tracelog:LogCapture section.

How it works

• When enabled, incoming requests are matched against the configured rules.
• If a request matches:
  • All log entries produced during that request are captured.
• If a request does not match:
  • It is ignored by the selective logging mechanism.
• Existing logging continues to function as before.

Matching rules

A request is logged when all of the following conditions are met:

• Enabled is set to true
• The HTTP method matches one of the configured Methods (if specified)
• At least one of the following matches:
  • Request path starts with a configured route prefix (1)
  • Action name (2)
  • Controller name (3)

Matching is case‑insensitive.

The required details are found in each individual endpoint you wish to log.

Enabling and disabling

• Enable selective logging: set "Enabled": true
• Disable selective logging: set "Enabled": false

When disabled, the application automatically falls back to the original logging behavior.

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,data",
        "controller": "info,sql,dbconnection,data",
        "service": "info,sql,dbconnection,data",
        "repositories": "info,sql,dbconnection,data",
        "data": "info,sql,dbconnection,data"
  },
  "LogCapture": {
        "Enabled": false,
        "Controllers": [ project_previews", "activities" ],
        "Actions": [ "GET", "POST", "PATCH" ],
        "RoutePrefixes": [ "/v1/project_previews", "/v1/activities" ],
        "UseRegex": false
  }
}

<!--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" />