PingDirectory

Working with the entry counter plugin

You can use the entry counter plugin to count and report the number of entries in the server that match your specified criteria.

How the entry counter plugin works

The plugin periodically performs background searches to find entries matching your configured search criteria, which can include base DNs, filters, and named subcategory filters. The plugin reports the number of matching entries and other related information in monitor entries that you can retrieve using the administrative console or an LDAP client.

The entry counter plugin minimizes the need for long, expensive searches. The plugin updates its search results after each polling duration, which is configured using time-between-searches.

Use the entry counter plugin to create a search for active users so that you can monitor your need for user licenses in real time.

How to set up the entry counter plugin

By default, the entry counter plugin isn’t enabled. You need to do the following:

  1. Create and enable the plugin.

  2. Configure a set of criteria for the plugin.

  3. Consume the output of the plugin.

You can only enable and configure a single instance of the plugin, but you can create multiple named sets of criteria.

Creating and enabling the plugin

When creating the entry counter plugin, do the following:

  • Give the plugin a name, which you reference when creating criteria.

  • Specify a plugin type of entry-counter.

  • Enable the plugin.

  • (Optional) Specify the length of time between searches using time-between-searches.

    The time-between-searches parameter represents the length of time between the end of one search and the beginning of the next. The default value is 1 hour.

    Before you set a different value, consider how many entries a search involves and how long it could take. Set a value that accounts for both the length of the search and your need for the latest information.

Here’s an example of how to create and enable the entry counter plugin:

$ bin/dsconfig create-plugin \
    --plugin-name "Entry Counter" \
    --type entry-counter \
    --set enabled:true \
    --set time-between-searches:100ms

Configuring a set of entry counter criteria

You can configure one or more sets of entry counter criteria. Each set can specify the following:

  • Which entries to count (required)

  • Warning and error count thresholds (optional)

  • Whether to report entry sizes on disk (optional)

Use the following properties to configure a set of entry counter plugin criteria:

Property Required or optional Description

base-dn

Optional

A multivalued property that specifies one or more base DNs to use when searching for matching entries.

If you don’t specify a base DN, the server uses the base DNs for all public backends defined in the server.

filter

Required

A single-valued property that specifies the filter to use when searching for matching entries.

For example, to identify user entries, you can set a filter like "(|(objectClass=person)(objectClass=ubidPerson))".

Different environments could use different object classes for user entries.

named-sub-category-filter

Optional

A multivalued property that specifies filters that subcategorize matching entries using additional criteria. Use the form name:filter to set values for this property.

For example, if you set the filter property to find user entries in the server, you can use the named-sub-category-filter property to further categorize those entries into active users, inactive users, or users who have never authenticated.

In the following samples, these categories are determined based on the last time a user successfully authenticated, where the value 31536000 represents the number of seconds in 1 year:

active-users:(ds-pwp-state-json:jsonObjectFilterExtensibleMatch:={ "filterType":"lessThan", "field":"seconds-since-last-login", "value":31536000, "allowEquals":true })

inactive-users:(ds-pwp-state-json:jsonObjectFilterExtensibleMatch:={ "filterType":"greaterThan", "field":"seconds-since-last-login", "value":31536000, "allowEquals":false })

users-who-have-never-authenticated:(ds-pwp-state-json:jsonObjectFilterExtensibleMatch:={ "filterType":"negate", "negateFilter":{ "filterType":"containsField", "field":"last-login-time" } })

warning-threshold-minimum-count

Optional

A single-valued property that specifies a minimum threshold of matching entries to raise a warning alarm.

The number of matching entries is based on the combination of base DN and filter criteria.

The server doesn’t raise a warning alarm if the error-threshold-minimum-count threshold is also triggered.

error-threshold-minimum-count

Optional

A single-valued property that specifies a minimum threshold of matching entries to raise an error alarm.

The number of matching entries is based on the combination of base DN and filter criteria.

track-matching-entry-size

Optional

A Boolean property that specifies whether the server tracks the amount of space used to store information about the entries in the backend database.

Set the value to true to enable this property.

If this property is enabled, the entry counter processing gets more expensive because the server performs additional operations to calculate the size of each entry.

The matching entry size returned only represents the size of the encoded entry itself and doesn’t include any associated index records.

When configuring a set of criteria for the entry counter plugin, do the following:

  • Reference the name you gave the plugin using plugin-name.

  • Give the set of criteria a name using criteria-name.

  • Set the search criteria.

  • If needed, configure count thresholds and entry size reporting.

The plugin treats each set of criteria separately and returns a monitor entry for each set.

Here’s an example of how to configure a set of entry counter plugin criteria:

$ bin/dsconfig create-entry-counter-plugin-criteria \
    --plugin-name "Entry Counter" \
    --criteria-name Users \
    --set base-dn:dc=example,dc=com \
    --set filter:(objectClass=person)

Here’s an example of how to delete a set of entry counter plugin criteria:

$ bin/dsconfig delete-entry-counter-plugin-criteria \
    --plugin-name "Entry Counter" \
    --criteria-name Users

Consuming the output of the plugin

Monitor entries generated from the plugin criteria have a structural object class of ds-entry-counter-plugin-monitor-entry and can include the following attributes with values specific to their associated criteria.

Learn more about adding monitor entries to the administrative console.
Attribute Present in the entry? Description

criteria-name

Always

The name of the set of criteria specified for the monitor entry.

results-available

Always

Indicates whether the server has completed at least one internal search to identify the number of matching entries.

Use this attribute to determine whether entry count data will be available for the criteria.

At server startup, after the plugin is enabled, or after new criteria is defined, the server won’t have completed any entry counter searches, but it will still create a monitor entry for that criteria.

results-last-updated-time

Only with results

Indicates the time that the matching entry count results were last updated.

base-dn

Always

The included base DNs (or the default set, if none were configured).

filter

Always

The filter from the search criteria.

matching-entry-count

Only with results

The number of entries that match the criteria.

sub-category-filter-json

Always (if defined)

A multivalued JSON attribute with information about any subcategory filters defined in the criteria.

Each filter is represented by a separate value that contains the following JSON fields:

name

The name of the subcategory filter (always included).

filter

The filter used to subcategorize matching entries (always included).

count

The number of entries that match the filter (only with results).

warning-threshold-minimum-matching-entry-count

Always (if defined)

The minimum matching entry count threshold for the server to raise a warning alarm.

warning-threshold-reached

Only with results (if defined)

Indicates whether the number of entries that match the criteria is greater than or equal to the warning threshold.

percent-of-warning-threshold-reached

Only with results (if defined)

A percentage that indicates how close the number of matching entries is to reaching the warning threshold.

The value can be greater than 100% if the number of matching entries exceeds the warning threshold.

error-threshold-minimum-matching-entry-count

Always (if defined)

The minimum matching entry count threshold for the server to raise an error alarm.

error-threshold-reached

Only with results (if defined)

Indicates whether the number of entries that match the criteria is greater than or equal to the error threshold.

percent-of-error-threshold-reached

Only with results (if defined)

A percentage that indicates how close the number of matching entries is to reaching the error threshold.

The value can be greater than 100% if the number of matching entries exceeds the error threshold.

track-matching-entry-size

Always

Indicates whether the track-matching-entry-size property is enabled.

total-matching-entry-size-bytes

Only with results (if enabled)

The total size, in bytes, required to store all matching entries in the database.

average-matching-entry-size-bytes

Only with results (if enabled)

The average size, in bytes, required to store each matching entry in the database.

minimum-matching-entry-size-bytes

Only with results that include at least one matching entry (if enabled)

The size, in bytes, required to store the smallest matching entry in the database.

maximum-matching-entry-size-bytes

Only with results that include at least one matching entry (if enabled)

The size, in bytes, required to store the largest matching entry in the database.