--- title: Working with the entry counter plugin description: You can use the entry counter plugin to count and report the number of entries in the server that match your specified criteria. component: pingdirectory version: 11.0 page_id: pingdirectory:pingdirectory_server_administration_guide:pd_ds_entry_counter_plugin canonical_url: https://docs.pingidentity.com/pingdirectory/11.0/pingdirectory_server_administration_guide/pd_ds_entry_counter_plugin.html section_ids: how-the-entry-counter-plugin-works: How the entry counter plugin works how-to-set-up-the-entry-counter-plugin: How to set up the entry counter plugin creating-and-enabling-the-plugin: Creating and enabling the plugin configuring-a-set-of-entry-counter-criteria: Configuring a set of entry counter criteria consuming-the-output-of-the-plugin: Consuming the output of the plugin --- # 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 admin 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](#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](pd_ds_alarms_alerts_gauges.html#alarms).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 admin console](../monitoring_the_pingdirectory_suite_of_products/pd_proxy_monitor_admin_console.html). | | 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. |