I am using a centralized logger application (Seq, Splunk or PaperTrail) at my company. Octopus Deploy writes all its logs to files hosted on the server. Anytime something goes wrong I have to RDP into that VM and dig through the log files. It would be nice to be able to write to that centralized logger I already have running. Is it possible to configure Octopus Deploy to do that?
Yes. With a warning.
Configuring Octopus Deploy
First, let’s go through how to configure Octopus Deploy. Octopus Deploy uses nlog as its logging engine. Octopus Deploy also uses an .nlog file to define the logging configuration. That works out great for us, as it would be much, much harder if it was defining the logging configuration in code.
Now that we know that it uses nlog, we need to find the file Octopus.Server.exe.nlog. That file is typically located in C:\Program Files\Octopus Deploy\Octopus
In my case, I want to log to PaperTrail. Following the documentation written by PaperTrail, I will need to add a assembly reference to NLog.Targets.Syslog, a new target, and a new rule.
Before modifying the Octopus.Server.exe.nlog file I need to download NLog.Targets.Syslog from NuGet. That package also has a dependency to System.Runtime.InteropServices.RuntimeInformation. Those packages can be downloaded by clicking the download package link on the right.
After the packages have been downloaded, I’ll extract them using 7-zip. A NuGet package is nothing more than a glorified zip file with additional metadata. Once the packages have been extracted you will need to grab the .dlls from the highest numbered .NET Framework folder. For example, NLog.Targets.Syslog is written for .NET Framework 4.5.2, so the folder to choose would be net452.
I like to copy the .dlls to a file share so I can get to them easier on the Octopus Server.
Then I will RDP into the server hosting Octopus and copy the .dlls NLog.Targets.Syslog and System.Runtime.InteropsServices.RuntimeInformation from that folder on the file share to C:\Program Files\Octopus Deploy\Octopus.
Now I am ready to update Octopus.Server.exe.nlog. To do this I will open up notepad++ as an admin and add the following entries per the documentation from PaperTrail.
A quick restart of the Octopus Server and I can see I am now logging to PaperTrail!
The Warning
Here be dragons. The information provided above is provided as-is without any support. There are a lot of variables in configuring this.
Accidentally change the wrong entry in the nlog file which stopped Octopus Deploy from starting
I did this when writing this article. I was copying in an older nlog file from early 2019. That file didn’t have the correct logging format specified. Octopus Deploy runs a check on logs when it starts up. If it encounters a logging format it isn’t expecting it will stop the application.
Reference an NLog extension with a dependency on a higher version of NLog than what Octopus Deploy is using will prevent Octopus Deploy from starting
I ran into this when I originally did this a year ago. NLog.Targets.SysLog requires NLog 4.5.4. For a while Octopus Deploy was using a version of NLog below 4.x. Look at the version of NLog your Octopus Deploy instance is using.
The Octopus.Server.exe.nlog file will be reset to default settings during an upgrade or repair
This is a double-edged sword. A reset on repair / upgrade is great when something isn’t working and Octopus won’t start because of a bad file. But that also means you need to modify this file after each upgrade. You can automate that, but it is one more thing to worry about.
Use Repair or Reinstall to get back to a working state
If you are unable to start your Octopus Deploy server then either uninstall/reinstall Octopus Deploy or run the MSI repair process. Your actual Octopus Deploy configuration isn’t stored in C:\Program Files\Octopus Deploy\Octopus. It is stored either in the registry or in C:\ProgramData.
Alerting
Not having to RDP into Octopus Deploy is great. An additional benefit is most tooling provides some sort of alerting. Chances are you have configured alerts for other software you monitor. Now you can leverage the same tooling with Octopus. For example, I configured a couple of alerts, one to watch for performance and another to watch for unauthorized access.
Conclusion
There is risk associated with doing this. Personally, I think the reward is worth the risk. You can mitigate these risks by:
- Automating the Octopus upgrade process and include steps to update the nlog file
- Test the upgrade on test instance of Octopus Deploy.
You can see this in action in an older Ask Octopus Video.