Using the Search Consumption Dashboard

Each Coveo™ Cloud platform customer license agreement defines a set of usage limits and quotas. Administrators and other organization members with the required privileges can review these limits and their current statuses from the Settings panel in the Coveo Cloud administration console (see Coveo Cloud Organization Limits).

Search entitlement metrics measure actual search resources consumed by the end users of a solution. As such, those metrics deserve particular attention and can be visualized in their own dedicated Consumption Dashboard.

This article provides information to help administrators use the Consumption Dashboard to accurately monitor search entitlement metrics for their Coveo Cloud organization.

Query logs are kept for one year.

Introduction to License Entitlements

Usage of the Coveo™ Cloud platform by end users is licensed in two different ways, depending on the type of deployment:

  • Public facing or anonymous search interfaces generally use an entitlement based on queries per month (QPM) quotas which are reset on the first day of each month.
  • Authenticated search interfaces (private and public facing) can use one of several kinds of per-user entitlements, with no limit on the actual number of queries performed.

Please refer to your customer agreement for more details on the entitlements that apply to your contract.

Quick Start

Configure the Consumption Dashboard

If your license agreement includes search entitlements based on metrics other than queries per month (QPM), follow the steps below to properly set up your Consumption Dashboard.

In the Consumption Dashboard, for each row in the table:

  • If the Search Hub cell value corresponds to a search interface that should use a per-user entitlement, select the most appropriate Entitlement Metric cell value among Agent users, Intranet users, and Partner users.
  • Otherwise, select the Queries per Month (QPM) value in the Entitlement Metric cell (this is the default).

The Consumption Dashboard header should now be displaying accurate totals.

Consumption Dashboard Anatomy

You can access the Consumption Dashboard from the Settings panel in the Coveo Cloud administration console (see Search Consumption Dashboard Sub Tab).

The following annotated screen capture presents the different components of the Consumption Dashboard:

Consumption Dashboard

1

Header
Shows the running total for each entitlement metric currently accounted for in the dashboard. Also shows which month is selected (2).

2

Month selector
Click the back and forward arrows to navigate between recorded months to see how resource consumption is evolving in the solution.

When you access the dashboard, the current month is selected by default.

3

Filter box
Enter text to hide all rows whose Search Hub (4) value does not match the specified filter.

Filtering has no impact on the running totals shown in the header (1).

4

Search Hub column
Each search hub from which a combined total of more than ten normal and recommendation queries were performed during the selected month appears as a separate row in the table. This allows you to monitor resource consumption for each active search interface in the solution. Search hubs from which fewer queries have originated are not displayed to avoid polluting the table with superfluous information.

The total number of normal queries in the header (1) accounts for queries originating from the search hubs which are not displayed in the table. This means that there may be a slight discrepancy between this total and the one you can obtain by manually summing up the Normal Queries column in the table. Always consider the total in the header to be the accurate one.
5

Entitlement Metric column
When you first access the dashboard, the Queries per Month (QPM) entitlement metric is selected by default for each row. In this state, only recommendation, persistent, and normal queries are accounted for and totalized in the header (1).

To get accurate readings, select the appropriate entitlement metric for each row (see Queries per Month (QPM) and Agent, Intranet, and Partner Users).

Entitlement metric selections are automatically saved when you change them.

6

Users, Recommendation Queries, Persistent Queries, Normal Queries, and Queries per Second (QPS) columns
For a given row, if the Agent users, Intranet users, or Partner users value is selected in the Entitlement Metric cell (5), only the User cell is taken into account when computing running totals in the header (1). Otherwise, if the Queries per Month (QPM) value is selected, only the Recommendation Queries, Persistent Queries, and Normal Queries cells are taken into account for that row.

The Recommendation Queries and Persistent Queries columns appear in the table only if their value is greater than zero for at least one row in the table.

Queries per Month (QPM)

For search interfaces where end users are not individually identifiable, search entitlements are usually based on queries per month (QPM) quotas which are reset on the first day of each month.

In the Consumption Dashboard, you should select the Queries per month (QPM) entitlement metric for each search hub that is not using a per-user entitlement.

Technically speaking, a query is a Coveo Search API request that retrieves query results (i.e., a successful GET or POST HTTP request to /rest/search or /rest/search/v2). Other uses of the Search API such as requesting field-based or Coveo Machine Learning (Coveo ML) Query Suggestions (QS), generating search tokens, retrieving quick view data, etc. do not count as queries.

As a rule of thumb, most actions impacting the results or facets being displayed in a search interface count as queries.

The following actions count as queries:

  • Loading a search interface.
  • Switching to a different tab.
  • Submitting a search request from a search box.
  • Selecting a displayed query suggestion.
  • Changing the sort criterion or sort direction of search results.
  • Switching to a different page of search results.
  • Changing the number of results per page.
  • Selecting, deselecting, or excluding a facet value.
  • Changing the sort order or matching mode of a facet.
  • Using the search box at the bottom of a facet.
  • Navigating through search page states using browser history.
  • Expanding the result of a threaded conversation (e.g., Chatter).
  • Any custom code that triggers a search request.

The following actions do not count as queries:

  • Retrieving query suggestions while typing keywords in a search box.
  • Opening a quick view for a search result.

Three distinct types of queries are accounted for: normal queries, recommendation queries, and persistent queries. Each type of query counts against its own QPM quota. Any query that is neither a recommendation query nor a persistent query counts as a normal query.

Recommendation Queries

Recommendation queries originate from search interfaces powered by the Coveo ML Event Recommendations (ER) feature (see Coveo Machine Learning Event Recommendations Deployment Overview).

Recommendation queries count against the recommendations per month (RPM) quota (i.e., they do not count against the normal QPM quota).

Persistent Queries

Persistent queries are typically used to render relatively static, search-based content in a web page or application (see Rendering Static Content Using Persistent Queries).

Persistent queries count against the persistent queries per month (PQPM) quota (i.e., they do not count against the normal QPM quota).

The Coveo Cloud platform tracks the number of unique persistent queries executed each month (see Determining Persistent Query Uniqueness). In essence, this means that even if a given unique persistent query is executed a thousand times during a month, it still only counts once against the PQPM quota.

Agent, Intranet, and Partner Users

For search interfaces used by authenticated users (e.g., Intranet, agent insight panel, partner portal, etc.), search entitlement is based on the number of users, rather than on queries per month (QPM).

In the Consumption Dashboard, if your license agreement includes user-based search entitlements, you should typically select the Agent user, Intranet users, or Partner users entitlement metric for each appropriate search hub.

For search interfaces identified as per-user in the Consumption Dashboard, the Coveo Cloud platform tracks the number of distinct users that performed queries in the past months. The exact number of months depends on the entitlement:

User entitlement Period accounted for
Agent 3 months
Intranet 6 months
Partner 12 months
  • For someone to count as a user, they need to have performed a query in those time frames, depending on their type. The period accounted is related to their login frequency (e.g., agents log in more often than intranets and partners).

  • In the Consumption Dashboard, the number of users displayed for each hub is the distinct user counts for the selected month only. For this reason, this value can be lower than the one displayed in the header.

At any time, if the total number of users for an entitlement exceeds the maximum value allowed by the license, the license should be revised.

In this context, unless otherwise specified by the license, queries made from per-user search interfaces do not count against any of the QPM quotas.

What Is a User

A user is an identity passed when a query is made in a Coveo-powered search interface (e.g., search page, insight panel, etc.).

  • On an authenticated Intranet search page, each employee counts as a distinct user.
  • In the context of Coveo for Salesforce, each authenticated Salesforce user (e.g., support agent) using the search interface counts as a distinct user.

When performing a query using many identities, only the first one counts as a distinct user.

For example, if a query is run using the following identities:

  • john@doe.com (Email Security Provider)
  • some-custom-id (Custom Security Provider)

In that case, only john@doe.com would be counted in the user metrics.

Access a Resource Consumption Graph

You can access a graph to visualize resource consumption evolution for a given search hub over the selected month or the last 12 months. The graph, however, currently accounts for normal queries only.

In the Consumption Dashboard, click a search hub, and then in the Action bar, click View Graph.

Access Query Logs

You can access an HTML log file listing the queries made in the selected search hub during the selected month, along with their date and time, query expression, etc. (see Understanding the Query Expression). The information in this file can be useful when troubleshooting query usage.

In the Consumption Dashboard, click a search hub, and then, in the Action bar, click:

  • View Query Logs to open the log in a new browser tab.

OR

  • Download Query Logs to download the HTML log file.

Required Privileges

The following table indicates the privileges required to view or edit elements of the Consumption Dashboard and associated panels (see Privilege Management and Privilege Reference).

Action Service - Domain Required access level
View the Consumption Dashboard and related activities

Organization - Activities

Search - Search Usage Metrics

View
Edit the entitlement metric of a search hub

Organization - Activities

View

Search - Search Usage Metrics

Edit
View or download a list of the queries performed in a hub during a certain month

Organization - Activities

Search - Query Logs

Search - Search Usage Metrics

View