= Performance Statistics Reference
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

This page explains some of the statistics that Solr exposes.

There are two approaches to retrieving metrics. First, you can use the <<metrics-reporting.adoc#metrics-api,Metrics API>>, or you can enable JMX and get metrics from the <<mbean-request-handler.adoc#,MBean Request Handler>> or via an external tool such as JConsole. The below descriptions focus on retrieving the metrics using the Metrics API, but the metric names are the same if using the MBean Request Handler or an external tool.

These statistics are per core. When you are running in SolrCloud mode these statistics would co-relate to the performance of an individual replica.

== Request Handler Statistics

=== Update Request Handler

The update request handler is an endpoint to send data to Solr. We can see how many update requests are being fired, how fast is it performing, and other valuable information regarding requests.

*Registry & Path:* `solr.<core>:UPDATE./update`

You can request update request handler statistics with an API request such as `\http://localhost:8983/solr/admin/metrics?group=core&prefix=UPDATE`.

=== Search Request Handler

Can be useful to measure and track number of search queries, response times, etc. If you are not using the “select” handler then the path needs to be changed appropriately. Similarly if you are using the “sql” handler or “export” handler, the realtime handler “get”, or any other handler similar statistics can be found for that as well.

*Registry & Path*: `solr.<core>:QUERY./select`

You can request statistics for the `/select` request handler with an API request such as `\http://localhost:8983/solr/admin/metrics?group=core&prefix=QUERY./select`.

=== Commonly Used Stats for Request Handlers
All of the update and search request handlers will provide the following statistics.

*Request Times*

To get request times, specifically, you can send an API request such as:

* `\http://localhost:8983/solr/admin/metrics?group=core&prefix=UPDATE./update.requestTimes`
*  `\http://localhost:8983/solr/admin/metrics?group=core&prefix=QUERY./select.requestTimes`

// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed

[cols="25,75",options="header"]
|===
|Attribute |Description
|15minRate |Requests per second received over the past 15 minutes.
|5minRate |Requests per second received over the past 5 minutes.
|p75_ms |Request processing time for the request which belongs to the 75^th^ Percentile. E.g., if 100 requests are received, then the 75^th^ fastest request time will be reported by this statistic.
|p95_ms |Request processing time in milliseconds for the request which belongs to the 95^th^ Percentile. E.g., if 100 requests are received, then the 95^th^ fastest request time will be reported in this statistic.
|p999_ms |Request processing time in milliseconds for the request which belongs to the 99.9^th^ Percentile. E.g., if 1000 requests are received, then the 999^th^ fastest request time will be reported in this statistic.
|p99_ms |Request processing time in milliseconds for the request which belongs to the 99^th^ Percentile. E.g., if 100 requests are received, then the 99^th^ fastest request time will be reported in this statistic.
|count |Total number of requests made since the Solr core was first created.
|median_ms |Median of all the request processing time.
|meanRate |Average number of requests received per second since the Solr core was first created.
|===

*Errors and Other Times*

Other types of data such as errors and timeouts are also provided. These are available under different metric names. For example:

* `\http://localhost:8983/solr/admin/metrics?group=core&prefix=UPDATE./update.errors`
*  `\http://localhost:8983/solr/admin/metrics?group=core&prefix=QUERY./select.errors`

The table below shows the metric names and attributes to request:

[cols="30,70",options="header"]
|===
|Metric name | Description
|`QUERY./select.errors`
`UPDATE./update.errors` |Number of errors encountered by handler. In addition to a count of errors, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`QUERY./select.clientErrors`
`UPDATE./update.clientErrors` |Number of syntax or parse errors made by a client while making requests. In addition to a count of errors, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`QUERY./select.requests`
`UPDATE./update.requests` |Number of requests received by this handler.
|`QUERY./select.serverErrors`
`UPDATE./update.serverErrors` |Number of errors thrown by the server while executing the request. In addition to a count of errors, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`QUERY./select.timeouts`
`UPDATE./update.timeouts` |Number of responses received with partial results. In addition to a count of timeout events, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`QUERY./select.totalTime`
`UPDATE./update.totalTime` |The sum of all request processing times since the Solr process was started.
|`QUERY./select.handlerStart`
`UPDATE./update.handlerStart` |Epoch time when the handler was registered.
|===

*Distributed vs. Local Request Times*

Processing of a single distributed request in SolrCloud usually requires making several requests to
other nodes and other replicas. The common statistics listed above lump these timings together, even though
they are very different in nature, thus making it difficult to measure the latency of distributed and
local requests separately. Solr 8.4 introduced additional statistics that help to do this.

These metrics are structured the same as `requestTimes` and `totalTime` metrics above but they use
different full names, e.g., `QUERY./select.distrib.requestTimes` and `QUERY./select.local.requestTimes`.
The metrics under the `distrib` path correspond to the time it takes for a (potentially) distributed
request to complete all remote calls plus any local processing, and return the result to the caller.
The metrics under the `local` path correspond to the time it takes for a local call (non-distributed,
i.e., being processed only by the Solr core where the handler operates) to complete.

== Update Handler

This section has information on the total number of adds and how many commits have been fired against a Solr core.

*Registry & Path:* `solr.<core>:UPDATE.updateHandler`

You can get all update handler statistics shown in the table below with an API request such as `\http://localhost:8983/solr/admin/metrics?group=core&prefix=UPDATE.updateHandler`.

The following describes the specific statistics you can get:

// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed

[cols="40,60",options="header"]
|===
|Attribute |Description
|`UPDATE.updateHandler.adds` |Total number of “add” requests since last commit.
|`UPDATE.updateHandler.autoCommitMaxTime` |Maximum time between two auto-commits execution.
|`UPDATE.updateHandler.autoCommits` |Total number of auto-commits executed.
|`UPDATE.updateHandler.commits` | Number of total commits executed.

In addition to a count of commits, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`UPDATE.updateHandler.cumulativeAdds` |Number of “effective” additions executed over the lifetime. The counter is incremented when “add‘ command is executed while decremented when “rollback” is executed.

In addition to a count of adds, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`UPDATE.updateHandler.cumulativeDeletesById` |Number of document deletions executed by ID over the lifetime. The counter is incremented when “delete” command is executed and decremented when “rollback” is executed.

In addition to a count of deletes, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`UPDATE.updateHandler.cumulativeDeletesByQuery` |Number of document deletions executed by query over the lifetime. The counter is incremented when “delete” command is executed and decremented when “rollback” is executed.

In addition to a count of deletes, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`UPDATE.updateHandler.cumulativeErrors` |Number of error messages received while performing addition/deletion actions on documents over the lifetime.

In addition to a count of errors, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`UPDATE.updateHandler.deletesById` |Currently uncommitted deletions by ID.
|`UPDATE.updateHandler.deletesByQuery` |Currently uncommitted deletions by query.
|`UPDATE.updateHandler.docsPending` |Number of documents which are pending commit.
|`UPDATE.updateHandler.errors` |Number of error messages received while performing addition/deletion/commit/rollback actions on documents over the lifetime of the core.
|`UPDATE.updateHandler.expungeDeletes` |Number of commit commands issued with expunge deletes.

In addition to a count of expunge deletes, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`UPDATE.updateHandler.merges` | Number of index merges that have occurred.

In addition to a count of merges, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`UPDATE.updateHandler.optimizes` |Number of explicit optimize commands issued.

In addition to a count of optimizations, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`UPDATE.updateHandler.rollbacks` |Number of rollbacks executed.

In addition to a count of rollbacks, mean, 1 minute, 5 minute, and 15 minute rates are also available.
|`UPDATE.updateHandler.softAutoCommitMaxTime` |Maximum document ‘adds’ between two soft auto-commits.
|`UPDATE.updateHandler.softAutoCommits` |Number of soft commits executed.
|===

== Cache Statistics

=== Document Cache

This cache holds Lucene Document objects (the stored fields for each document). Since Lucene internal document IDs are transient, this cache cannot be auto-warmed.

*Registry and Path:* `solr.<core>:CACHE.searcher.documentCache`

You can get the statistics shown in the table below with an API request such as `\http://localhost:8983/solr/admin/metrics?group=core&prefix=CACHE.searcher.documentCache`.

=== Query Result Cache

This cache holds the results of previous searches: ordered lists of document IDs based on a query, a sort, and the range of documents requested

*Registry and Path:* `solr.<core>:CACHE.searcher.queryResultCache`

You can get the statistics shown in the table below with an API request such as `\http://localhost:8983/solr/admin/metrics?group=core&prefix=CACHE.searcher.queryResultCache`.

=== Filter Cache

This cache is used for filters for unordered sets of all documents that match a query.

*Registry and Path:* `solr.<core>:CACHE.searcher.filterCache`

You can get the statistics shown in the table below with an API request such as `\http://localhost:8983/solr/admin/metrics?group=core&prefix=CACHE.searcher.filterCache`.

=== Statistics for Caches

The following statistics are available for each of the caches mentioned above:

// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed

[cols="25,75",options="header"]
|===
|Attribute |Description
|cumulative_evictions |Number of cache evictions across all caches since this node has been running.
|cumulative_hitratio |Ratio of cache hits to lookups across all the caches since this node has been running.
|cumulative_hits |Number of cache hits across all the caches since this node has been running.
|cumulative_inserts |Number of cache insertions across all the caches since this node has been running.
|cumulative_lookups |Number of cache lookups across all the caches since this node has been running.
|evictions |Number of cache evictions for the current index searcher.
|hitratio |Ratio of cache hits to lookups for the current index searcher.
|hits |Number of hits for the current index searcher.
|inserts |Number of inserts into the cache.
|lookups |Number of lookups against the cache.
|size |Number of entries in the cache at that particular instance.
|warmupTime |Warm-up time for the registered index searcher in milliseconds. This time is taken in account for the “auto-warming” of caches.
|===

When eviction by heap usage is enabled, the following additional statistics are available for the Query Result Cache:

[cols="25,75",options="header"]
|===
|Attribute |Description
|maxRamMB |Maximum heap that should be used by the cache beyond which keys will be evicted.
|ramBytesUsed| Actual heap usage of the cache at that particular instance.
|evictionsRamUsage| Number of cache evictions for the current index searcher because heap usage exceeded maxRamMB.
|===

More information on Solr caches is available in the section <<query-settings-in-solrconfig.adoc#,Query Settings in SolrConfig>>.