Class FileLoggingSettings

Settings that govern the behavior of the FileLog receiver, including file rotation policy, disk space protection, directory location, and the async write pipeline.

Inheritance
object
FileLoggingSettings
Inherited Members
Namespace: Scylla.Core.Config
Assembly: ScyllaCore.dll
Syntax
[Serializable]
public sealed class FileLoggingSettings
Remarks

These settings are read once by FileLog at construction time. Changing them at runtime has no effect on an already-running FileLog instance; ScyllaBootstrap must recreate the receiver for changes to take effect.

File rotation: When a log file reaches MaxLogFileSizeMB, the writer selects the next available slot up to MaxLogFiles. Once all slots are occupied the oldest file is overwritten, creating a circular log-file ring.

Disk space guard: Before every write the FileLog checks that free space on the log drive meets MinFreeDiskSpaceMB. If the threshold is not met, file logging is silently disabled for the session to avoid filling the disk.

Async pipeline: Log entries are queued in a ConcurrentQueue and drained by a background Task. BatchSize controls how many entries are gathered per write call; FlushIntervalMs controls the polling cadence when the queue is empty.

Fields

BatchSize

Number of log entries accumulated in the async queue before a single batch write is issued to disk. Higher values amortize file I/O across more entries and reduce write frequency, but increase the number of entries that can be lost if the application crashes before the batch is flushed. Very low values (below 10) cause near-continuous disk writes. Very high values (above 100) risk losing many entries on an unexpected crash. The recommended range is 25-75 entries per batch.

Declaration
[Tooltip("Number of log entries collected in memory before they are written to disk as a single batch. Higher values reduce disk I/O frequency at the cost of more in-memory entries. Lower values flush to disk more frequently, reducing the risk of data loss on crash.")]
[Range(1, 500)]
public int BatchSize
Field Value
Type Description
int

FlushIntervalMs

How long the background write task sleeps, in milliseconds, when the log entry queue is empty before polling again. Lower values reduce the latency between a log call and the entry appearing in the file, but increase CPU wake-up frequency on the background thread. Very low values (below 5 ms) may cause excessive CPU usage on some platforms. Very high values (above 100 ms) can delay log output and increase the number of entries lost on a hard crash. The recommended range is 10-50 ms.

Declaration
[Tooltip("Interval in milliseconds at which the file logger polls its internal queue for new entries and writes them to disk. Lower values provide more timely output but increase I/O overhead. Higher values reduce overhead but delay when entries appear in the log file.")]
[Range(1, 1000)]
public int FlushIntervalMs
Field Value
Type Description
int

LogSubFolder

Name of the subdirectory created under the platform's user documents folder (or Application.persistentDataPath as a fallback) where log files are stored. For example, with an application named "MyGame" and LogSubFolder = "Logs", files are written to Documents/MyGame/Logs/. This field must not be null, empty, or whitespace; the ScyllaLoggerConfiguration validator reports an error if it is.

Declaration
[Tooltip("Name of the subdirectory within the application's persistent data path where log files are stored. Change this to organize logs separately from other application data, or to distinguish logs from different build configurations.")]
public string LogSubFolder
Field Value
Type Description
string

MaxLogFileSizeMB

Maximum size in megabytes that a single log file may grow to before the FileLog rotates to the next file slot. Very small values (below 0.5 MB) cause frequent rotation and excess disk I/O. Very large values (above 10 MB) produce files that are slow to open and search. The recommended range is 1-5 MB. Use MaxFileSizeBytes to obtain this value in bytes, which is what FileLog uses internally for comparison.

Declaration
[Tooltip("Maximum size of a single log file in megabytes before the logger rotates to a new file. Smaller values produce more granular files that are easier to transfer, while larger values reduce the frequency of file rotation.")]
[Range(0.1, 100)]
public float MaxLogFileSizeMB
Field Value
Type Description
float

MaxLogFiles

Maximum number of log files to retain across all sessions. When this limit is reached, the oldest file is overwritten rather than creating a new one, implementing a circular file ring. Setting this very low (below 3) risks losing recent history if sessions start faster than old files are reviewed. Setting it very high (above 50) can consume significant disk space equal to MaxLogFiles * MaxLogFileSizeMB megabytes. The recommended range is 3-10 files.

Declaration
[Tooltip("Maximum number of log files retained on disk. When this limit is exceeded, the oldest log files are automatically deleted during startup. Increase this value if you need to keep a longer history of past sessions for debugging.")]
[Range(1, 100)]
public int MaxLogFiles
Field Value
Type Description
int

MinFreeDiskSpaceMB

Minimum free disk space in megabytes that must remain available on the log drive. Before every write the FileLog checks available space; if free space drops below this value, file logging is immediately and permanently disabled for the current session to prevent the disk from being filled. Setting this too low (below 50 MB) risks allowing the log to fill the drive; setting it too high wastes disk capacity that could otherwise be used by the application. The recommended range is 100-500 MB. Use MinFreeDiskSpaceBytes for the byte-precision value.

Declaration
[Tooltip("Minimum amount of free disk space in megabytes that must be available for file logging to continue. If free space drops below this threshold, file logging is paused to prevent filling the disk. Set this to a safe margin above zero.")]
[Range(10, 1000)]
public float MinFreeDiskSpaceMB
Field Value
Type Description
float

Properties

MaxFileSizeBytes

Gets MaxLogFileSizeMB converted to bytes, as required by the internal size-comparison logic in FileLog.

Declaration
public long MaxFileSizeBytes { get; }
Property Value
Type Description
long

The maximum log file size expressed in bytes. Computed as MaxLogFileSizeMB * 1,048,576.

MinFreeDiskSpaceBytes

Gets MinFreeDiskSpaceMB converted to bytes, as required by the internal disk-space guard in FileLog.

Declaration
public long MinFreeDiskSpaceBytes { get; }
Property Value
Type Description
long

The minimum required free disk space expressed in bytes. Computed as MinFreeDiskSpaceMB * 1,048,576.

Extension Methods