Class FileLog

A logging utility that writes log output to files with built-in support for automated file rotation. Ensures efficient log management by limiting log file count and size, as well as performing disk space checks. Supports both plain text and structured JSON output formats for different use cases.

Inheritance
object
FileLog
Implements
Inherited Members
Namespace: Scylla.Core
Assembly: ScyllaCore.dll
Syntax
public sealed class FileLog : ILogReceiver, IDisposable
Remarks

Designed for applications that require persistent log storage in a structured format. Handles the creation of log directories and prevents excessive disk usage by adhering to predefined rotation and cleanup policies. Uses asynchronous file I/O for non-blocking log writes. Call Dispose() when shutting down to ensure all pending log entries are written.

Structured Logging:

When Format is set to Json, log entries are output in JSON Lines (JSONL) format - one JSON object per line. This format is ideal for log aggregation tools (ELK stack, Splunk, etc.) and automated log analysis. Each JSON object contains all log entry fields: timestamp, level, category, message, file, line, etc.

Constructors

FileLog(string, bool, FileLoggingSettings, FileLogFormattingSettings)

Initializes a new instance of the FileLog class.

Declaration
public FileLog(string productName = null, bool useAsync = true, FileLoggingSettings fileLoggingSettings = null, FileLogFormattingSettings formattingSettings = null)
Parameters
Type Name Description
string productName

The name of the game/application. Used to create a subdirectory in the user's Documents folder and as the base name for log files. If null or empty, use the application product name.
bool useAsync

Whether to use asynchronous file writes. Set to false for test environments or when synchronous behavior is needed. Default: true.
FileLoggingSettings fileLoggingSettings

Optional file logging settings. If null, default values are used.
FileLogFormattingSettings formattingSettings

Optional file log formatting settings. If null, default values are used.

Properties

Format

Gets or sets the on-disk serialization format for log entries written by this instance. Changing this property after the first log entry has been written causes subsequent entries to use the new format, but already-written files retain the format they were created with.

Declaration
public LogFileFormat Format { get; set; }
Property Value
Type Description
LogFileFormat

PlainText for human-readable .log files (default), or JSON for machine-readable JSON Lines .json files.
Remarks

When set to JSON, log entries are serialized as JSON objects (one per line), making them straightforward to ingest by log aggregation tools such as the ELK stack, Splunk, or Grafana Loki. PlainText produces human-readable output suitable for reading directly in a text editor.

LogLabelLevel

Gets the minimum LogLevel at which the descriptive level label (e.g. [DEBUG], [WARNING]) is included in file log output. This implementation returns Minimum, so labels are always written to file regardless of severity, providing the richest possible context for log analysis.

Declaration
public LogLevel LogLabelLevel { get; }
Property Value
Type Description
LogLevel

Minimum, so labels are included for all log levels.

LogPrefix

Gets the prefix string that prepends all log messages in the file log. Returns LOG_PREFIX (e.g. [Scylla]), making Scylla entries distinguishable from other content in the log file.

Declaration
public string LogPrefix { get; }
Property Value
Type Description
string

The constant prefix string defined by LOG_PREFIX.

ShowCategory

Gets or sets whether the padded log category (e.g. [Core]) is written for each log entry in the file log output.

Declaration
public bool ShowCategory { get; set; }
Property Value
Type Description
bool

true to include PaddedCategory when it is non-empty; false to omit it. Default: true.

ShowCodeLocation

Gets or sets whether the source file name and line number are written for each log entry in the file log output.

Declaration
public bool ShowCodeLocation { get; set; }
Property Value
Type Description
bool

true to include the bracketed code location (e.g. [ScyllaBootstrap.cs:236]) built from FilePath and LineNumber; false to omit it. The field is suppressed automatically if the file path is null or the line number is zero. Default: true.

ShowLabel

Gets or sets whether the padded log-level label (e.g. [WARNING]) is written for each log entry in the file log output.

Declaration
public bool ShowLabel { get; set; }
Property Value
Type Description
bool

true to include PaddedLabel when it is non-empty; false to omit it. The label is only present for entries whose level meets LogLabelLevel. Default: true.

ShowPrefix

Gets or sets whether the log prefix (e.g. [Scylla]) is written for each log entry in the file log output.

Declaration
public bool ShowPrefix { get; set; }
Property Value
Type Description
bool

true to include Prefix; false to omit it. Default: true.

ShowTimestamp

Gets or sets whether a timestamp is written for each log entry in the file log output.

Declaration
public bool ShowTimestamp { get; set; }
Property Value
Type Description
bool

true to include Timestamp surrounded by brackets before each entry; false to omit it. Default: true.

Methods

ClearLog()

Clears all log files managed by this FileLog instance.

Declaration
public void ClearLog()
Remarks

Deletes all existing log files located in the configured log directory (both .log and .json files) and resets the current log file path. If an error occurs while deleting a specific file, the method continues to attempt deletion of the remaining files.

Dispose()

Disposes the FileLog instance, ensuring all pending log entries are written. This should be called when shutting down the application to ensure no logs are lost.

Declaration
public void Dispose()

Flush(int)

Flushes all pending log entries to disk synchronously. This method waits for all queued log entries to be written. Use this method in synchronous contexts like unit tests. Note: If async is disabled, this method returns immediately as writes are already synchronous.

Declaration
public bool Flush(int maxIterations = 1000)
Parameters
Type Name Description
int maxIterations

Maximum number of iterations to wait. Default: 1000.
Returns
Type Description
bool

True if queue is empty (flush likely completed), false if timeout occurred.

FlushAsync()

Flushes all pending log entries to the disk asynchronously. This method ensures that all queued log entries are written before returning.

Declaration
public Task FlushAsync()
Returns
Type Description
Task

A task that completes when all pending log entries have been written.

LogData(LogEntry)

Logs a formatted log entry to the log file.

Declaration
public void LogData(LogEntry logEntry)
Parameters
Type Name Description
LogEntry logEntry

The formatted log entry containing all pre-processed components.

Implements

Extension Methods

See Also