summaryrefslogtreecommitdiffstats
path: root/doc/logging.txt
blob: b4ee45996a578250514ee6da6ef7693815898b1f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

New logging framework in glusterfs is targeted for end users like
customers, community members, testers etc.  This aims to bring clear,
understandable logs called user logs whereas the current logging are
considered as developer logs.  The new framework brings with following
features

* Each message is logged with proper well defined error code and each
  error code has well known error message.
* A logbook has defined error code and error messages.  It helps to
  keep track of possible causes and remedies
* Log are sent to syslog.  The syslog application can be configured to
  pass them to centralized logging system
* It brings
  - Remove repeated log messages
  - Send alerts to users on certain events
  - Run a program on events
  - Call home service on events


Log book:
=========
A log book is a JSON formatted file error-codes.json located in top
level of glusterfs source repository.  At compile time, gen-headers.py
generates libglusterfs/src/gf-error-codes.h using the log book and
gf-error-codes.h.template file.  libglusterfs/src/gf-error-codes.h
consists of header definitions and helper functions to get message by
code for given locale. Currently it has _gf_get_message() function
returns message for locale 'en'.

New entry to log book is added like

{
    "IO_ERROR": {"code": 2233,
                 "message": {"en": "I/O error occurred"}},
    "SETUP_ERROR": {"code": 2240,
                 "message": {"en": "Setup error"}},
}


Logging:
========
The framework provides two functions

void gf_openlog (const char *ident, int option, int facility);
void gf_syslog (int error_code, int facility_priority, char *format, ...);

Consumers need to call gf_openlog() prior to gf_syslog() like the way
traditional syslog function calls.  error_code is mandatory when using
gf_syslog().  For example,

gf_openlog (NULL, -1, -1);
gf_syslog (GF_ERR_DEV, LOG_ERR, "error reading configuration file");

The logs are sent in CEE format (http://cee.mitre.org/) to syslog.
Its targeted to rsyslog syslog server.

This log framework is enabled at compile time by default.  This can be
disabled by passing '--disable-syslog' to ./configure or '--without
syslog' to rpmbuild

Even though its enabled at compile time, its required to have
/etc/glusterfs/logger.conf file to make it into effect before starting
gluster services

Currently all gluster logs are sent with error code GF_ERR_DEV.