32.1 Defining a log

You can define a log on the Logs page, in a definition file, or from code. On the Logs page, New log starts from a blank definition or from a template: web requests, business events, errors and warnings, positions, or background jobs. A definition has these parts:

Part	What it is
Key	The name the application records by, which the files are named after. Letters, digits, `-` and `_`, starting with a letter or digit; at most 64 characters
Name, description	What the Logs page shows
Columns	What an entry holds besides its timestamp: each column's key, name, type and statistics (§32.3)
Record entries, Keep statistics	Two switches. Turn one off for a log that only counts, or one that only records
One file per	Minute, hour, day or month: how the entries are split into files
Keep entries for, At most	The age limit in days and the size limit in MB, applied to whole files; 0 means no limit
Level of statistical detail	How far back the statistics reach (§32.3)
Weeks start on	The first day of a week, for weekly statistics
Also write a text copy, Compress	A tab-separated `.txt` beside each entries file, readable without the database; smaller entries files

The column types are text, whole number, decimal number, date and time, duration, bytes and position (§32.8). A key cannot change later, since the files are named after it; duplicate the log instead. The activity logs' keys are taken: system, query, transaction, action, task, taskbatch and metrics.

Where definitions are kept. A definition is a <key>.json file in one of two folders, like everything the admin UI edits:

SHARED is relatude.settings/logs/, part of the application: kept in source control and deployed with it. A database with a short name (ShortName, §12.1) uses relatude.settings/<short name>/logs/.
THIS SERVER is overrides/logs/ on the database's storage, relatude.data/overrides/logs/ by default. The Logs page, CustomLogs.Create and CustomLogs.Update save here. A definition here replaces the SHARED one with the same key. Deleting a SHARED log writes a marker here that removes it on this installation.

On the Logs page, each log is tagged shared or this server. Move to shared moves definitions from THIS SERVER into SHARED, or discards them. Move them in development and commit the folder: on a deployed server, SHARED is the deployed copy, and the next deployment replaces it (§12.2).

A definition file you write by hand, or copy from another application, into either folder is picked up when the database opens, or with Reload from disk on the Logs page.

The definition file. The Definition view of a log shows its file, and you can edit it there as text:

{
  "Key": "requests",
  "Name": "Web requests",
  "Description": "The requests the site answers.",
  "Properties": {
    "path":     { "Name": "Path", "DataType": "String", "Statistics": [ { "StatisticsType": "UniqueCountEstimate", "Resolution": 3 } ] },
    "status":   { "Name": "Status", "DataType": "Integer", "Statistics": [ { "StatisticsType": "UniqueCountWithValues", "Resolution": 3 } ] },
    "duration": { "Name": "Duration (ms)", "DataType": "Double", "Statistics": [ { "StatisticsType": "CountSumAvgMinMax", "Resolution": 3 } ] },
    "user":     { "Name": "User", "DataType": "String", "Statistics": [ { "StatisticsType": "UniqueCountEstimate", "Resolution": 3 } ] },
    "position": { "Name": "Position", "DataType": "GeoCoordinate", "Statistics": [ { "StatisticsType": "GeoHeatmap", "Resolution": 3 } ] }
  },
  "FileInterval": "Hour",
  "EnableLog": true,
  "EnableStatistics": true,
  "EnableLogTextFormat": false,
  "ResolutionRowStats": 3,
  "FirstDayOfWeek": "Monday",
  "MaxAgeOfLogFilesInDays": 14,
  "MaxTotalSizeOfLogFilesInMb": 100,
  "Compressed": false
}

Comments, trailing commas, names in any case, and enums by name or number are accepted. A file that is not a valid log is left alone and listed on the Logs page with the error, so you can fix it there or delete it.

From code, the same definition is a LogSettings:

using Relatude.DB.IO;        // FileInterval
using Relatude.DB.Logging;   // LogSettings, LogProperty, LogDataType, StatisticsType

if (!db.CustomLogs.HasLog("requests")) {
    var requests = new LogSettings {
        Key = "requests",
        Name = "Web requests",
        FileInterval = FileInterval.Hour,
        MaxAgeOfLogFilesInDays = 14,
        ResolutionRowStats = 3,
    };
    requests.Properties.Add("path", new LogProperty {
        Name = "Path", DataType = LogDataType.String,
        Statistics = [new(StatisticsType.UniqueCountEstimate)],
    });
    requests.Properties.Add("duration", new LogProperty {
        Name = "Duration (ms)", DataType = LogDataType.Double,
        Statistics = [new(StatisticsType.CountSumAvgMinMax)],
    });
    db.CustomLogs.Create(requests);   // saved on THIS SERVER; the log starts at once
}

Create throws for a key that is taken or invalid, and CheckNewKey tells you why beforehand. GetDefinition and GetDefinitions return copies, so changing one has no effect until you pass it to Update (§32.6). LogSettings also reads and writes the JSON: ToJson, FromJson, SaveToFile and LoadFromFile.