WARNING: Version 2.3 of Elasticsearch has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
Profile API
editProfile API
editThis functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
The Profile API provides detailed timing information about the execution of individual components in a query. It gives the user insight into how queries are executed at a low level so that the user can understand why certain queries are slow, and take steps to improve their slow queries.
The output from the Profile API is very verbose, especially for complicated queries executed across many shards. Pretty-printing the response is recommended to help understand the output
The details provided by the Profile API directly expose Lucene class names and concepts, which means that complete interpretation of the results require fairly advanced knowledge of Lucene. This page attempts to give a crash-course in how Lucene executes queries so that you can use the Profile API to successfully diagnose and debug queries, but it is only an overview. For complete understanding, please refer to Lucene’s documentation and, in places, the code.
With that said, a complete understanding is often not required to fix a slow query. It is usually
sufficient to see that a particular component of a query is slow, and not necessarily understand why
the advance phase of that query is the cause, for example.
Usage
editAny _search request can be profiled by adding a top-level profile parameter:
curl -XGET 'localhost:9200/_search' -d '{
"profile": true,
"query" : {
"match" : { "message" : "search test" }
}
}
This will yield the following result:
{
"took": 25,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"failed": 0
},
"hits": {
"total": 1,
"max_score": 1,
"hits": [ ... ]
},
"profile": {
"shards": [
{
"id": "[htuC6YnSSSmKFq5UBt0YMA][test][0]",
"searches": [
{
"query": [
{
"query_type": "BooleanQuery",
"lucene": "message:search message:test",
"time": "15.52889800ms",
"breakdown": {
"score": 0,
"next_doc": 24495,
"match": 0,
"create_weight": 8488388,
"build_scorer": 7016015,
"advance": 0
},
"children": [
{
"query_type": "TermQuery",
"lucene": "message:search",
"time": "4.938855000ms",
"breakdown": {
"score": 0,
"next_doc": 18332,
"match": 0,
"create_weight": 2945570,
"build_scorer": 1974953,
"advance": 0
}
},
{
"query_type": "TermQuery",
"lucene": "message:test",
"time": "0.5016660000ms",
"breakdown": {
"score": 0,
"next_doc": 0,
"match": 0,
"create_weight": 170534,
"build_scorer": 331132,
"advance": 0
}
}
]
}
],
"rewrite_time": 185002,
"collector": [
{
"name": "SimpleTopScoreDocCollector",
"reason": "search_top_hits",
"time": "2.206529000ms"
}
]
}
]
}
]
}
}
Even for a simple query, the response is relatively complicated. Let’s break it down piece-by-piece before moving to more complex examples.
First, the overall structure of the profile response is as follows:
{
"profile": {
"shards": [
{
"id": "[htuC6YnSSSmKFq5UBt0YMA][test][0]",
"searches": [
{
"query": [...],
"rewrite_time": 185002,
"collector": [...]
}
]
}
]
}
}
|
A profile is returned for each shard that participated in the response, and is identified by a unique ID |
|
|
Each profile contains a section which holds details about the query execution |
|
|
Each profile has a single time representing the cumulative rewrite time |
|
|
Each profile also contains a section about the Lucene Collectors which run the search |
Because a search request may be executed against one or more shards in an index, and a search may cover
one or more indices, the top level element in the profile response is an array of shard objects.
Each shard object lists it’s id which uniquely identifies the shard. The ID’s format is
[nodeID][indexName][shardID].
The profile itself may consist of one or more "searches", where a search is a query executed against the underlying
Lucene index. Most Search Requests submitted by the user will only execute a single search against the Lucene index.
But occasionally multiple searches will be executed, such as including a global aggregation (which needs to execute
a secondary "match_all" query for the global context).
Inside each search object there will be two arrays of profiled information:
a query array and a collector array. In the future, more sections may be added, such as suggest, highlight,
aggregations, etc
There will also be a rewrite metric showing the total time spent rewriting the query (in nanoseconds).