From ff94e1a2129b50887914fa60f084106617059c69 Mon Sep 17 00:00:00 2001
From: Jacek Sieka <jacek@status.im>
Date: Thu, 18 Feb 2021 07:57:41 +0100
Subject: [PATCH] Document log rotation (#2327)

* Document log rotation

* phrasing updates

Co-authored-by: Dustin Brody <tersec@users.noreply.github.com>
---
 docs/the_nimbus_book/src/SUMMARY.md    |  1 +
 docs/the_nimbus_book/src/log-rotate.md | 60 ++++++++++++++++++++++++++
 scripts/rotatelogs-compress.sh         |  9 ++++
 3 files changed, 70 insertions(+)
 create mode 100644 docs/the_nimbus_book/src/log-rotate.md
 create mode 100755 scripts/rotatelogs-compress.sh

diff --git a/docs/the_nimbus_book/src/SUMMARY.md b/docs/the_nimbus_book/src/SUMMARY.md
index 1c21e9ae5..6b2983fb6 100644
--- a/docs/the_nimbus_book/src/SUMMARY.md
+++ b/docs/the_nimbus_book/src/SUMMARY.md
@@ -27,6 +27,7 @@
 - [Recover / generate keys](./more-keys.md)
 - [Perform a voluntary exit](./voluntary-exit.md)
 - [Setup a systemd service](./beacon-node-systemd.md)
+- [Setup log rotation](./log-rotate.md)
 
 # Tutorials
 - [Grafana and Prometheus](./metrics-pretty-pictures.md)
diff --git a/docs/the_nimbus_book/src/log-rotate.md b/docs/the_nimbus_book/src/log-rotate.md
new file mode 100644
index 000000000..b8504a618
--- /dev/null
+++ b/docs/the_nimbus_book/src/log-rotate.md
@@ -0,0 +1,60 @@
+# Log rotation
+
+Nimbus logs are written to the console, and optionally to a file. Using the log file option for a long-running process may lead to difficulties when the file grows large. This is typically solved with a log rotator that will switch which file is witten to as well as compress and remove old logs.
+
+To set up file-based log rotation, an application such as [rotatelogs](https://httpd.apache.org/docs/2.4/programs/rotatelogs.html) is used - `rotatelogs` is available on most servers and can be used with `docker`, `systemd` and manual setups to write rotated logs files.
+
+In particular, when using `systemd` and its accompanying `journald` log daemon, this setup avoids clogging the the system log and keep the Nimbus logs in a separate location.
+
+## Compression
+
+`rotatelogs` works by reading stdin and redirecting it to a file based on a name pattern. Whenever the log is about to be rotated, the application will invoke a shell script with the old and new log files. Our aim is to compress the log file to save space. [repo](https://github.com/status-im/nimbus-eth2/tree/unstable/scripts/rotatelogs-compress.sh) provides a helper script to do so:
+
+```bash
+# Create a rotation script for rotatelogs
+cat << EOF > rotatelogs-compress.sh
+#!/bin/sh
+
+# Helper script for Apache rotatelogs to compress log files on rotation - `$2` contains the old log file name
+
+if [ -f "$2" ]; then
+    # "nice" prevents hogging the CPU with this low-priority task
+    nice gzip -9 "$2"
+fi
+EOF
+
+chmod +x rotatelogs-compress.sh
+```
+
+## Build
+
+Logs in files generally don't benefit from colors - to avoid colors being written to the file, additional flags can be added to the Nimbus [build process](./build.md) - these flags are best saved in a build script to which one can add more options. Future versions of Nimbus will support disabling colors at runtime.
+
+```bash
+
+# Build nimbus with colors disabled
+cat << EOF > build-nbc-text.sh
+#!/bin/bash
+make NIMFLAGS="-d:chronicles_colors=off -d:chronicles_sinks=textlines" nimbus_beacon_node
+EOF
+```
+
+## Run
+
+The final step is to redirect logs to `rotatelogs` using a pipe when starting nimbus:
+
+```bash
+build/nimbus_beacon_node \
+  --network:pyrmont \
+  --web3-url="$WEB3URL" \
+  --data-dir:$DATADIR | rotatelogs -L "$DATADIR/nbc_bn.log" -p "/path/to/rotatelogs-compress.sh" -D -f -c "$DATADIR/log/nbc_bn_%Y%m%d%H%M%S.log" 3600
+```
+
+The options used in this example will:
+
+* `-L nbc_bn.log` - symlink to the latest log file, for use with `tail -F`
+* `-p "/path/to/rotatelogs-compress.sh"` - script to run when rotation is about to happen
+* `-D` - create the `log` directory if needed
+* `-f` - open the log immediately when starting `rotatelogs`
+* `-c "$DATADIR/log/nbc_bn_%Y%m%d%H%M%S.log"` - include timestamp in log filename
+* `3600` - rotate logs every hour (3600 seconds)
diff --git a/scripts/rotatelogs-compress.sh b/scripts/rotatelogs-compress.sh
new file mode 100755
index 000000000..9870ffe6c
--- /dev/null
+++ b/scripts/rotatelogs-compress.sh
@@ -0,0 +1,9 @@
+#!/bin/sh
+
+# Helper script for Apache rotatelogs to compress log files on rotation - `$2` contains the old log file name
+
+if [ -f "$2" ]; then
+    # "nice" prevents hogging the CPU with this low-priority task
+    nice gzip -9 "$2"
+fi
+