Syslog configuration ==================== `syslog <https://en.wikipedia.org/wiki/Syslog>`_ is a standard for message logging over networks. OMERO.server supports logging to either a local or remote syslog service. This allows all logs of the OMERO.server to be routed to a central location instead of (or as well as) to a file. .. note:: It is important to note that this applies only to the OMERO.server itself, not to components like OMERO.web. How it works ------------ Whenever a log message is generated, OMERO's logging framework will forward that message to any configured appenders. By default, OMERO is configured to log everything to files. .. note:: OMERO is configured to log a record of events for operations such as import. These are written directly to the Managed Repository. It is very likely that even if replacing file logging with syslog, this aspect should be retained in files. This is easily achieved by not changing any loggers using `SIFT`. Configuration ^^^^^^^^^^^^^ To configure OMERO to be able to log to syslog, it is necessary to modify the file ``OMERO.server/current/etc/logback.xml``. It is possible to do all the configuration changes in this file alone, but for ease of config management, it is demonstrated here where an additional ``OMERO.server/current/etc/logback_syslog.xml`` file is used in addition. The following information is required to configure OMERO to log to syslog. - The host on which syslog is running: e.g. `localhost` - The port number on which syslog is running on that host: e.g. `514` - The facility (`RFC 3164 <https://tools.ietf.org/html/rfc3164>`_) that OMERO should be handled as: e.g. `user` or `local6` .. note:: The facility is important because it determines how syslog will handle the messages it receives. It is unlikely that OMERO's log output will be desired in a local systems primary message log for example. On Linux this is often ``/var/log/messages``. Remember to configure the syslog configuration to avoid this. This is also where configuration of onward forwarding can be configured (to a service such as `splunk <http://www.splunk.com/>`_). Finally, syslog can be configured to specifically output this facility output to a file such as ``/var/log/omero``. Create the new file ``OMERO.server/current/etc/logback_syslog.xml``: :: <?xml version="1.0" encoding="UTF-8"?> <included> <!-- syslog --> <appender name="SYSLOG" class="ch.qos.logback.classic.net.SyslogAppender"> <!-- Exclude debug level logging from ome.services.blitz.repo.ManagedImportRequestI --> <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> <evaluator> <!-- defaults to type ch.qos.logback.classic.boolex.JaninoEventEvaluator --> <expression>return Level.DEBUG.equals(Level.toLevel(level)) && logger.equals("ome.services.blitz.repo.ManagedImportRequestI");</expression> </evaluator> <OnMismatch>NEUTRAL</OnMismatch> <OnMatch>DENY</OnMatch> </filter> <!-- Exclude debug level logging from omero.* (except allow omero.cmd.*) --> <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> <evaluator> <!-- defaults to type ch.qos.logback.classic.boolex.JaninoEventEvaluator --> <expression>return Level.DEBUG.equals(Level.toLevel(level)) && logger.startsWith("omero.") && !logger.startsWith("omero.cmd.");</expression> </evaluator> <OnMismatch>NEUTRAL</OnMismatch> <OnMatch>DENY</OnMatch> </filter> <syslogHost>localhost</syslogHost> <facility>local6</facility> <suffixPattern>OMERO [%level] [%thread] %logger %msg</suffixPattern> </appender> </included> This creates an appender that sends messages to syslog. `syslogHost` is the host on which syslog is running. No port is specified as `514` is the default. The `suffixPattern` is customizable. In this instance it is identical to OMERO's file logger except an added "OMERO" identifier has been added for clarity. The name of the appender has been set to `SYSLOG`. The filters replicate the same behaviour from the default `FILE` appender. .. note:: If configuring the appender directly in the ``OMERO.server/current/etc/logback.xml`` file, then the `included` tag should not be used. Within the `configuration` tag of ``OMERO.server/current/etc/logback.xml`` add: :: <include file="/path/to/OMERO.server/etc/logback_syslog.xml"/> .. note:: The included file path can be relative, but note that it is NOT relative to the ``OMERO.server/current/etc/logback.xml`` file, but to the current directory set by OMERO. It is highly recommended to use a full path. Finally, also within ``OMERO.server/current/etc/logback.xml`` modify the `root` tag to include a second `appender-ref` (It can also be replaced if the file logs are not desired or syslog will handle writing those to a file on OMERO's behalf): :: <root level="OFF"> <appender-ref ref="SYSLOG"/> <appender-ref ref="FILE"/> </root> .. note:: A restart of OMERO will be necessary before this takes effect.