Profile API

edit

This 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

edit

Any _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" }
  }
}

Setting the top-level profile parameter to true will enable profiling for the search

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"
                    }
                 ]
              }
           ]
        }
     ]
  }
}

Search results are returned, but were omitted here for brevity

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).