Enabling tracing

Tracing can be enabled in the LDAP programming interface. Any change to trace options is global and affects all LDAP handles. There are two methods to enable tracing:

  1. The first method is to use the ldap_set_option() API, specifying the option to be set as LDAP_OPT_DEBUG or LDAP_OPT_DEBUG_STRING. Once a new debug level is set using this method, the debug level that is specified with the LDAP_DEBUG environment variable is no longer in effect.
    Example: To enable all trace classes using the ldap_set_option() API, specify one of the following:
        rc = ldap_set_option(ld, LDAP_OPT_DEBUG, LDAP_DEBUG_ANY);
    
    or
    
    rc = ldap_set_option(ld, LDAP_OPT_DEBUG_STRING, "ANY");
    The value that is specified for LDAP_OPT_DEBUG_STRING is a string that can have the same values as the LDAP_DEBUG environment variable. The call to ldap_set_option() can occur at any point after calling ldap_init() and before calling ldap_unbind() or ldap_unbind_s() to set or change debug options.
  2. The second method for enabling tracing is to set the LDAP_DEBUG environment variable. The value for LDAP_DEBUG is a mask that you can specify as follows:
    • A decimal value (for example, 32).
    • A hexadecimal value (for example, x20, X20, 0x20, or 0X20)
    • A keyword (for example, FILTER)
    • A construct of those values using plus and minus signs to indicate inclusion or exclusion of a value. For example:
      • ’32768+8’ is the same as specifying ’x8000+x8’, or ’ERROR+CONNS’
      • '2147483647-16' is the same as specifying 'x7FFFFFFF-x10' or 'ANY-BER'
      • By beginning the debug level with a minus sign, you can deactivate debug collection for a debug level. For example, "-CONNS" modifies an existing debug level by deactivating connection traces.
      • By beginning the debug level with a plus sign, you can activate debug collection for a debug level. For example, "+CONNS" modifies an existing debug level by activating connection traces.
      Note: Specifying the debug level using decimal or hex values with a plus or minus sign is not necessarily the same as specifying the sum or difference as the debug level. For example, specifying '7+1' activates the 'TRACE', 'PACKETS', and 'ARGS' debug levels, while specifying '8' activates only the 'CONNS' debug level. Similarly, specifying '16-1' activates only the 'BER' debug level, while specifying '15' activates 'TRACE', 'PACKETS', ARGS', and 'CONNS'.

    Restrictions: To enable or change tracing using this method, the LDAP_DEBUG environment variable must be set or changed before the client run time is first initialized. Later changes to the value of LDAP_DEBUG have no effect on the debug level of the client. If the debug level is set or changed using the LDAP_OPT_DEBUG or LDAP_OPT_DEBUG_STRING option, the debug level that is specified with the LDAP_DEBUG environment variable is no longer in effect.

    The LDAP trace routine uses the IBM-1047 code page when writing text data to the trace data set. The trace output is written to stdout unless the LDAP_DEBUG_FILENAME environment variable is defined. If the application creates additional processes, specify % as part of the trace file name. This causes the % to be replaced by the current process identifier, therefore, generating a unique file name for each process. Failure to do this can cause the trace file to be corrupted because locking is done on a process basis.

    Example: The following example shows the use of % in the trace file name.
        export LDAP_DEBUG_FILENAME=/tmp/myapp.%.trc
    Table 1 lists the debug levels and related decimal, hexadecimal, and keyword values. Keywords can be abbreviated using the uppercase characters for each keyword.
    Table 1. LDAP debug levels
    Keyword Decimal Hexadecimal Description
    OFF 0 0x00000000 No debugging
    TRACe 1 0x00000001 Entry and exit from routines
    PACKets 2 0x00000002 Packet activity
    ARGS 4 0x00000004 Data arguments from requests
    CONNs 8 0x00000008 Connection activity
    BER 16 0x00000010 Encoding and decoding of data, including ASCII and EBCDIC translations, if applicable
    FILTer 32 0x00000020 Search filters
    MESSage 64 0x00000040 Messaging subsystem activities and events
    ACL 128 0x00000080 Access Control List activities
    STATs 256 0x00000100 Operational statistics
    THREad 512 0x00000200 Threading activities
    REPLication 1024 0x00000400 Replication activities
    PARSe 2048 0x00000800 Parsing activities
    PERFormance 4096 0x00001000 Performance statistics
    SDBM 8192 0x00002000 Backend activities (SDBM)
    REFErral 16384 0x00004000 Referral activities
    ERROr 32768 0x00008000 Error conditions
    SYSPlex 65536 0x00010000 Sysplex/WLM activities
    MULTIServer 131072 0x00020000 Multi-server activities
    LDAPBE 262144 0x00040000 Connection between a frontend and a backend
    STRBuf 524288 0x00080000 UTF-8 support activities
    TDBM 1048576 0x00100000 Backend activities (TDBM)
    SCHEma 2097152 0x00200000 Schema support activities
    BECApabilities 4194304 0x00400000 Backend capabilities
    CACHe 8388608 0x00800000 Cache activities
    INFO 16777216 0x01000000 General processing information
    LDBM 33554432 0x02000000 Backend activities (LDBM)
    PLUGin 67108864 0x04000000 Plug-in extension activities
    ANY 2147483647 0x7FFFFFFF All levels of debug
    ALL 2147483647 0x7FFFFFFF All levels of debug
    Note: The minimum abbreviation for each keyword is shown in uppercase letters.