From 7ced5e13f4f6d6c1017c48affb581a5490320ce7 Mon Sep 17 00:00:00 2001 From: Ben Pearce Date: Tue, 27 Jan 2026 13:45:17 +1000 Subject: [PATCH 1/3] added custom log formatting details --- src/pages/docs/support/log-files.md | 75 +++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/src/pages/docs/support/log-files.md b/src/pages/docs/support/log-files.md index 4c4e74353c..594bc647e2 100644 --- a/src/pages/docs/support/log-files.md +++ b/src/pages/docs/support/log-files.md @@ -61,6 +61,81 @@ 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 + +``` + +This produces log entries in the format: + +``` +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 + +``` + +This produces timestamps like: + +``` +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 + +``` + +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. From 9b3a5a4a6253dc1c8f24174e047dc3b73c140ec8 Mon Sep 17 00:00:00 2001 From: Ben Pearce Date: Tue, 27 Jan 2026 13:51:21 +1000 Subject: [PATCH 2/3] linting fixes --- src/pages/docs/support/log-files.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/support/log-files.md b/src/pages/docs/support/log-files.md index 594bc647e2..c22df88445 100644 --- a/src/pages/docs/support/log-files.md +++ b/src/pages/docs/support/log-files.md @@ -71,11 +71,12 @@ The format of log entries is controlled by NLog layout variables in the `octopus 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 @@ -95,11 +96,12 @@ The default `${longdate}` renderer does not include timezone information. To inc 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 From 14b40e7937d18221ed285f126278f5b2938257a8 Mon Sep 17 00:00:00 2001 From: Ben Pearce Date: Tue, 27 Jan 2026 13:55:32 +1000 Subject: [PATCH 3/3] spelling --- dictionary-octopus.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/dictionary-octopus.txt b/dictionary-octopus.txt index 8c66ccce5b..9e3edfe542 100644 --- a/dictionary-octopus.txt +++ b/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