Profile API

The query section contains detailed timing of the query tree executed by Lucene on a particular shard. The overall structure of this query tree will resemble your original Elasticsearch query, but may be slightly (or sometimes very) different. It will also use similar but not always identical naming. Using our previous match query example, let’s analyze the query section:

"query": [
    {
       "type": "BooleanQuery",
       "description": "message:some message:number",
       "time_in_nanos": "1873811",
       "breakdown": {...},               
       "children": [
          {
             "type": "TermQuery",
             "description": "message:some",
             "time_in_nanos": "391943",
             "breakdown": {...}
          },
          {
             "type": "TermQuery",
             "description": "message:number",
             "time_in_nanos": "210682",
             "breakdown": {...}
          }
       ]
    }
]

Based on the profile structure, we can see that our match query was rewritten by Lucene into a BooleanQuery with two clauses (both holding a TermQuery). The type field displays the Lucene class name, and often aligns with the equivalent name in Elasticsearch. The description field displays the Lucene explanation text for the query, and is made available to help differentiating between parts of your query (e.g. both message:search and message:test are TermQuery’s and would appear identical otherwise.

The time_in_nanos field shows that this query took ~1.8ms for the entire BooleanQuery to execute. The recorded time is inclusive of all children.

The breakdown field will give detailed stats about how the time was spent, we’ll look at that in a moment. Finally, the children array lists any sub-queries that may be present. Because we searched for two values ("search test"), our BooleanQuery holds two children TermQueries. They have identical information (type, time, breakdown, etc). Children are allowed to have their own children.

The breakdown component lists detailed timing statistics about low-level Lucene execution:

"breakdown": {
   "score": 51306,
   "score_count": 4,
   "build_scorer": 2935582,
   "build_scorer_count": 1,
   "match": 0,
   "match_count": 0,
   "create_weight": 919297,
   "create_weight_count": 1,
   "next_doc": 53876,
   "next_doc_count": 5,
   "advance": 0,
   "advance_count": 0,
   "compute_max_score": 0,
   "compute_max_score_count": 0,
   "shallow_advance": 0,
   "shallow_advance_count": 0,
   "set_min_competitive_score": 0,
   "set_min_competitive_score_count": 0
}

Timings are listed in wall-clock nanoseconds and are not normalized at all. All caveats about the overall time_in_nanos apply here. The intention of the breakdown is to give you a feel for A) what machinery in Lucene is actually eating time, and B) the magnitude of differences in times between the various components. Like the overall time, the breakdown is inclusive of all children times.

The meaning of the stats are as follows:

The Collectors portion of the response shows high-level execution details. Lucene works by defining a "Collector" which is responsible for coordinating the traversal, scoring, and collection of matching documents. Collectors are also how a single query can record aggregation results, execute unscoped "global" queries, execute post-query filters, etc.

Looking at the previous example:

"collector": [
   {
      "name": "SimpleTopScoreDocCollector",
      "reason": "search_top_hits",
      "time_in_nanos": "32273"
   }
]

We see a single collector named SimpleTopScoreDocCollector wrapped into CancellableCollector. SimpleTopScoreDocCollector is the default "scoring and sorting" Collector used by Elasticsearch. The reason field attempts to give a plain English description of the class name. The time_in_nanos is similar to the time in the Query tree: a wall-clock time inclusive of all children. Similarly, children lists all sub-collectors. The CancellableCollector that wraps SimpleTopScoreDocCollector is used by Elasticsearch to detect if the current search was cancelled and stop collecting documents as soon as it occurs.

It should be noted that Collector times are independent from the Query times. They are calculated, combined, and normalized independently! Due to the nature of Lucene’s execution, it is impossible to "merge" the times from the Collectors into the Query section, so they are displayed in separate portions.

For reference, the various collector reasons are:

All queries in Lucene undergo a "rewriting" process. A query (and its sub-queries) may be rewritten one or more times, and the process continues until the query stops changing. This process allows Lucene to perform optimizations, such as removing redundant clauses, replacing one query for a more efficient execution path, etc. For example a Boolean → Boolean → TermQuery can be rewritten to a TermQuery, because all the Booleans are unnecessary in this case.

The rewriting process is complex and difficult to display, since queries can change drastically. Rather than showing the intermediate results, the total rewrite time is simply displayed as a value (in nanoseconds). This value is cumulative and contains the total time for all queries being rewritten.

To demonstrate a slightly more complex query and the associated results, we can profile the following query:

GET /twitter/_search
{
  "profile": true,
  "query": {
    "term": {
      "user": {
        "value": "test"
      }
    }
  },
  "aggs": {
    "my_scoped_agg": {
      "terms": {
        "field": "likes"
      }
    },
    "my_global_agg": {
      "global": {},
      "aggs": {
        "my_level_agg": {
          "terms": {
            "field": "likes"
          }
        }
      }
    }
  },
  "post_filter": {
    "match": {
      "message": "some"
    }
  }
}

This example has:

The API returns the following result:

{
   ...
   "profile": {
         "shards": [
            {
               "id": "[P6-vulHtQRWuD4YnubWb7A][test][0]",
               "searches": [
                  {
                     "query": [
                        {
                           "type": "TermQuery",
                           "description": "message:some",
                           "time_in_nanos": "409456",
                           "breakdown": {
                              "score": 0,
                              "build_scorer_count": 1,
                              "match_count": 0,
                              "create_weight": 31584,
                              "next_doc": 0,
                              "match": 0,
                              "create_weight_count": 1,
                              "next_doc_count": 2,
                              "score_count": 1,
                              "build_scorer": 377872,
                              "advance": 0,
                              "advance_count": 0,
                              "compute_max_score": 0,
                              "compute_max_score_count": 0,
                              "shallow_advance": 0,
                              "shallow_advance_count": 0,
                              "set_min_competitive_score": 0,
                              "set_min_competitive_score_count": 0
                           }
                        },
                        {
                           "type": "TermQuery",
                           "description": "user:test",
                           "time_in_nanos": "303702",
                           "breakdown": {
                              "score": 0,
                              "build_scorer_count": 1,
                              "match_count": 0,
                              "create_weight": 185215,
                              "next_doc": 5936,
                              "match": 0,
                              "create_weight_count": 1,
                              "next_doc_count": 2,
                              "score_count": 1,
                              "build_scorer": 112551,
                              "advance": 0,
                              "advance_count": 0,
                              "compute_max_score": 0,
                              "compute_max_score_count": 0,
                              "shallow_advance": 0,
                              "shallow_advance_count": 0,
                              "set_min_competitive_score": 0,
                              "set_min_competitive_score_count": 0
                           }
                        }
                     ],
                     "rewrite_time": 7208,
                     "collector": [
                        {
                          "name": "MultiCollector",
                          "reason": "search_multi",
                          "time_in_nanos": 1820,
                          "children": [
                            {
                              "name": "FilteredCollector",
                              "reason": "search_post_filter",
                              "time_in_nanos": 7735,
                              "children": [
                                {
                                  "name": "SimpleTopScoreDocCollector",
                                  "reason": "search_top_hits",
                                  "time_in_nanos": 1328
                                }
                              ]
                            },
                            {
                              "name": "MultiBucketCollector: [[my_scoped_agg, my_global_agg]]",
                              "reason": "aggregation",
                              "time_in_nanos": 8273
                            }
                          ]
                        }
                     ]
                  }
               ],
               "aggregations": [...] 
            }
         ]
      }
}

As you can see, the output is significantly more verbose than before. All the major portions of the query are represented:

The Collector tree is fairly straightforward, showing how a single CancellableCollector wraps a MultiCollector which also wraps a FilteredCollector to execute the post_filter (and in turn wraps the normal scoring SimpleCollector), a BucketCollector to run all scoped aggregations.

A special note needs to be made about the MultiTermQuery class of queries. This includes wildcards, regex, and fuzzy queries. These queries emit very verbose responses, and are not overly structured.

Essentially, these queries rewrite themselves on a per-segment basis. If you imagine the wildcard query b*, it technically can match any token that begins with the letter "b". It would be impossible to enumerate all possible combinations, so Lucene rewrites the query in context of the segment being evaluated, e.g., one segment may contain the tokens [bar, baz], so the query rewrites to a BooleanQuery combination of "bar" and "baz". Another segment may only have the token [bakery], so the query rewrites to a single TermQuery for "bakery".

Due to this dynamic, per-segment rewriting, the clean tree structure becomes distorted and no longer follows a clean "lineage" showing how one query rewrites into the next. At present time, all we can do is apologize, and suggest you collapse the details for that query’s children if it is too confusing. Luckily, all the timing statistics are correct, just not the physical layout in the response, so it is sufficient to just analyze the top-level MultiTermQuery and ignore its children if you find the details too tricky to interpret.

Hopefully this will be fixed in future iterations, but it is a tricky problem to solve and still in-progress. :)

The breakdown component lists detailed timing statistics about low-level Lucene execution:

"breakdown": {
  "reduce": 0,
  "reduce_count": 0,
  "build_aggregation": 49765,
  "build_aggregation_count": 300,
  "initialize": 52785,
  "initialize_count": 300,
  "reduce_count": 0,
  "collect": 3155490036,
  "collect_count": 1800
}

Timings are listed in wall-clock nanoseconds and are not normalized at all. All caveats about the overall time apply here. The intention of the breakdown is to give you a feel for A) what machinery in Elasticsearch is actually eating time, and B) the magnitude of differences in times between the various components. Like the overall time, the breakdown is inclusive of all children times.

The meaning of the stats are as follows:

Like any profiler, the Profile API introduces a non-negligible overhead to search execution. The act of instrumenting low-level method calls such as collect, advance, and next_doc can be fairly expensive, since these methods are called in tight loops. Therefore, profiling should not be enabled in production settings by default, and should not be compared against non-profiled query times. Profiling is just a diagnostic tool.

There are also cases where special Lucene optimizations are disabled, since they are not amenable to profiling. This could cause some queries to report larger relative times than their non-profiled counterparts, but in general should not have a drastic effect compared to other components in the profiled query.