search

389ds / 389-ds-base

The enterprise-class Open Source LDAP server for Linux
https://www.port389.org/
Other
200 stars 82 forks source link

No documentation for slapd log levels #6231

Open alexandrevicenzi opened 2 weeks ago

alexandrevicenzi commented 2 weeks ago

Hi,

It seems that the only place where slapd log levels exist is in the code.

/*
 * log.c
 */
#define LDAP_DEBUG_TRACE      0x00000001  /*         1 */
#define LDAP_DEBUG_PACKETS    0x00000002  /*         2 */
#define LDAP_DEBUG_ARGS       0x00000004  /*         4 */
#define LDAP_DEBUG_CONNS      0x00000008  /*         8 */
#define LDAP_DEBUG_BER        0x00000010  /*        16 */
#define LDAP_DEBUG_FILTER     0x00000020  /*        32 */
#define LDAP_DEBUG_CONFIG     0x00000040  /*        64 */
#define LDAP_DEBUG_ACL        0x00000080  /*       128 */
#define LDAP_DEBUG_STATS      0x00000100  /*       256 */
#define LDAP_DEBUG_STATS2     0x00000200  /*       512 */
#define LDAP_DEBUG_SHELL      0x00000400  /*      1024 */
#define LDAP_DEBUG_PARSE      0x00000800  /*      2048 */
#define LDAP_DEBUG_HOUSE      0x00001000  /*      4096 */
#define LDAP_DEBUG_REPL       0x00002000  /*      8192 */
#define LDAP_DEBUG_ANY        0x00004000  /*     16384 */
#define LDAP_DEBUG_CACHE      0x00008000  /*     32768 */
#define LDAP_DEBUG_PLUGIN     0x00010000  /*     65536 */
#define LDAP_DEBUG_TIMING     0x00020000  /*    131072 */
#define LDAP_DEBUG_ACLSUMMARY 0x00040000  /*    262144 */
#define LDAP_DEBUG_BACKLDBM   0x00080000  /*    524288 */
#define LDAP_DEBUG_PWDPOLICY  0x00100000  /*   1048576 */
#define LDAP_DEBUG_EMERG      0x00200000  /*   2097152 */
#define LDAP_DEBUG_ALERT      0x00400000  /*   4194304 */
#define LDAP_DEBUG_CRIT       0x00800000  /*   8388608 */
#define LDAP_DEBUG_ERR        0x01000000  /*  16777216 */
#define LDAP_DEBUG_WARNING    0x02000000  /*  33554432 */
#define LDAP_DEBUG_NOTICE     0x04000000  /*  67108864 */
#define LDAP_DEBUG_INFO       0x08000000  /* 134217728 */
#define LDAP_DEBUG_DEBUG      0x10000000  /* 268435456 */
#define LDAP_DEBUG_ALL_LEVELS 0xFFFFFF

Is there a document with a meaningful message about each log level?

A few can be traced to https://pagure.io/389-ds-base/issue/48978. PWDPOLICY can be traced to https://github.com/389ds/389-ds-base/commit/469e856cad65996fdaa2afb33051603555179c67. Everything else is traced to https://github.com/389ds/389-ds-base/commit/b2093e3016027d6b5cf06b3f91f30769bfc099e2.

OpenLDAP has a few options, but not all levels.

mreynolds389 commented 2 weeks ago

Does this help:

https://access.redhat.com/documentation/en-us/red_hat_directory_server/12/html/configuration_and_schema_reference/assembly_log-files-reference_config-schema-reference-title#ref_error-log-logging-levels_assembly_error-log-reference

alexandrevicenzi commented 2 weeks ago

@mreynolds389 yes, it helps, but it does not list all levels. The ones introduced by https://pagure.io/389-ds-base/issue/48978 are missing.

mreynolds389 commented 2 weeks ago

@mreynolds389 yes, it helps, but it does not list all levels. The ones introduced by https://pagure.io/389-ds-base/issue/48978 are missing.

Those are not logging levels. Those indicate how severe the message is (regardless of the logging level). They do their best to comply with syslogs severity levels.

mreynolds389 commented 2 weeks ago

@mreynolds389 yes, it helps, but it does not list all levels. The ones introduced by https://pagure.io/389-ds-base/issue/48978 are missing.

Those are not logging levels. Those indicate how severe the message is (regardless of the logging level). They do their best to comply with syslogs severity levels.

Sorry this is not entirely accurate, and from a coding perspective I can understand the confusion here.

So yes, the severity levels are "log levels" from an internal perspective, but not from an external one. You can not configure the error log to only log a specific severity level. The severity levels are only for generic/default error messages, and are intended to give more meaning to a message. You can view it like this:

These are the configurable logging levels that log specific messages about their own context:

#define LDAP_DEBUG_TRACE      0x00000001  /*         1 */
#define LDAP_DEBUG_PACKETS    0x00000002  /*         2 */
#define LDAP_DEBUG_ARGS       0x00000004  /*         4 */
#define LDAP_DEBUG_CONNS      0x00000008  /*         8 */
#define LDAP_DEBUG_BER        0x00000010  /*        16 */
#define LDAP_DEBUG_FILTER     0x00000020  /*        32 */
#define LDAP_DEBUG_CONFIG     0x00000040  /*        64 */
#define LDAP_DEBUG_ACL        0x00000080  /*       128 */
#define LDAP_DEBUG_STATS      0x00000100  /*       256 */
#define LDAP_DEBUG_STATS2     0x00000200  /*       512 */
#define LDAP_DEBUG_SHELL      0x00000400  /*      1024 */
#define LDAP_DEBUG_PARSE      0x00000800  /*      2048 */
#define LDAP_DEBUG_HOUSE      0x00001000  /*      4096 */
#define LDAP_DEBUG_REPL       0x00002000  /*      8192 */
#define LDAP_DEBUG_ANY        0x00004000  /*     16384 */
#define LDAP_DEBUG_CACHE      0x00008000  /*     32768 */
#define LDAP_DEBUG_PLUGIN     0x00010000  /*     65536 */
#define LDAP_DEBUG_TIMING     0x00020000  /*    131072 */
#define LDAP_DEBUG_ACLSUMMARY 0x00040000  /*    262144 */
#define LDAP_DEBUG_BACKLDBM   0x00080000  /*    524288 */
#define LDAP_DEBUG_PWDPOLICY  0x00100000  /*   1048576 */

These "severity levels" are only for "default" error messages and they are NOT configurable

#define LDAP_DEBUG_EMERG      0x00200000  /*   2097152 */
#define LDAP_DEBUG_ALERT      0x00400000  /*   4194304 */
#define LDAP_DEBUG_CRIT       0x00800000  /*   8388608 */
#define LDAP_DEBUG_ERR        0x01000000  /*  16777216 */
#define LDAP_DEBUG_WARNING    0x02000000  /*  33554432 */
#define LDAP_DEBUG_NOTICE     0x04000000  /*  67108864 */
#define LDAP_DEBUG_INFO       0x08000000  /* 134217728 */
alexandrevicenzi commented 2 weeks ago

Those are not logging levels. Those indicate how severe the message is (regardless of the logging level). They do their best to comply with syslogs severity levels.

I noticed that while reading the original Pagure issue, but in the code they are used by slapi_log_err as other levels.

These "severity levels" are only for "default" error messages and they are NOT configurable

In https://github.com/389ds/389-ds-base/blob/main/src/lib389/cli/dscontainer#L326 the log level (env var DS_ERRORLOG_LEVEL) is 266354688, which matches LDAP_DEBUG_DEBUG. It seems you can configure and use it. Is this an addition from others that happens to match? Or is this a wrong value?

I also noticed that LDAP_DEBUG_TIMING is unused in the code and undocumented. LDAP_DEBUG_STATS and LDAP_DEBUG_STATS2 while used, seem to not be documented in the Red Hat Directory Server docs.

mreynolds389 commented 2 weeks ago

Those are not logging levels. Those indicate how severe the message is (regardless of the logging level). They do their best to comply with syslogs severity levels.

I noticed that while reading the original Pagure issue, but in the code they are used by slapi_log_err as other levels.

Basically all the "severity" levels are for fine grained interpretations of LDAP_DEBUG_ANY(SLAPI_LOG_ERR). We added the severity levels because customers could not determine if a log message as an INFO message or an actual error they should care about. So we replaced thousands of these generic error log messages more detailed ones via these severity levels:

                                        LDAP_DEBUG_ANY
                                      |  |  |  |  |  |  | 

LDAP_DEBUG_EMERG   LDAP_DEBUG_ALERT   LDAP_DEBUG_CRIT   LDAP_DEBUG_ERR  LDAP_DEBUG_WARNING ...

These "severity levels" are only for "default" error messages and they are NOT configurable

In https://github.com/389ds/389-ds-base/blob/main/src/lib389/cli/dscontainer#L326 the log level (env var DS_ERRORLOG_LEVEL) is 266354688, which matches LDAP_DEBUG_DEBUG.

This is kind of a catch-all debug level IIRC

It seems you can configure and use it. Is this an addition from others that happens to match? Or is this a wrong value?

I'd have to play around with it - it's not a commonly used log level

I also noticed that LDAP_DEBUG_TIMING is unused in the code and undocumented. LDAP_DEBUG_STATS and LDAP_DEBUG_STATS2 while used, seem to not be documented in the Red Hat Directory Server docs.

Keep in mind this source code is probably 30 years old. Some of these log levels simply aren't used anymore, and the logging was removed.

The LDAP_DEBUG_STATS/LDAP_DEBUG_STATS2 is used for the access log logging level (not error log). The naming is terrible, but that's what it's used for.