3.1.1.3.4.1.6 LDAP_SERVER_GET_STATS_OID

  • Article

The LDAP_SERVER_GET_STATS_OID control is used with an LDAP search operation.

When sending this control to a DC running Windows 2000 operating system, the client omits the controlValue field. When sending this control to a DC running Windows Server 2003 operating system and later, the client either omits the controlValue field or sets the controlValue field to one of the 32-bit unsigned integer values in the following table. The values are not BER-encoded.

Value name

Value

Description

SO_NORMAL

0

Perform the search as if no LDAP_SERVER_GET_STATS_OID control was included in the search request.

SO_STATS

1

Perform the search and return data related to the resources consumed performing the search, as well as the actual search results.

SO_ONLY_OPTIMIZE

2

Return data related to how the search would be performed, but do not actually return the search results.

SO_EXTENDED_FMT

4

Windows Server 2008 operating system and later: Returns the data in an alternative format documented later in this section.

Windows 2000, Windows Server 2003, Windows Server 2003 R2 operating system, and Active Directory Application Mode (ADAM): Not supported.

Omitting the controlValue field is equivalent to specifying the SO_STATS value.

When the server receives a search request with the LDAP_SERVER_GET_STATS_OID control attached to it, it includes a response control in the search response. The controlType field of the returned Control structure is set to the OID of the LDAP_SERVER_GET_STATS_OID control. The controlValue field is included in the returned Control structure.

The response to this control contains information outside the state model. This control instructs the server to return internal data related to how the LDAP search was performed.

For Windows 2000 DCs, the returned controlValue is the BER encoding of the following ASN.1 structure

 StatsResponseValueV1 ::= SEQUENCE {
     threadCountTag            INTEGER
     threadCount               INTEGER
     coreTimeTag               INTEGER
     coreTime                  INTEGER
     callTimeTag               INTEGER
     callTime                  INTEGER
     searchSubOperationsTag    INTEGER
     searchSubOperations       INTEGER
 }

where threadCountTag, coreTimeTag, callTimeTag, and searchSubOperationsTag are equal to 1, 2, 3, and 4, respectively. threadCount is the number of threads that were processing LDAP requests on the DC at the time the search operation was performed, coreTime is the time, in milliseconds, that the core logic in the DC spent processing the request, callTime is the overall time, in milliseconds, that the DC spent processing the request, and searchSubOperations is the number of individual operations that the DC performed in processing the request.

If the client does not have the SE_DEBUG_PRIVILEGE, a Windows 2000 DC MUST return the value 0 for the searchSubOperations field of this structure.

For Windows Server 2003, Windows Server 2003 R2, and ADAM DCs, the controlValue of the response control is the BER encoding of the following ASN.1 structure.

 StatsResponseValueV2 ::= SEQUENCE {
     threadCountTag        INTEGER
     threadCount           INTEGER
     callTimeTag           INTEGER
     callTime              INTEGER
     entriesReturnedTag    INTEGER
     entriesReturned       INTEGER
     entriesVisitedTag     INTEGER
     entriesVisited        INTEGER
     filterTag             INTEGER
     filter                OCTET STRING
     indexTag              INTEGER
     index                 OCTET STRING
 }

In this structure, threadCountTag, threadCount, callTimeTag, and callTime are defined as in the Windows 2000 structure. entriesReturnedTag, entriesVisitedTag, filterTag, and indexTag are 5, 6, 7, and 8, respectively. entriesReturned is the number of objects returned in the search result. entriesVisited is the number of objects that the DC considered for inclusion in the search result. filter is a UTF-8 string that represents the optimized form of the search filter that is used by the DC to perform a search. index is a string, defined by the system default code page, that indicates which database indexes were used by the DC to perform the search.

If the client does not have the SE_DEBUG_PRIVILEGE, a Windows Server 2003, Windows Server 2003 R2, or ADAM DC MUST return the value 0 for the entriesReturned and entriesVisited fields of this structure. The server MUST return NULL for the filter and index fields of this structure.

For Windows Server 2008 and later DCs, the controlValue of the response control is the BER encoding of the following ASN.1 structure if the SO_EXTENDED_FMT flag is not specified.

 StatsResponseValueV3 ::= SEQUENCE {
     threadCountTag        INTEGER
     threadCount           INTEGER
     callTimeTag           INTEGER
     callTime              INTEGER
     entriesReturnedTag    INTEGER
     entriesReturned       INTEGER
     entriesVisitedTag     INTEGER
     entriesVisited        INTEGER
     filterTag             INTEGER
     filter                OCTET STRING
     indexTag              INTEGER
     index                 OCTET STRING
     pagesReferencedTag    INTEGER
     pagesReferenced       INTEGER
     pagesReadTag          INTEGER
     pagesRead             INTEGER
     pagesPrereadTag       INTEGER
     pagesPreread          INTEGER
     pagesDirtiedTag       INTEGER
     pagesDirtied          INTEGER
     pagesRedirtiedTag     INTEGER
     pagesRedirtied        INTEGER
     logRecordCountTag     INTEGER
     logRecordCount        INTEGER
     logRecordBytesTag     INTEGER
     logRecordBytes        INTEGER
 }

In this structure, fields with the same name as fields in the Windows Server 2003 structure are defined as in the Windows Server 2003 structure. pagesReferencedTag, pagesReadTag, pagesPrereadTag, pagesDirtiedTag, pagesRedirtiedTag, logRecordCountTag, and logRecordCountBytesTag are 9, 10, 11, 12, 13, 14, and 15, respectively. pagesReferenced is the number of database pages referenced by the DC in processing the search. pagesRead is the number of database pages read from disk, and pagesPreread is the number of database pages preread from disk by the DC in processing the search. pagesDirtied is the number of clean database pages modified by the DC in processing the search, while pagesRedirtied is the number of previously modified database pages that were modified by the DC in processing the search. logRecordCount and logRecordBytes are the number and size in bytes, respectively, of database log records generated by the DC in processing the search.

For Windows Server 2008 and later DCs, if the SO_EXTENDED_FMT flag is specified, an alternative format is used for the controlValue of the response control instead of the format shown previously. Unlike the previous formats in which each statistic is assigned a fixed position within the structure, in the alternative format the ordering of the statistics can change. Rather than relying on position, each statistic has an associated human-readable string that specifies what that statistic is. Additionally, the use of these associated strings alleviates the need to hard-code the positional information into the client-side parser of the response control, permitting the DC to be updated to return addition statistics without necessitating a corresponding client-side change.

When using the alternative format, the controlValue of the response control is the BER encoding of the following ASN.1 structure.

 StatsResponseValueV4 ::= SEQUENCE OF SEQUENCE {
     statisticName         OCTET STRING
     CHOICE {
         intStatistic [0]       INTEGER
         stringStatistic [1]    OCTET STRING
     }
 }

If the human-readable string in an element of the StatsResponseValueV4 structure is the empty string, then the element contains an undefined value of no significance.

Effectively, this is an array of statistics, in which each statistic has a human-readable name (the statisticName field) and a value. If it is an integer-valued statistic, the value is stored in the intStatistic field. If it is a string-valued statistic, the value is stored in the stringStatistic field.

When the SO_EXTENDED_FMT flag is specified, Windows Server 2008 and later DCs return the same statistics as if the flag was not specified. The only difference is the format used to return the statistics. The wording of the statisticName field is implementation-defined. Currently, the wording as it maps to each statistic as specified in the non-SO_EXTENDED_FMT version of the structure is as follows.

 threadCount           "Thread count"
 callTime              "Call time (in ms)"
 entriesReturned       "Entries Returned"
 entriesVisited        "Entries Visited"
 filter                "Used Filter"
 index                 "Used Indexes"
 pagesReferenced       "Pages Referenced"
 pagesRead             "Pages Read From Disk"
 pagesPreread          "Pages Pre-read From Disk"
 pagesDirtied          "Clean Pages Modified"
 pagesRedirtied        "Dirty Pages Modified"
 logRecordCount        "Log Records Generated"
 logRecordBytes        "Log Record Bytes Generated"

For Windows Server 2008 through Windows Server 2012 R2 operating system DCs, a requestor is said to have debug search stats permitted when it holds the SE_DEBUG_PRIVILEGE. For Windows Server 2016 operating system and later DCs, a requestor is said to have debug search stats permitted if it holds the SE_DEBUG_PRIVILEGE or if it has the control access right identified by the GUID {b3ab0434-7863-4891-bdbd-9ca79f1c099b} on the queryPolicy object for the DC (section 3.1.1.3.4.6).

If the client does not have debug search stats permitted, Windows Server 2008 and later DCs MUST return the value 0 for the entriesReturned, entriesVisited, pagesReferenced, pagesRead, pagesPreread, pagesDirtied, pagesRedirtied, logRecordCount, and logRecordBytes fields, regardless of the format in which the data is returned. The server MUST return NULL for the filter and index fields, regardless of the format in which the data is returned.

When the SO_EXTENDED_FMT flag is specified and the client has debug search stats permitted, Windows Server 2016 and later DCs additionally return the following statistics: indicesRequiredToOptimize, queryOptimizerState, atqDelay, cpuTime, and searchSignature.

indicesRequiredToOptimize is a space-separated list of attributes for which no indices exist and for which the implementation could have performed a more optimized search if such indices existed. queryOptimizerState is a description of the final processing state of the implementation's query pre-processing. This statistic is only returned when the SO_STATS or SO_ONLY_OPTIMIZE flags are specified in addition to the SO_EXTENDED_FMT flag. atqDelay is an approximation of the amount of time (in milliseconds) that the request spent on a queue on the DC before the DC began to actively process the request. cpuTime is an approximation of the amount of time (in milliseconds) that the DC spent to actively process the request. There is no protocol requirement regarding the accuracy of these approximations. searchSignature is an implementation-defined value that encapsulates some of the search parameters. The choice of which parameters to encapsulate and how to encapsulate them is an implementation detail and not normatively defined by the protocol. Informally, the intent of this statistic is to assign the same signature to "similar" searches. The wording of the statisticName field as it maps to these additional statistics is as follows.

 indicesRequiredToOptimize "Indices required to optimize"
 queryOptimizerState       "Query optimizer state"
 atqDelay                  "Atq Delay"
 cpuTime                   "CPU Time"
 searchSignature           "Search Signature"

When the SO_EXTENDED_FMT flag is specified, Windows Server v1803 operating system and later DCs additionally return the following statistics: callTimeTotal, cpuTimeTotal, retryCount, and correlationId.

If the client does not have debug search stats permitted, a Windows Server v1803 and later DC MUST return the value 0 for the callTimeTotal, cpuTimeTotal, and retryCount fields, regardless of the format in which the data is returned.

The retryCount field is an integer containing the number of times the LDAP request was internally re-attempted while fulfilling the request. callTimeTotal is an approximation of the overall time taken (in milliseconds) to fulfill a request including overhead real time. cpuTimeTotal is an approximation of the amount of time (in milliseconds) that the DC spent to actively process the request including overhead processing time. correlationId contains an identifier for the LDAP request. If a correlation identifier was provided to the DC via the LDAP_SERVER_SET_CORRELATION_ID_OID control, that value is returned. If no such correlation identifier was provided, there is no restriction on what value is returned. The wording of the statisticName field as it maps to these additional statistics is as follows.

 callTimeTotal "Total call time (in ms)"
 cpuTimeTotal  "Total CPU time"
 retryCount    "Number of retries"
 correlationId "Correlation ID"

When the SO_EXTENDED_FMT flag is specified, Windows Server v1809 operating system and later DCs and Windows Server 2019 operating system and later DCs additionally return the following statistics:

  • linksAdded and linksDeleted.

    If the client does not have debug search stats permitted, or if the request is a search request, the DC MUST return the value 0 for these fields, regardless of the format in which the data is returned.

  • For values not equal to 0, DCs additionally return optimizedLinkSeeks, nonOptimizedLinkSeeks, selectionFilterOverhead, and linkIndexMisses.

    If the client does not have debug search stats permitted, the DC MUST NOT return these fields, regardless of the format in which the data is returned. Otherwise, the above specified values are additionally returned by the DC.

The linksAdded field is an integer containing the number of object links added while fulfilling the request. The linksDeleted field is an integer containing the number of object links deleted while fulfilling the request. optimizedLinkSeeks is an implementation-defined value that approximates the relative optimized data-seek expense of retrieving object links while fulfilling the request. nonOptimizedLinkSeeks is an implementation-defined value that approximates the relative unoptimized data-seek expense of retrieving object links while fulfilling the request. selectionFilterOverhead is an implementation-defined value that approximates the relative data-processing expense of applying a selection filter while fulfilling the request. linkIndexMisses is an implementation-defined value that approximates the number of times that indexes could not be used while applying a selection filter when fulfilling the request. The wording of the statisticName field as it maps to these additional statistics is as follows.

 linksAdded              "Links Added"
 linksDeleted            "Links Deleted"
 optimizedLinkSeeks      "Optimized Link Seeks"
 nonOptimizedLinkSeeks   "Non-Optimized Link Seeks"
 selectionFilterOverhead "Selection Filter Overhead"
 linkIndexMisses         "Link Index Misses"