gitlab svlogd runsv 基于Rotated Log的日志统计

小结：

1、

日志轮询

log roate 日志文件自动转存和重命名

2、

rotated log独立于其他模块，可以以静态库或者动态库的形式支持二次开发；

3、

[root@d1 ~]# gitlab-ctl start
ok: run: gitaly: (pid 4356) 1s
ok: run: gitlab-monitor: (pid 4367) 0s
ok: run: gitlab-workhorse: (pid 4379) 1s
ok: run: logrotate: (pid 4388) 0s
ok: run: nginx: (pid 4394) 1s
ok: run: node-exporter: (pid 4400) 0s
ok: run: postgres-exporter: (pid 4480) 0s
ok: run: postgresql: (pid 4485) 1s
ok: run: prometheus: (pid 4493) 0s
ok: run: redis: (pid 4503) 1s
ok: run: redis-exporter: (pid 4512) 0s
ok: run: sidekiq: (pid 4517) 0s
ok: run: unicorn: (pid 4526) 1s
[root@d1 ~]# ps -aux | grep nginx
root 690 0.0 0.0 4232 340 ? Ss 18:08 0:00 runsv nginx
root 771 0.0 0.0 4376 344 ? S 18:08 0:00 svlogd -tt /var/log/gitlab/nginx
root 4394 0.0 0.0 37936 3112 ? Ss 18:14 0:00 nginx: master process /opt/gitlab/embedded/sbin/nginx -p /var/opt/gitlab/nginx
gitlab-+ 4395 0.0 0.0 44272 5544 ? S 18:14 0:00 nginx: worker process
gitlab-+ 4396 0.0 0.0 44272 5544 ? S 18:14 0:00 nginx: worker process
gitlab-+ 4397 0.0 0.0 40228 1592 ? S 18:14 0:00 nginx: cache manager process
gitlab-+ 4398 0.0 0.0 40228 1592 ? S 18:14 0:00 nginx: cache loader process
root 4554 0.0 0.0 112728 964 pts/0 S+ 18:14 0:00 grep --color=auto nginx
[root@d1 ~]#

svlogd(8) manual page http://smarden.org/runit/svlogd.8.html

[root@d1 ~]# ll -as /var/log/gitlab/nginx/
总用量 508
12 drwxr-x---. 2 root gitlab-www 8192 1月 7 00:18 .
4 drwxr-xr-x. 18 git root 4096 5月 21 2018 ..
4 -rwxr--r-- 1 root root 122 6月 15 2018 @400000005b23610d322bfc8c.s
4 -rwxr--r-- 1 root root 109 7月 18 08:52 @400000005b4e8f4f2b93346c.s
0 -rw-r--r--. 1 root root 0 1月 7 00:18 access.log
4 -rw-r--r-- 1 root root 20 12月 28 00:17 access.log.10.gz
4 -rw-r--r-- 1 root root 20 12月 27 00:17 access.log.11.gz
4 -rw-r--r-- 1 root root 20 12月 26 00:17 access.log.12.gz
4 -rw-r--r-- 1 root root 20 12月 25 10:17 access.log.13.gz
4 -rw-r--r-- 1 root root 20 12月 13 00:52 access.log.14.gz
4 -rw-r--r-- 1 root root 20 12月 12 00:51 access.log.15.gz
4 -rw-r--r-- 1 root root 20 12月 11 00:51 access.log.16.gz
4 -rw-r--r-- 1 root root 20 12月 10 08:51 access.log.17.gz
4 -rw-r--r-- 1 root root 20 12月 9 00:35 access.log.18.gz
4 -rw-r--r-- 1 root root 20 12月 8 00:35 access.log.19.gz
4 -rw-r--r-- 1 root root 20 1月 6 00:18 access.log.1.gz
4 -rw-r--r-- 1 root root 20 12月 7 00:35 access.log.20.gz
4 -rw-r--r-- 1 root root 20 12月 6 00:35 access.log.21.gz
4 -rw-r--r-- 1 root root 20 12月 5 00:35 access.log.22.gz
4 -rw-r--r-- 1 root root 20 12月 4 00:35 access.log.23.gz
4 -rw-r--r-- 1 root root 20 12月 3 00:35 access.log.24.gz
4 -rw-r--r-- 1 root root 20 12月 2 00:35 access.log.25.gz
4 -rw-r--r-- 1 root root 20 12月 1 00:35 access.log.26.gz
4 -rw-r--r-- 1 root root 20 11月 30 00:35 access.log.27.gz
4 -rw-r--r-- 1 root root 20 11月 29 00:35 access.log.28.gz
4 -rw-r--r-- 1 root root 20 11月 28 00:35 access.log.29.gz
4 -rw-r--r-- 1 root root 20 1月 5 00:18 access.log.2.gz
4 -rw-r--r-- 1 root root 20 11月 27 00:35 access.log.30.gz
4 -rw-r--r-- 1 root root 20 1月 4 00:18 access.log.3.gz
4 -rw-r--r-- 1 root root 20 1月 3 00:18 access.log.4.gz
4 -rw-r--r-- 1 root root 20 1月 2 00:17 access.log.5.gz
4 -rw-r--r-- 1 root root 20 1月 1 00:17 access.log.6.gz
4 -rw-r--r-- 1 root root 20 12月 31 00:17 access.log.7.gz
4 -rw-r--r-- 1 root root 20 12月 30 00:17 access.log.8.gz
4 -rw-r--r-- 1 root root 20 12月 29 00:17 access.log.9.gz
4 -rw-r--r--. 1 root root 30 5月 21 2018 config
0 -rw-r--r-- 1 root root 0 7月 18 08:52 current
0 -rw-r--r--. 1 root root 0 1月 7 00:18 error.log
4 -rw-r--r-- 1 root root 20 12月 28 00:17 error.log.10.gz
4 -rw-r--r-- 1 root root 20 12月 27 00:17 error.log.11.gz
4 -rw-r--r-- 1 root root 20 12月 26 00:17 error.log.12.gz
4 -rw-r--r-- 1 root root 20 12月 25 10:17 error.log.13.gz
4 -rw-r--r-- 1 root root 20 12月 13 00:52 error.log.14.gz
4 -rw-r--r-- 1 root root 20 12月 12 00:51 error.log.15.gz
4 -rw-r--r-- 1 root root 20 12月 11 00:51 error.log.16.gz
4 -rw-r--r-- 1 root root 20 12月 10 08:51 error.log.17.gz
4 -rw-r--r-- 1 root root 20 12月 9 00:35 error.log.18.gz
4 -rw-r--r-- 1 root root 20 12月 8 00:35 error.log.19.gz
4 -rw-r--r-- 1 root root 20 1月 6 00:18 error.log.1.gz
4 -rw-r--r-- 1 root root 20 12月 7 00:35 error.log.20.gz
4 -rw-r--r-- 1 root root 20 12月 6 00:35 error.log.21.gz
4 -rw-r--r-- 1 root root 20 12月 5 00:35 error.log.22.gz
4 -rw-r--r-- 1 root root 20 12月 4 00:35 error.log.23.gz
4 -rw-r--r-- 1 root root 20 12月 3 00:35 error.log.24.gz
4 -rw-r--r-- 1 root root 20 12月 2 00:35 error.log.25.gz
4 -rw-r--r-- 1 root root 20 12月 1 00:35 error.log.26.gz
4 -rw-r--r-- 1 root root 20 11月 30 00:35 error.log.27.gz
4 -rw-r--r-- 1 root root 20 11月 29 00:35 error.log.28.gz
4 -rw-r--r-- 1 root root 20 11月 28 00:35 error.log.29.gz
4 -rw-r--r-- 1 root root 20 1月 5 00:18 error.log.2.gz
4 -rw-r--r-- 1 root root 20 11月 27 00:35 error.log.30.gz
4 -rw-r--r-- 1 root root 20 1月 4 00:18 error.log.3.gz
4 -rw-r--r-- 1 root root 20 1月 3 00:18 error.log.4.gz
4 -rw-r--r-- 1 root root 20 1月 2 00:17 error.log.5.gz
4 -rw-r--r-- 1 root root 20 1月 1 00:17 error.log.6.gz
4 -rw-r--r-- 1 root root 20 12月 31 00:17 error.log.7.gz
4 -rw-r--r-- 1 root root 20 12月 30 00:17 error.log.8.gz
4 -rw-r--r-- 1 root root 20 12月 29 00:17 error.log.9.gz
0 -rw-r--r--. 1 root root 0 1月 7 00:18 gitlab_access.log
4 -rw-r--r-- 1 root root 20 12月 28 00:17 gitlab_access.log.10.gz
4 -rw-r--r-- 1 root root 20 12月 27 00:17 gitlab_access.log.11.gz
4 -rw-r--r-- 1 root root 20 12月 26 00:17 gitlab_access.log.12.gz
4 -rw-r--r-- 1 root root 20 12月 25 10:17 gitlab_access.log.13.gz
4 -rw-r--r-- 1 root root 20 12月 13 00:52 gitlab_access.log.14.gz
4 -rw-r--r-- 1 root root 20 12月 12 00:51 gitlab_access.log.15.gz
4 -rw-r--r-- 1 root root 20 12月 11 00:51 gitlab_access.log.16.gz
4 -rw-r--r-- 1 root root 20 12月 10 08:51 gitlab_access.log.17.gz
4 -rw-r--r-- 1 root root 20 12月 9 00:35 gitlab_access.log.18.gz
4 -rw-r--r-- 1 root root 20 12月 8 00:35 gitlab_access.log.19.gz
4 -rw-r--r-- 1 root root 20 1月 6 00:18 gitlab_access.log.1.gz
4 -rw-r--r-- 1 root root 20 12月 7 00:35 gitlab_access.log.20.gz
4 -rw-r--r-- 1 root root 20 12月 6 00:35 gitlab_access.log.21.gz
4 -rw-r--r-- 1 root root 20 12月 5 00:35 gitlab_access.log.22.gz
4 -rw-r--r-- 1 root root 20 12月 4 00:35 gitlab_access.log.23.gz
4 -rw-r--r-- 1 root root 20 12月 3 00:35 gitlab_access.log.24.gz
4 -rw-r--r-- 1 root root 20 12月 2 00:35 gitlab_access.log.25.gz
4 -rw-r--r-- 1 root root 20 12月 1 00:35 gitlab_access.log.26.gz
4 -rw-r--r-- 1 root root 20 11月 30 00:35 gitlab_access.log.27.gz
4 -rw-r--r-- 1 root root 20 11月 29 00:35 gitlab_access.log.28.gz
4 -rw-r--r-- 1 root root 207 11月 28 14:40 gitlab_access.log.29.gz
4 -rw-r--r-- 1 root root 20 1月 5 00:18 gitlab_access.log.2.gz
4 -rw-r--r-- 1 root root 207 11月 27 09:58 gitlab_access.log.30.gz
4 -rw-r--r-- 1 root root 20 1月 4 00:18 gitlab_access.log.3.gz
4 -rw-r--r-- 1 root root 20 1月 3 00:18 gitlab_access.log.4.gz
4 -rw-r--r-- 1 root root 20 1月 2 00:17 gitlab_access.log.5.gz
4 -rw-r--r-- 1 root root 20 1月 1 00:17 gitlab_access.log.6.gz
4 -rw-r--r-- 1 root root 20 12月 31 00:17 gitlab_access.log.7.gz
4 -rw-r--r-- 1 root root 20 12月 30 00:17 gitlab_access.log.8.gz
4 -rw-r--r-- 1 root root 20 12月 29 00:17 gitlab_access.log.9.gz
0 -rw-r--r--. 1 root root 0 1月 7 00:18 gitlab_error.log
4 -rw-r--r-- 1 root root 20 12月 28 00:17 gitlab_error.log.10.gz
4 -rw-r--r-- 1 root root 20 12月 27 00:17 gitlab_error.log.11.gz
4 -rw-r--r-- 1 root root 20 12月 26 00:17 gitlab_error.log.12.gz
4 -rw-r--r-- 1 root root 20 12月 25 10:17 gitlab_error.log.13.gz
4 -rw-r--r-- 1 root root 20 12月 13 00:52 gitlab_error.log.14.gz
4 -rw-r--r-- 1 root root 20 12月 12 00:51 gitlab_error.log.15.gz
4 -rw-r--r-- 1 root root 20 12月 11 00:51 gitlab_error.log.16.gz
4 -rw-r--r-- 1 root root 20 12月 10 08:51 gitlab_error.log.17.gz
4 -rw-r--r-- 1 root root 20 12月 9 00:35 gitlab_error.log.18.gz
4 -rw-r--r-- 1 root root 20 12月 8 00:35 gitlab_error.log.19.gz
4 -rw-r--r-- 1 root root 20 1月 6 00:18 gitlab_error.log.1.gz
4 -rw-r--r-- 1 root root 20 12月 7 00:35 gitlab_error.log.20.gz
4 -rw-r--r-- 1 root root 20 12月 6 00:35 gitlab_error.log.21.gz
4 -rw-r--r-- 1 root root 20 12月 5 00:35 gitlab_error.log.22.gz
4 -rw-r--r-- 1 root root 20 12月 4 00:35 gitlab_error.log.23.gz
4 -rw-r--r-- 1 root root 20 12月 3 00:35 gitlab_error.log.24.gz
4 -rw-r--r-- 1 root root 20 12月 2 00:35 gitlab_error.log.25.gz
4 -rw-r--r-- 1 root root 20 12月 1 00:35 gitlab_error.log.26.gz
4 -rw-r--r-- 1 root root 20 11月 30 00:35 gitlab_error.log.27.gz
4 -rw-r--r-- 1 root root 20 11月 29 00:35 gitlab_error.log.28.gz
4 -rw-r--r-- 1 root root 20 11月 28 00:35 gitlab_error.log.29.gz
4 -rw-r--r-- 1 root root 20 1月 5 00:18 gitlab_error.log.2.gz
4 -rw-r--r-- 1 root root 20 11月 27 00:35 gitlab_error.log.30.gz
4 -rw-r--r-- 1 root root 20 1月 4 00:18 gitlab_error.log.3.gz
4 -rw-r--r-- 1 root root 20 1月 3 00:18 gitlab_error.log.4.gz
4 -rw-r--r-- 1 root root 20 1月 2 00:17 gitlab_error.log.5.gz
4 -rw-r--r-- 1 root root 20 1月 1 00:17 gitlab_error.log.6.gz
4 -rw-r--r-- 1 root root 20 12月 31 00:17 gitlab_error.log.7.gz
4 -rw-r--r-- 1 root root 20 12月 30 00:17 gitlab_error.log.8.gz
4 -rw-r--r-- 1 root root 20 12月 29 00:17 gitlab_error.log.9.gz
0 -rw-------. 1 root root 0 5月 21 2018 lock
0 -rw-r--r-- 1 root root 0 7月 18 08:52 state
[root@d1 ~]#

基于Rotated Log的日志统计-存储之厨-51CTO博客 http://blog.51cto.com/xiamachao/1769244

Rotated Log 简介

    Rotated log是linux支持日志文件自动转储和重命名的机制。当需要限制每个日志文件大小，或者需要周期地统计并记录日志的时候，就是rotated log机制大显身手的好时机。

Rotated Log的使用和配置

    Rotated log的配置文件都是在/etc/logrotate.d里面，它本身依赖于logrotate命令的执行。logrotate自身作为一个日常的cron job，正常情况下它一天只会执行一次,通过下面的命令可以看到它是如何作为一个cron job的：

[root@localhost cron.daily]# pwd

/etc/cron.daily

[root@localhost cron.daily]# cat logrotate

#!/bin/sh

/usr/sbin/logrotate /etc/logrotate.conf

EXITVALUE=$?

if [ $EXITVALUE != 0 ]; then

/usr/bin/logger -t logrotate "ALERT exited abnormally with [$EXITVALUE]"

fi

exit 0

    除非rotate是根据日志文件大小进行，或者强制执行转储命令logrotate -f。配置文件里指定了需要rotate的日志文件的名字，以及rotate触发的机制、处理的策略，以/etc/logrotate.d/syslogd为例:

[root@localhost logrotate.d]# cat syslog

/var/log/cron

/var/log/maillog

/var/log/messages

/var/log/secure

/var/log/spooler

{

sharedscripts

postrotate

/bin/kill -HUP `cat /var/run/syslogd.pid 2> /dev/null` 2> /dev/null || true

endscript

}

 从第一到第五行指定了有待rotate的日志文件的名字,这里列出了五个日志文件需要保存。sharedscripts表示postrotate脚本命令/bin/kill -HUP `cat /var/run/syslogd.pid 2> /dev/null` 2> /dev/null || true只会执行一次，而不是在每个上述的日志文件rotate之后都执行一次。

    Rotated Log相关的程序设计

根据本人最近使用logrotate的经验和教训，重点需要考虑和引起注意的要素有：

1.考虑到保证每一条记录的完整性，建议根据时间而非容量进行自动回转。

2.考虑到查询的方便和log rotated的命名规则，需要设计好合适的数据结构来统计每一个日志文件的记录。还是以上面的mailog日志文件为例，如果某个时刻系统只有一个mailog，第一次rotate之后之前的mailog会重新命名为mailog.1，而mailog里面的内容会被清空；第二次rotate之后，之前的maillog.1会被重命名为mailog.2，而之前的maillog会重新命名为mailog.1，而mailog里面的内容会被情况，后续的rotate以此类推。因此，需要一个设计良好的数据结构和方法来表示文件名称和真实文件。

3.如果存在多个用户同时访问日志文件的情况，为了保证日志总数和记录的完整和一致，需要在访问文件前加锁。

4.进阶：Rotated log本身和其他模块和代码没有联系，其他应用往往需要从rotated log里存取数据，为此可以开发出和具体业务无关的且便于扩展的rotated log API，以静态库或者动态库的形式支持二次开发。

系统运维|Linux日志文件总管——logrotate https://linux.cn/article-4126-1.html

svlogd(8) manual page http://smarden.org/runit/svlogd.8.html

svlogd - runit’s service logging daemon

Synopsis

svlogd [-tttv] [-r c] [-R xyz] [-l len] [-b buflen] logs

Description

logs consists of one or more arguments, each specifying a directory.

svlogd continuously reads log data from its standard input, optionally filters log messages, and writes the data to one or more automatically rotated logs.

Recent log files can automatically be processed by an arbitrary processor program when they are rotated, and svlogd can be told to alert selected log messages to standard error, and through udp.

svlogd runs until it sees end-of-file on standard input or is sent a TERM signal, see below.

Log Directory

A log directory log contains some number of old log files, and the current log file current. Old log files have a file name starting with @ followed by a precise timestamp (see the daemontools’ tai64n program), indicating when currentwas rotated  and renamed to this file.

A log directory additionally contains the lock file lock, maybe state and newstate, and optionally the file config. svlogd creates necessary files if they don’t exist.

If svlogd has trouble opening a log directory, it prints a warning, and ignores this log directory. If svlogd is unable to open all log directories given at the command line, it exits with an error. This can happen on start-up or after receiving a HUP signal.

Log File Rotation

svlogd appends selected log messages to the current log file. If current has size bytes or more (or there is a new-line within the last len of size bytes), or is older than a specified amount of time, current is rotated:

svlogd closes current, changes permission of current to 0755, renames current to @timestamp.s, and starts with a new empty current. If svlogd sees num or more old log files in the log directory, it removes the oldest one. Note that this doesn’t decrease the number of log files if there are already more than num log files, this must be done manually, e.g. for keeping 10 log files:

ls -1 @* |sort |sed -ne ’10,$p’ |xargs rm

Processor

If svlogd is told to process recent log files, it saves current to @timestamp.u, feeds @timestamp.u through ‘‘sh -c "processor"’’ and writes the output to @timestamp.t. If the processor finishes successfully, @timestamp.t is renamed to @timestamp.s, and @timestamp.u is deleted; otherwise @timestamp.t is deleted and the processor is started again. svlogd also saves any output that the processor writes to file descriptor 5, and makes that output available on file descriptor 4 when running processor on the next log file rotation.

A processor is run in the background. If svlogd sees a previously started processor still running when trying to start a new one for the same log, it blocks until the currently running processor has finished successfully. Only the HUP signal works in that situation. Note that this may block any program feeding its log data to svlogd.

Config

On startup, and after receiving a HUP signal, svlogd checks for each log directory log if the configuration file log/config exists, and if so, reads the file line by line and adjusts configuration for log as follows:

If the line is empty, or starts with a ‘‘#’’, it is ignored. A line of the form

ssize

sets the maximum file size of current when svlogd should rotate the current log file to size bytes. Default is 1000000. If size is zero, svlogd doesn’t rotate log files. You should set size to at least (2 * len).

nnum

sets the number of old log files svlogd should maintain to num. If svlogd sees more that num old log files in log after log file rotation, it deletes the oldest one. Default is 10. If num is zero, svlogd doesn’t remove old log files.

Nmin

sets the minimum number of old log files svlogd should maintain to min. min must be less than num. If min is set, and svlogd cannot write to current because the filesystem is full, and it sees more than min old log files, it deletes the oldest one.

ttimeout

sets the maximum age of the current log file when svlogd should rotate the current log file to timeout seconds. If current is timeout seconds old, and is not empty, svlogd forces log file rotation.

!processor

tells svlogd to feed each recent log file through processor (see above) on log file rotation. By default log files are not processed.

ua.b.c.d[:port]

tells svlogd to transmit the first len characters of selected log messages to the IP address a.b.c.d, port number port. If port isn’t set, the default port for syslog is used (514). len can be set through the -l option, see below. If svlogdhas trouble sending udp packets, it writes error messages to the log directory. Attention: logging through udp is unreliable,  and should be used in private networks only.

Ua.b.c.d[:port]

is the same as the u line above, but the log messages are no longer written to the log directory, but transmitted through udp only. Error messages from svlogd concerning sending udp packages still go to the log directory.

pprefix

tells svlogd to prefix each line to be written to the log directory, to standard error, or through UDP, with prefix.

If a line starts with a -, +, e, or E, svlogd matches the first len characters of each log message against pattern and acts accordingly:

-pattern

the log message is deselected.

+pattern

the log message is selected.

epattern

the log message is selected to be printed to standard error.

Epattern

the log message is deselected to be printed to standard error.

Initially each line is selected to be written to log/current. Deselected log messages are discarded from log. Initially each line is deselected to be written to standard err. Log messages selected for standard error are written to standard error.

Pattern Matching

svlogd matches a log message against the string pattern as follows:

pattern is applied to the log message one character by one, starting with the first. A character not a star (‘‘*’’) and not a plus (‘‘+’’) matches itself. A plus matches the next character in pattern in the log message one or more times. A star before the end of pattern matches any string in the log message that does not include the next character in pattern. A star at the end of pattern matches any string.

Timestamps optionally added by svlogd are not considered part of the log message.

An svlogd pattern is not a regular expression. For example consider a log message like this

2005-12-18_09:13:50.97618 tcpsvd: info: pid 1977 from 10.4.1.14

The following pattern doesn’t match

-*pid*

because the first star matches up to the first p in tcpsvd, and then the match fails because i is not s. To match this log message, you can use a pattern like this instead

-*: *: pid *

Options

-t

timestamp. Prefix each selected line with a precise timestamp (see the daemontools’ tai64n program) when writing to log or to standard error.

-tt

timestamp. Prefix each selected line with a human readable, sortable UTC timestamp of the form YYYY-MM-DD_HH:MM:SS.xxxxx when writing to log or to standard error.

-ttt

timestamp. Prefix each selected line with a human readable, sortable UTC timestamp of the form YYYY-MM-DDTHH:MM:SS.xxxxx when writing to log or to standard error.

-r c

replace. c must be a single character. Replace non-printable characters in log messages with c. Characters are replaced before pattern matching is applied.

-R xyz

replace charset. Additionally to non-printable characters, replace all characters found in xyz with c (default ‘‘_’’).

-l len

line length. Pattern matching applies to the first len characters of a log message only. Default is 1000.

-b buflen

buffer size. Set the size of the buffer svlogd uses when reading from standard input and writing to logs to buflen. Default is 1024. buflen must be greater than len. For svlogd instances that process a lot of data in short time, the buffer size should be increased to improve performance.

-v

verbose. Print verbose messages to standard error.

Signals

If svlogd is sent a HUP signal, it closes and reopens all logs, and updates their configuration according to log/config. If svlogd has trouble opening a log directory, it prints a warning, and discards this log directory. If svlogd is unable to open all log directories given at the command line, it exits with an error.

If svlogd is sent a TERM signal, or if it sees end-of-file on standard input, it stops reading standard input, processes the data in the buffer, waits for all processor subprocesses to finish if any, and exits 0 as soon as possible.

If svlogd is sent an ALRM signal, it forces log file rotation for all logs with a non empty current log file.

See Also

sv(8), runsv(8), chpst(8), runit(8), runit-init(8), runsvdir(8), runsvchdir(8)

http://smarden.org/runit/

 

runsv(8) manual page http://smarden.org/runit/runsv.8.html

runsv - starts and monitors a service and optionally an appendant log service

Synopsis

runsv service

Description

service must be a directory.

runsv switches to the directory service and starts ./run. If ./run exits and ./finish exists, runsv starts ./finish. If ./finish doesn’t exist or ./finish exits, runsv restarts ./run.

If ./run or ./finish exit immediately, runsv waits a second before starting ./finish or restarting ./run.

Two arguments are given to ./finish. The first one is ./run’s exit code, or -1 if ./run didn’t exit normally. The second one is the least significant byte of the exit status as determined by waitpid(2); for instance it is 0 if ./run exited normally, and the signal number if ./run was terminated by a signal. If runsv cannot start ./run for some reason, the exit code is 111 and the status is 0.

If the file service/down exists, runsv does not start ./run immediately. The control interface (see below) can be used to start the service and to give other commands to runsv.

If the directory service/log exists, runsv creates a pipe, redirects service/run’s and service/finish’s standard output to the pipe, switches to the directory service/log and starts ./run (and ./finish) exactly as described above for the servicedirectory. The standard input of the log service is redirected  to read from the pipe.

runsv maintains status information in a binary format (compatible to the daemontools’ supervise program) in service/supervise/status and service/log/supervise/status, and in a human-readable format in service/supervise/stat,service/log/supervise/stat, service/supervise/pid, service/log/supervise/pid.

Control

The named pipes service/supervise/control, and (optionally) service/log/supervise/control are provided to give commands to runsv. You can use sv(8) to control the service or just write one of the following characters to the named pipe:

u

Up. If the service is not running, start it. If the service stops, restart it.

d

Down. If the service is running, send it a TERM signal, and then a CONT signal. If ./run exits, start ./finish if it exists. After it stops, do not restart service.

o

Once. If the service is not running, start it. Do not restart it if it stops.

p

Pause. If the service is running, send it a STOP signal.

c

Continue. If the service is running, send it a CONT signal.

h

Hangup. If the service is running, send it a HUP signal.

a

Alarm. If the service is running, send it a ALRM signal.

i

Interrupt. If the service is running, send it a INT signal.

q

Quit. If the service is running, send it a QUIT signal.

1

User-defined 1. If the service is running, send it a USR1 signal.

2

User-defined 2. If the service is running, send it a USR2 signal.

t

Terminate. If the service is running, send it a TERM signal.

k

Kill. If the service is running, send it a KILL signal.

x

Exit. If the service is running, send it a TERM signal, and then a CONT signal. Do not restart the service. If the service is down, and no log service exists, runsv exits. If the service is down and a log service exists, runsv closes the standard input of the log service, and waits for it to terminate. If the log service is down, runsv exits. This command is ignored if it is given to service/log/supervise/control.

Example: to send a TERM signal to the socklog-unix service, either do # sv term /service/socklog-unix
or
# printf t >/service/socklog-unix/supervise/control

printf(1) usually blocks if no runsv process is running in the service directory.

Customize Control

For each control character c sent to the control pipe, runsv first checks if service/control/c exists and is executable. If so, it starts service/control/c and waits for it to terminate, before interpreting the command. If the program exits with return code 0, runsv refrains from sending the service the corresponding signal. The command o is always considered as command u. On command d first service/control/t is checked, and then service/control/d. On command x first service/control/t is checked, and then service/control/x. The control of the optional log service cannot be customized.

Signals

If runsv receives a TERM signal, it acts as if the character x was written to the control pipe.

Exit Codes

runsv exits 111 on an error on startup or if another runsv is running in service.

runsv exits 0 if it was told to exit.

See Also

sv(8), chpst(8), svlogd(8), runit(8), runit-init(8), runsvdir(8), runsvchdir(8), utmpset(8)

http://smarden.org/runit/