added custom log formatting details

dictionary-octopus.txt

@@ -262,6 +262,7 @@ Linq
 Liquibase
 llms
 localport
+longdate
 lstrip
 ltsc
 Lucene
@@ -280,6 +281,7 @@ Metabase
 milli
 minidump
 minifier
+minlevel
 MITM
 Mkto
 Moines
@@ -541,6 +543,7 @@ tfvar
 tfvars
 TFVC
 thepassword
+threadid
 timespan
 tlsv1
 tmpfs

src/pages/docs/support/log-files.md

@@ -61,6 +61,83 @@ The Octopus process will automatically switch to the new logging level as soon a
 Leaving your `minlevel` too low will impact the performance of Octopus Server. We recommend resetting back to the default logging configuration once you have completed your diagnostics session.
 :::
 
+## Customizing log format {#Logfiles-Customizinglogformat}
+
+The format of log entries is controlled by NLog layout variables in the `octopus.server.exe.nlog` file. The default layout is:
+
+```xml
+<variable name="normalLayout" value="${longdate}  ${processid:padding=5}  ${threadid:padding=5} ${uppercase:${level}:padding=5}  ${message}${onexception:${newline}${exception:format=ToString}}"/>
+```
+
+This produces log entries in the format:
+
+```text
+2024-01-15 10:30:45.1234  12345  67890  INFO  Your log message here
+```
+
+The layout components are:
+
+- `${longdate}` - Timestamp in `yyyy-MM-dd HH:mm:ss.ffff` format
+- `${processid}` - The process ID
+- `${threadid}` - The thread ID
+- `${level}` - Log level (Trace, Debug, Info, Warn, Error, Fatal)
+- `${message}` - The log message
+- `${exception}` - Exception details when present
+
+You can customize the layout by modifying the `normalLayout` variable.
+
+### Custom date formats with timezone {#Logfiles-Customdateformats}
+
+The default `${longdate}` renderer does not include timezone information. To include the timezone offset in your timestamps, replace `${longdate}` with a custom `${date}` format:
+
+```xml
+<variable name="normalLayout" value="${date:format=yyyy-MM-dd HH\:mm\:ss.ffff zzz}  ${processid:padding=5}  ${threadid:padding=5} ${uppercase:${level}:padding=5}  ${message}${onexception:${newline}${exception:format=ToString}}"/>
+```
+
+This produces timestamps like:
+
+```text
+2024-01-15 10:30:45.1234 +10:00  12345  67890  INFO  Your log message here
+```
+
+Common date format specifiers:
+
+- `zzz` - UTC offset with hours and minutes (e.g., `+10:00`, `-05:00`)
+- `zz` - UTC offset with hours only (e.g., `+10`, `-05`)
+- `K` - Timezone information in ISO 8601 format
+
+For UTC timestamps instead of local time, use:
+
+```xml
+${date:universalTime=true:format=yyyy-MM-dd HH\:mm\:ss.ffff}Z
+```
+
+:::div{.hint}
+**Note:** Colons in date format strings must be escaped with a backslash (`\:`) because colons are used as parameter delimiters in NLog layout syntax.
+::: For example, to include the logger name:
+
+```xml
+<variable name="normalLayout" value="${longdate} ${uppercase:${level}:padding=5} [${logger:shortName=true}] ${message}${onexception:${newline}${exception:format=ToString}}"/>
+```
+
+For a full list of available layout renderers, see the [NLog documentation](https://nlog-project.org/config/?tab=layout-renderers).
+
+### Preserving custom configuration across upgrades {#Logfiles-Preservingcustomconfiguration}
+
+The default `octopus.server.exe.nlog` file is overwritten when Octopus Server is upgraded. To preserve your customizations:
+
+1. Create a copy of `octopus.server.exe.nlog` in the same directory
+2. Rename the copy to `Octopus.Server.exe.user.nlog`
+3. Make your changes to the `user.nlog` file
+4. Restart Octopus Server
+
+When a `user.nlog` file exists, the server loads it instead of the default configuration. The installer will not overwrite this file during upgrades.
+
+:::div{.warning}
+**Keep your custom config in sync**
+If you use a custom `user.nlog` file, be aware that future Octopus versions may make changes to the default NLog configuration. After upgrading, compare your custom file with the new default to ensure compatibility.
+:::
+
 ## Changing log levels for Halibut {#Logfiles-Changingloglevelshalibut}
 
 To change the logging level for Halibut as logged in the Octopus Server, we follow a similar process as described above with a few changes.