Bug 994127 - Asynchronous file logging is undocumented
Asynchronous file logging is undocumented
Status: CLOSED ERRATA
Product: Red Hat Enterprise Linux 6
Classification: Red Hat
Component: rsyslog7 (Show other bugs)
6.4
All Linux
unspecified Severity medium
: rc
: ---
Assigned To: Tomas Heinrich
Dalibor Pospíšil
: Documentation
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2013-08-06 10:39 EDT by John Koelndorfer
Modified: 2014-10-14 03:30 EDT (History)
7 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2014-10-14 03:30:19 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description John Koelndorfer 2013-08-06 10:39:23 EDT
Description of problem:

A feature of rsyslog that allows you to skip syncing after every log entry is undocumented in the rsyslog.conf man page.  The feature is documented at http://www.rsyslog.com/doc/rsyslog_conf_actions.html:

You may prefix each entry with the minus "-'' sign to omit syncing the file after every logging. Note that you might lose information if the system crashes right behind a write attempt. Nevertheless this might give you back some performance, especially if you run programs that use logging in a very verbose manner.

It seems that the version packaged does have this functionality.  I verified by downloading and unpacking http://ftp.redhat.com/pub/redhat/linux/enterprise/6Server/en/os/SRPMS/rsyslog-5.8.10-6.el6.src.rpm.  Once unpacked, I examined tools/omfile.c in the source directory.  Line 742 - 747 implements (some) of the feature:

    if(*p == '-') {
        pData->bSyncFile = 0;
        p++;
    } else {
        pData->bSyncFile = bEnableSync;
    }

Version-Release number of selected component (if applicable): 5.8.10-6.el6


How reproducible: Always


Steps to Reproduce:
1. Execute "man rsyslog.conf"
2. Look for description of aforementioned feature

Actual results:

Feature does not appear in the manual.

Expected results:

Feature should be documented in the manual.  I would suggest under the ACTIONS -> Regular file section.

Additional info:
Comment 2 Martin Poole 2013-08-08 13:08:21 EDT
This is already covered in the accompanying HTML documentation.
Comment 3 John Koelndorfer 2013-08-08 14:58:42 EDT
Does that preclude the feature from being covered in the man page?  If that is the case, perhaps the man page should be entirely replaced with a simple message that says "see the HTML documentation."

You must understand that, as an administrator, it's not convenient to be reading HTML docs on a server.  Especially if we have to go digging in them to find major software features.

Further, I would like to point out that there are much less useful features which are documented in the manual.  There's a fully working example for inserting log messages into a database.  Is this more or less common than enabling asynchronous writes?

Asynchronous writes are of interest to all but the smallest environments.  By contrast, I don't think many people are going to be sending their logs to a named pipe or database.

All that would be necessary is a single line saying "prefixing the file name with a - will cause writes to be asynchronous."
Comment 4 Tomas Heinrich 2013-08-16 08:56:58 EDT
First of all: Yes, the man page is lacking quite a bit.

(In reply to John Koelndorfer from comment #3)
> Does that preclude the feature from being covered in the man page?  If that

Certainly not.

> is the case, perhaps the man page should be entirely replaced with a simple
> message that says "see the HTML documentation."

Surely there is some threshold to what amount of information is desirable to have in one place.

> You must understand that, as an administrator, it's not convenient to be
> reading HTML docs on a server.  Especially if we have to go digging in them
> to find major software features.

I agree that the man pages are the traditional way of providing documentation on the command line. But I would argue that elinks is not that much worse. There might be people arguing that info(1) is the only one true way.

> Further, I would like to point out that there are much less useful features
> which are documented in the manual.  There's a fully working example for
> inserting log messages into a database.  Is this more or less common than
> enabling asynchronous writes?

The problem in this case is that the upstream has chosen to use the html files as the primary source of documentation and the man page is getting rusty.

> Asynchronous writes are of interest to all but the smallest environments. 
> By contrast, I don't think many people are going to be sending their logs to
> a named pipe or database.
>
> All that would be necessary is a single line saying "prefixing the file name
> with a - will cause writes to be asynchronous."

It would be necessary to periodically check the man page for differences to the latest docs, otherwise sooner of later 
somebody comes along complaining their favorite feature is not included.

I'll get to updating the man page, eventually, but that is a low priority item, which is hopefully understandable.
In the meantime, upstream happily accepts suggestions for improvements.
Comment 5 RHEL Product and Program Management 2013-10-13 22:50:20 EDT
This request was not resolved in time for the current release.
Red Hat invites you to ask your support representative to
propose this request, if still desired, for consideration in
the next release of Red Hat Enterprise Linux.
Comment 15 errata-xmlrpc 2014-10-14 03:30:19 EDT
Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

http://rhn.redhat.com/errata/RHEA-2014-1540.html

Note You need to log in before you can comment on or make changes to this bug.