Date: 5/16/2022

Symas makes two tools available for OpenLDAP log analysis and reduction:

• lr2 - the log analysis and reduction tool and
• ll2 - a log load analysis tool

These programs are written in Python3 and have no special dependencies.

The programs are available from Symas's git repository.

README File Contents

# Symas Logging Utilities
> This program is made available under the Symas Public License.
> For a copy please see https://symas.com/licenses.html

This directory contains two Python3 scripts:

* `lr2`: Log Reduction and Summary - This reads an OpenLDAP Log file and produces a summary (described in detail below) of the overall log.
* `ll2`: Loag Load Analyzer - This program reads the reduced form of the log produced by `lr2` (.rlog) and summarizes the LDAP Requests receive in user-specified intervals (in seconds). The first and last intervals MAY be inaccurate as the log file may start or end in the middle of the interval.

A convenience shell script, `doLog` runs the scripts for the specified log file in sequence.

The two tools write their output to STDOUT. Normal redirection should be used to retain the output for later review.

## `lr2`

`lr2` is a python program (script) that reduces a log file to a report:

### USAGE

    lr2 <fully-qualified-pathname-to-log> [ > <file-for-output ]

### Summary Report

* Summaries by LDAP operation type: 
    * total number of each operation found in the log,
    * the number of those requests that failed (err not 0 or 10 (refer)). 
    * If microsecond-timing is enabled in the OpenLDAP logs, the `slapd` elapsed time processing the requests feeds evaluation of average and maximum. Otherwise times are not reported. Microsecond timing is standard in OpenLDAP 2.5 and 2.6..
* A section will report the appearance of un-indexed Attributes used in search filters. Searches with un-indexed Attributes force OpenLDAP to read the entire database to fulfill the query. This is not a problem for very occasional queries but should be avoided in general.
* The number of `syncrepl` "Refresh" operations found in the log
* Non-zero return codes by LDAP Operation  with counts
* Summary of syncrepl pseudo-ops to provide an indication of the amount of `syncrepl` traffic is also being handled. 
  The requests above are those coming from the network. These "requests" come from replication. syncrepl traffic is not reflected by normal log records. It is only visible in the "SYNC" records. "REPEAT" is used as shorthand for consumer syncrepl traffic that results in OpenLDAP realizing that the update was already made (CSN_TOO_OLD). This is "normal" in multi-master replication clusters. Excessive numbers of replication pairings can drive this non-productive traffic up. It should be monitored.

### Reduced Log File

`lr2` also produces a summary of the operations and syncrepl pseudo-operations in a "reduced log" file. Its name will be the same as the input log file with an additional suffix of '.rlog'. The rlog file contains one line for each operation or pseudo-operation found. The line contains, in order:

* The line number of the beginning of a normal LDAP operation or of the line o which the pseudo-operation was found.
* The connection number of the connection the request was made under.
* The operation number of the request within the connection
* A "session number" rarely used. This is important when a log contains a restart.
* The request's formal name reported in the log: SRCH, BIND, ATTACH, etc.
* A Tag field for which we have no actual documentation
* The LDAP Return Code 
* The number of entries returned by the operation
* The time the request was queued (qtime) in microseconds. Will be '0.0' if the log does not contain microsecond timing
* The elapsed time the `slapd` processing the request (3time) in microseconds. Will be '0.0' if the log does not contain microsecond timing
* The log record's time stamp for the first line for the operation (or the only line of the pseudo-operation)
* The log record's time stamp for the last (RESULT) line for the operation
* The last line number in the original file where the RESULT or SRCH RESULT can be found. For pseudo-operations this is the same value as the first field.

Pseudo-operations have bogus values of '-2' for connection number and operation number. Something had to be put there ;-).

## `ll2`

    ll2 <fully-qualified-pathname-to-reduced-log> [ > <file-for-output ]

`ll2` processes the out file from `lr2`, an `*.rlog` file. 

`ll2` produces a summary of the number of operations per "interval". The sample interval can be set by setting the environment variable LL2_INTERVAL to the number of seconds you want. Only LDAP requests from the network are reported by `ll2`. This program is intended to show the external load handled by the server/instance. An environment variable (LL2_DETAIL) can be set to "true" or "yes" to have `ll2` print a detail line for each interval. Otherwise, only the summary is printed. 

# Convenience Script

## `doLog`

`doLog` is a shell script (`/bin/bash`) that runs `lr2`, `logload`, and `logloadb` in order against the same log file.

## Usage

    doLog <fully-qualified-path-name-to-log [ > <file-for-output ]