This version of the OpenSearch documentation is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Profile

The Profile API provides timing information about the execution of individual components of a search request. Using the Profile API, you can debug slow requests and understand how to improve their performance. The Profile API does not measure the following:

  • Network latency
  • Time spent in the search fetch phase
  • Amount of time a request spends in queues
  • Idle time while merging shard responses on the coordinating node

The Profile API is a resource-consuming operation that adds overhead to search operations.

Example request

To use the Profile API, include the profile parameter set to true in the search request sent to the _search endpoint:

  1. GET /testindex/_search
  2. {
  3.   "profile": true,
  4.   "query" : {
  5.     "match" : { "title" : "wind" }
  6.   }
  7. }

copy

To turn on human-readable format, include the ?human=true query parameter in the request:

  1. GET /testindex/_search?human=true
  2. {
  3.   "profile": true,
  4.   "query" : {
  5.     "match" : { "title" : "wind" }
  6.   }
  7. }

copy

The response contains an additional time field with human-readable units, for example:

  1. "collector": [
  2.     {
  3.         "name": "SimpleTopScoreDocCollector",
  4.         "reason": "search_top_hits",
  5.         "time": "113.7micros",
  6.         "time_in_nanos": 113711
  7.     }
  8. ]

The Profile API response is verbose, so if you’re running the request through the curl command, include the ?pretty query parameter to make the response easier to understand.

Example response

The response contains profiling information:

Response

  1. {
  2.   "took": 21,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 1,
  6.     "successful": 1,
  7.     "skipped": 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total": {
  12.       "value": 2,
  13.       "relation": "eq"
  14.     },
  15.     "max_score": 0.19363807,
  16.     "hits": [
  17.       {
  18.         "_index": "testindex",
  19.         "_id": "1",
  20.         "_score": 0.19363807,
  21.         "_source": {
  22.           "title": "The wind rises"
  23.         }
  24.       },
  25.       {
  26.         "_index": "testindex",
  27.         "_id": "2",
  28.         "_score": 0.17225474,
  29.         "_source": {
  30.           "title": "Gone with the wind",
  31.           "description": "A 1939 American epic historical film"
  32.         }
  33.       }
  34.     ]
  35.   },
  36.   "profile": {
  37.     "shards": [
  38.       {
  39.         "id": "[LidyZ1HVS-u93-73Z49dQg][testindex][0]",
  40.         "inbound_network_time_in_millis": 0,
  41.         "outbound_network_time_in_millis": 0,
  42.         "searches": [
  43.           {
  44.             "query": [
  45.               {
  46.                 "type": "BooleanQuery",
  47.                 "description": "title:wind title:rise",
  48.                 "time_in_nanos": 2473919,
  49.                 "breakdown": {
  50.                   "set_min_competitive_score_count": 0,
  51.                   "match_count": 0,
  52.                   "shallow_advance_count": 0,
  53.                   "set_min_competitive_score": 0,
  54.                   "next_doc": 5209,
  55.                   "match": 0,
  56.                   "next_doc_count": 2,
  57.                   "score_count": 2,
  58.                   "compute_max_score_count": 0,
  59.                   "compute_max_score": 0,
  60.                   "advance": 9209,
  61.                   "advance_count": 2,
  62.                   "score": 20751,
  63.                   "build_scorer_count": 4,
  64.                   "create_weight": 1404458,
  65.                   "shallow_advance": 0,
  66.                   "create_weight_count": 1,
  67.                   "build_scorer": 1034292
  68.                 },
  69.                 "children": [
  70.                   {
  71.                     "type": "TermQuery",
  72.                     "description": "title:wind",
  73.                     "time_in_nanos": 813581,
  74.                     "breakdown": {
  75.                       "set_min_competitive_score_count": 0,
  76.                       "match_count": 0,
  77.                       "shallow_advance_count": 0,
  78.                       "set_min_competitive_score": 0,
  79.                       "next_doc": 3291,
  80.                       "match": 0,
  81.                       "next_doc_count": 2,
  82.                       "score_count": 2,
  83.                       "compute_max_score_count": 0,
  84.                       "compute_max_score": 0,
  85.                       "advance": 7208,
  86.                       "advance_count": 2,
  87.                       "score": 18666,
  88.                       "build_scorer_count": 6,
  89.                       "create_weight": 616375,
  90.                       "shallow_advance": 0,
  91.                       "create_weight_count": 1,
  92.                       "build_scorer": 168041
  93.                     }
  94.                   },
  95.                   {
  96.                     "type": "TermQuery",
  97.                     "description": "title:rise",
  98.                     "time_in_nanos": 191083,
  99.                     "breakdown": {
  100.                       "set_min_competitive_score_count": 0,
  101.                       "match_count": 0,
  102.                       "shallow_advance_count": 0,
  103.                       "set_min_competitive_score": 0,
  104.                       "next_doc": 0,
  105.                       "match": 0,
  106.                       "next_doc_count": 0,
  107.                       "score_count": 0,
  108.                       "compute_max_score_count": 0,
  109.                       "compute_max_score": 0,
  110.                       "advance": 0,
  111.                       "advance_count": 0,
  112.                       "score": 0,
  113.                       "build_scorer_count": 2,
  114.                       "create_weight": 188625,
  115.                       "shallow_advance": 0,
  116.                       "create_weight_count": 1,
  117.                       "build_scorer": 2458
  118.                     }
  119.                   }
  120.                 ]
  121.               }
  122.             ],
  123.             "rewrite_time": 192417,
  124.             "collector": [
  125.               {
  126.                 "name": "SimpleTopScoreDocCollector",
  127.                 "reason": "search_top_hits",
  128.                 "time_in_nanos": 77291
  129.               }
  130.             ]
  131.           }
  132.         ],
  133.         "aggregations": []
  134.       }
  135.     ]
  136.   }
  137. }

Response fields

The response includes the following fields.

FieldData typeDescription
profileObjectContains profiling information.
profile.shardsArray of objectsA search request can be executed against one or more shards in the index, and a search may involve one or more indexes. Thus, the profile.shards array contains profiling information for each shard that was involved in the search.
profile.shards.idStringThe shard ID of the shard in the [node-ID][index-name][shard-ID] format.
profile.shards.searchesArray of objectsA search represents a query executed against the underlying Lucene index. Most search requests execute a single search against a Lucene index, but some search requests can execute more than one search. For example, including a global aggregation results in a secondary match_all query for the global context. The profile.shards array contains profiling information about each search execution.
profile.shards.searches.queryArray of objectsProfiling information about the query execution.
profile.shards.searches.rewrite_timeIntegerAll Lucene queries are rewritten. A query and its children may be rewritten more than once, until the query stops changing. The rewriting process involves performing optimizations, such as removing redundant clauses or replacing a query path with a more efficient one. After the rewriting process, the original query may change significantly. The rewrite_time field contains the cumulative total rewrite time for the query and all its children, in nanoseconds.
profile.shards.searches.collectorArray of objectsProfiling information about the Lucene collectors that ran the search.
profile.shards.aggregationsArray of objectsProfiling information about the aggregation execution.

The query array

The query array contains objects with the following fields.

FieldData typeDescription
typeStringThe Lucene query type into which the search query was rewritten. Corresponds to the Lucene class name (which often has the same name in OpenSearch).
descriptionStringContains a Lucene explanation of the query. Helps differentiate queries with the same type.
time_in_nanosLongThe amount of time the query took to execute, in nanoseconds. In a parent query, the time is inclusive of the execution times of all the child queries.
breakdownObjectContains timing statistics about low-level Lucene execution.
childrenArray of objectsIf a query has subqueries (children), this field contains information about the subqueries.

The breakdown object

The breakdown object represents the timing statistics about low-level Lucene execution, broken down by method. Timings are listed in wall-clock nanoseconds and are not normalized. The breakdown timings are inclusive of all child times. The breakdown object comprises the following fields. All fields contain integer values.

FieldDescription
create_weightA Query object in Lucene is immutable. Yet, Lucene should be able to reuse Query objects in multiple IndexSearcher objects. Thus, Query objects need to keep temporary state and statistics associated with the index in which the query is executed. To achieve reuse, every Query object generates a Weight object, which keeps the temporary context (state) associated with the <IndexSearcher, Query> tuple. The create_weight field contains the amount of time spent creating the Weight object.
build_scorerA Scorer iterates over matching documents and generates a score for each document. The build_scorer field contains the amount of time spent generating the Scorer object. This does not include the time spent scoring the documents. The Scorer initialization time depends on the optimization and complexity of a particular query. The build_scorer parameter also includes the amount of time associated with caching, if caching is applicable and enabled for the query.
next_docThe next_doc Lucene method returns the document ID of the next document that matches the query. This method is a special type of the advance method and is equivalent to advance(docId() + 1). The next_doc method is more convenient for many Lucene queries. The next_doc field contains the amount of time required to determine the next matching document, which varies depending on the query type.
advanceThe advance method is a lower-level version of the next_doc method in Lucene. It also finds the next matching document but necessitates that the calling query perform additional tasks, such as identifying skips. Some queries, such as conjunctions (must clauses in Boolean queries), cannot use next_doc. For those queries, advance is timed.
matchFor some queries, document matching is performed in two steps. First, the document is matched approximately. Second, those documents that are approximately matched are examined through a more comprehensive process. For example, a phrase query first checks whether a document contains all terms in the phrase. Next, it verifies that the terms are in order (which is a more expensive process). The match field is non-zero only for those queries that use the two-step verification process.
scoreContains the time taken for a Scorer to score a particular document.
shallow_advanceContains the amount of time required to execute the advanceShallow Lucene method.
compute_max_scoreContains the amount of time required to execute the getMaxScore Lucene method.
set_min_competitive_scoreContains the amount of time required to execute the setMinCompetitiveScore Lucene method.
<method>_countContains the number of invocations of a <method>. For example, advance_count contains the number of invocations of the advance method. Different invocations of the same method occur because the method is called on different documents. You can determine the selectivity of a query by comparing counts in different query components.

The collector array

The collector array contains information about Lucene Collectors. A Collector is responsible for coordinating document traversal and scoring and collecting matching documents. Using Collectors, individual queries can record aggregation results and execute global queries or post-query filters.

FieldDescription
nameThe collector name. In the example response, the collector is a single SimpleTopScoreDocCollector—the default scoring and sorting collector.
reasonContains a description of the collector. For possible field values, see Collector reasons.
time_in_nanosA wall-clock time, including timing for all children.
childrenIf a collector has subcollectors (children), this field contains information about the subcollectors.

Collector times are calculated, combined, and normalized independently, so they are independent of query times.

Collector reasons

The following table describes all available collector reasons.

ReasonDescription
search_sortedA collector that scores and sorts documents. Present in most simple searches.
search_countA collector that counts the number of matching documents but does not fetch the source. Present when size: 0 is specified.
search_terminate_after_countA collector that searches for matching documents and terminates the search when it finds a specified number of documents. Present when the terminate_after_count query parameter is specified.
search_min_scoreA collector that returns matching documents that have a score greater than a minimum score. Present when the min_score parameter is specified.
search_multiA wrapper collector for other collectors. Present when search, aggregations, global aggregations, and post filters are combined in a single search.
search_timeoutA collector that stops running after a specified period of time. Present when a timeout parameter is specified.
aggregationA collector for aggregations that is run against the specified query scope. OpenSearch uses a single aggregation collector to collect documents for all aggregations.
global_aggregationA collector that is run against the global query scope. Global scope is different from a specified query scope, so in order to collect the entire dataset, a match_all query must be run.

Aggregations

To profile aggregations, send an aggregation request and provide the profile parameter set to true.

Example request: Global aggregation

  1. GET /opensearch_dashboards_sample_data_ecommerce/_search
  2. {
  3.   "profile": "true",
  4.   "size": 0,
  5.   "query": {
  6.     "match": { "manufacturer": "Elitelligence" }
  7.   },
  8.   "aggs": {
  9.     "all_products": {
  10.       "global": {}, 
  11.       "aggs": {     
  12.       "avg_price": { "avg": { "field": "taxful_total_price" } }
  13.       }
  14.     },
  15.     "elitelligence_products": { "avg": { "field": "taxful_total_price" } }
  16.   }
  17. }

copy

Example response: Global aggregation

The response contains profiling information:

Response

  1. {
  2.   "took": 10,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 1,
  6.     "successful": 1,
  7.     "skipped": 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total": {
  12.       "value": 1370,
  13.       "relation": "eq"
  14.     },
  15.     "max_score": null,
  16.     "hits": []
  17.   },
  18.   "aggregations": {
  19.     "all_products": {
  20.       "doc_count": 4675,
  21.       "avg_price": {
  22.         "value": 75.05542864304813
  23.       }
  24.     },
  25.     "elitelligence_products": {
  26.       "value": 68.4430200729927
  27.     }
  28.   },
  29.   "profile": {
  30.     "shards": [
  31.       {
  32.         "id": "[LidyZ1HVS-u93-73Z49dQg][opensearch_dashboards_sample_data_ecommerce][0]",
  33.         "inbound_network_time_in_millis": 0,
  34.         "outbound_network_time_in_millis": 0,
  35.         "searches": [
  36.           {
  37.             "query": [
  38.               {
  39.                 "type": "ConstantScoreQuery",
  40.                 "description": "ConstantScore(manufacturer:elitelligence)",
  41.                 "time_in_nanos": 1367487,
  42.                 "breakdown": {
  43.                   "set_min_competitive_score_count": 0,
  44.                   "match_count": 0,
  45.                   "shallow_advance_count": 0,
  46.                   "set_min_competitive_score": 0,
  47.                   "next_doc": 634321,
  48.                   "match": 0,
  49.                   "next_doc_count": 1370,
  50.                   "score_count": 0,
  51.                   "compute_max_score_count": 0,
  52.                   "compute_max_score": 0,
  53.                   "advance": 173250,
  54.                   "advance_count": 2,
  55.                   "score": 0,
  56.                   "build_scorer_count": 4,
  57.                   "create_weight": 132458,
  58.                   "shallow_advance": 0,
  59.                   "create_weight_count": 1,
  60.                   "build_scorer": 427458
  61.                 },
  62.                 "children": [
  63.                   {
  64.                     "type": "TermQuery",
  65.                     "description": "manufacturer:elitelligence",
  66.                     "time_in_nanos": 1174794,
  67.                     "breakdown": {
  68.                       "set_min_competitive_score_count": 0,
  69.                       "match_count": 0,
  70.                       "shallow_advance_count": 0,
  71.                       "set_min_competitive_score": 0,
  72.                       "next_doc": 470918,
  73.                       "match": 0,
  74.                       "next_doc_count": 1370,
  75.                       "score_count": 0,
  76.                       "compute_max_score_count": 0,
  77.                       "compute_max_score": 0,
  78.                       "advance": 172084,
  79.                       "advance_count": 2,
  80.                       "score": 0,
  81.                       "build_scorer_count": 4,
  82.                       "create_weight": 114041,
  83.                       "shallow_advance": 0,
  84.                       "create_weight_count": 1,
  85.                       "build_scorer": 417751
  86.                     }
  87.                   }
  88.                 ]
  89.               }
  90.             ],
  91.             "rewrite_time": 42542,
  92.             "collector": [
  93.               {
  94.                 "name": "MultiCollector",
  95.                 "reason": "search_multi",
  96.                 "time_in_nanos": 778406,
  97.                 "children": [
  98.                   {
  99.                     "name": "EarlyTerminatingCollector",
  100.                     "reason": "search_count",
  101.                     "time_in_nanos": 70290
  102.                   },
  103.                   {
  104.                     "name": "ProfilingAggregator: [elitelligence_products]",
  105.                     "reason": "aggregation",
  106.                     "time_in_nanos": 502780
  107.                   }
  108.                 ]
  109.               }
  110.             ]
  111.           },
  112.           {
  113.             "query": [
  114.               {
  115.                 "type": "ConstantScoreQuery",
  116.                 "description": "ConstantScore(*:*)",
  117.                 "time_in_nanos": 995345,
  118.                 "breakdown": {
  119.                   "set_min_competitive_score_count": 0,
  120.                   "match_count": 0,
  121.                   "shallow_advance_count": 0,
  122.                   "set_min_competitive_score": 0,
  123.                   "next_doc": 930803,
  124.                   "match": 0,
  125.                   "next_doc_count": 4675,
  126.                   "score_count": 0,
  127.                   "compute_max_score_count": 0,
  128.                   "compute_max_score": 0,
  129.                   "advance": 2209,
  130.                   "advance_count": 2,
  131.                   "score": 0,
  132.                   "build_scorer_count": 4,
  133.                   "create_weight": 23875,
  134.                   "shallow_advance": 0,
  135.                   "create_weight_count": 1,
  136.                   "build_scorer": 38458
  137.                 },
  138.                 "children": [
  139.                   {
  140.                     "type": "MatchAllDocsQuery",
  141.                     "description": "*:*",
  142.                     "time_in_nanos": 431375,
  143.                     "breakdown": {
  144.                       "set_min_competitive_score_count": 0,
  145.                       "match_count": 0,
  146.                       "shallow_advance_count": 0,
  147.                       "set_min_competitive_score": 0,
  148.                       "next_doc": 389875,
  149.                       "match": 0,
  150.                       "next_doc_count": 4675,
  151.                       "score_count": 0,
  152.                       "compute_max_score_count": 0,
  153.                       "compute_max_score": 0,
  154.                       "advance": 1167,
  155.                       "advance_count": 2,
  156.                       "score": 0,
  157.                       "build_scorer_count": 4,
  158.                       "create_weight": 9458,
  159.                       "shallow_advance": 0,
  160.                       "create_weight_count": 1,
  161.                       "build_scorer": 30875
  162.                     }
  163.                   }
  164.                 ]
  165.               }
  166.             ],
  167.             "rewrite_time": 8792,
  168.             "collector": [
  169.               {
  170.                 "name": "ProfilingAggregator: [all_products]",
  171.                 "reason": "aggregation_global",
  172.                 "time_in_nanos": 1310536
  173.               }
  174.             ]
  175.           }
  176.         ],
  177.         "aggregations": [
  178.           {
  179.             "type": "AvgAggregator",
  180.             "description": "elitelligence_products",
  181.             "time_in_nanos": 319918,
  182.             "breakdown": {
  183.               "reduce": 0,
  184.               "post_collection_count": 1,
  185.               "build_leaf_collector": 130709,
  186.               "build_aggregation": 2709,
  187.               "build_aggregation_count": 1,
  188.               "build_leaf_collector_count": 2,
  189.               "post_collection": 584,
  190.               "initialize": 4750,
  191.               "initialize_count": 1,
  192.               "reduce_count": 0,
  193.               "collect": 181166,
  194.               "collect_count": 1370
  195.             }
  196.           },
  197.           {
  198.             "type": "GlobalAggregator",
  199.             "description": "all_products",
  200.             "time_in_nanos": 1519340,
  201.             "breakdown": {
  202.               "reduce": 0,
  203.               "post_collection_count": 1,
  204.               "build_leaf_collector": 134625,
  205.               "build_aggregation": 59291,
  206.               "build_aggregation_count": 1,
  207.               "build_leaf_collector_count": 2,
  208.               "post_collection": 5041,
  209.               "initialize": 24500,
  210.               "initialize_count": 1,
  211.               "reduce_count": 0,
  212.               "collect": 1295883,
  213.               "collect_count": 4675
  214.             },
  215.             "children": [
  216.               {
  217.                 "type": "AvgAggregator",
  218.                 "description": "avg_price",
  219.                 "time_in_nanos": 775967,
  220.                 "breakdown": {
  221.                   "reduce": 0,
  222.                   "post_collection_count": 1,
  223.                   "build_leaf_collector": 98999,
  224.                   "build_aggregation": 33083,
  225.                   "build_aggregation_count": 1,
  226.                   "build_leaf_collector_count": 2,
  227.                   "post_collection": 2209,
  228.                   "initialize": 1708,
  229.                   "initialize_count": 1,
  230.                   "reduce_count": 0,
  231.                   "collect": 639968,
  232.                   "collect_count": 4675
  233.                 }
  234.               }
  235.             ]
  236.           }
  237.         ]
  238.       }
  239.     ]
  240.   }
  241. }

Example request: Non-global aggregation

  1. GET /opensearch_dashboards_sample_data_ecommerce/_search
  2. {
  3.   "size": 0,
  4.   "aggs": {
  5.     "avg_taxful_total_price": {
  6.       "avg": {
  7.         "field": "taxful_total_price"
  8.       }
  9.     }
  10.   }
  11. }

copy

Example response: Non-global aggregation

The response contains profiling information:

Response

  1. {
  2.   "took": 13,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 1,
  6.     "successful": 1,
  7.     "skipped": 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total": {
  12.       "value": 4675,
  13.       "relation": "eq"
  14.     },
  15.     "max_score": null,
  16.     "hits": []
  17.   },
  18.   "aggregations": {
  19.     "avg_taxful_total_price": {
  20.       "value": 75.05542864304813
  21.     }
  22.   },
  23.   "profile": {
  24.     "shards": [
  25.       {
  26.         "id": "[LidyZ1HVS-u93-73Z49dQg][opensearch_dashboards_sample_data_ecommerce][0]",
  27.         "inbound_network_time_in_millis": 0,
  28.         "outbound_network_time_in_millis": 0,
  29.         "searches": [
  30.           {
  31.             "query": [
  32.               {
  33.                 "type": "ConstantScoreQuery",
  34.                 "description": "ConstantScore(*:*)",
  35.                 "time_in_nanos": 1690820,
  36.                 "breakdown": {
  37.                   "set_min_competitive_score_count": 0,
  38.                   "match_count": 0,
  39.                   "shallow_advance_count": 0,
  40.                   "set_min_competitive_score": 0,
  41.                   "next_doc": 1614112,
  42.                   "match": 0,
  43.                   "next_doc_count": 4675,
  44.                   "score_count": 0,
  45.                   "compute_max_score_count": 0,
  46.                   "compute_max_score": 0,
  47.                   "advance": 2708,
  48.                   "advance_count": 2,
  49.                   "score": 0,
  50.                   "build_scorer_count": 4,
  51.                   "create_weight": 20250,
  52.                   "shallow_advance": 0,
  53.                   "create_weight_count": 1,
  54.                   "build_scorer": 53750
  55.                 },
  56.                 "children": [
  57.                   {
  58.                     "type": "MatchAllDocsQuery",
  59.                     "description": "*:*",
  60.                     "time_in_nanos": 770902,
  61.                     "breakdown": {
  62.                       "set_min_competitive_score_count": 0,
  63.                       "match_count": 0,
  64.                       "shallow_advance_count": 0,
  65.                       "set_min_competitive_score": 0,
  66.                       "next_doc": 721943,
  67.                       "match": 0,
  68.                       "next_doc_count": 4675,
  69.                       "score_count": 0,
  70.                       "compute_max_score_count": 0,
  71.                       "compute_max_score": 0,
  72.                       "advance": 1042,
  73.                       "advance_count": 2,
  74.                       "score": 0,
  75.                       "build_scorer_count": 4,
  76.                       "create_weight": 5041,
  77.                       "shallow_advance": 0,
  78.                       "create_weight_count": 1,
  79.                       "build_scorer": 42876
  80.                     }
  81.                   }
  82.                 ]
  83.               }
  84.             ],
  85.             "rewrite_time": 22000,
  86.             "collector": [
  87.               {
  88.                 "name": "MultiCollector",
  89.                 "reason": "search_multi",
  90.                 "time_in_nanos": 3672676,
  91.                 "children": [
  92.                   {
  93.                     "name": "EarlyTerminatingCollector",
  94.                     "reason": "search_count",
  95.                     "time_in_nanos": 78626
  96.                   },
  97.                   {
  98.                     "name": "ProfilingAggregator: [avg_taxful_total_price]",
  99.                     "reason": "aggregation",
  100.                     "time_in_nanos": 2834566
  101.                   }
  102.                 ]
  103.               }
  104.             ]
  105.           }
  106.         ],
  107.         "aggregations": [
  108.           {
  109.             "type": "AvgAggregator",
  110.             "description": "avg_taxful_total_price",
  111.             "time_in_nanos": 1973702,
  112.             "breakdown": {
  113.               "reduce": 0,
  114.               "post_collection_count": 1,
  115.               "build_leaf_collector": 199292,
  116.               "build_aggregation": 13584,
  117.               "build_aggregation_count": 1,
  118.               "build_leaf_collector_count": 2,
  119.               "post_collection": 6125,
  120.               "initialize": 6916,
  121.               "initialize_count": 1,
  122.               "reduce_count": 0,
  123.               "collect": 1747785,
  124.               "collect_count": 4675
  125.             }
  126.           }
  127.         ]
  128.       }
  129.     ]
  130.   }
  131. }

Response fields

The aggregations array contains aggregation objects with the following fields.

FieldData typeDescription
typeStringThe aggregator type. In the non-global aggregation example response, the aggregator type is AvgAggregator. Global aggregation example response contains a GlobalAggregator with an AvgAggregator child.
descriptionStringContains a Lucene explanation of the aggregation. Helps differentiate aggregations with the same type.
time_in_nanosLongThe amount of time taken to execute the aggregation, in nanoseconds. In a parent aggregation, the time is inclusive of the execution times of all the child aggregations.
breakdownObjectContains timing statistics about low-level Lucene execution.
childrenArray of objectsIf an aggregation has subaggregations (children), this field contains information about the subaggregations.
debugObjectSome aggregations return a debug object that describes the details of the underlying execution.

The breakdown object

The breakdown object represents the timing statistics about low-level Lucene execution, broken down by method. Each field in the breakdown object represents an internal Lucene method executed within the aggregation. Timings are listed in wall-clock nanoseconds and are not normalized. The breakdown timings are inclusive of all child times. The breakdown object is comprised of the following fields. All fields contain integer values.

FieldDescription
initializeContains the amount of time taken to execute the preCollection() callback method during AggregationCollectorManager creation.
build_leaf_collectorContains the time spent running the getLeafCollector() method of the aggregation, which creates a new collector to collect the given context.
collectContains the time spent collecting the documents into buckets.
post_collectionContains the time spent running the aggregation’s postCollection() callback method.
build_aggregationContains the time spent running the aggregation’s buildAggregations() method, which builds the results of this aggregation.
reduceContains the time spent in the reduce phase.
<method>_countContains the number of invocations of a <method>. For example, build_leaf_collector_count contains the number of invocations of the build_leaf_collector method.

Starting in OpenSearch 2.10, concurrent segment search allows each shard-level request to search segments in parallel during the query phase. If you enable the experimental concurrent segment search feature flag, the Profile API response will contain several additional fields with statistics about slices.

A slice is the unit of work that can be executed by a thread. Each query can be partitioned into multiple slices, with each slice containing one or more segments. All the slices can be executed either in parallel or in some order depending on the available threads in the pool.

In general, the max/min/avg slice time captures statistics across all slices for a timing type. For example, when profiling aggregations, the max_slice_time_in_nanos field in the aggregations section shows the maximum time consumed by the aggregation operation and its children across all slices.

Example response

The following is an example response for a concurrent search with three segment slices:

Response

  1. {
  2.   "took": 76,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 1,
  6.     "successful": 1,
  7.     "skipped": 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total": {
  12.       "value": 5,
  13.       "relation": "eq"
  14.     },
  15.     "max_score": 1,
  16.     "hits": [
  17.       ...
  18.     ]
  19.   },
  20.   "aggregations": {
  21.     ...
  22.   },
  23.   "profile": {
  24.     "shards": [
  25.       {
  26.         "id": "[Sn2zHhcMTRetEjXvppU8bA][idx][0]",
  27.         "inbound_network_time_in_millis": 0,
  28.         "outbound_network_time_in_millis": 0,
  29.         "searches": [
  30.           {
  31.             "query": [
  32.               {
  33.                 "type": "MatchAllDocsQuery",
  34.                 "description": "*:*",
  35.                 "time_in_nanos": 429246,
  36.                 "breakdown": {
  37.                   "set_min_competitive_score_count": 0,
  38.                   "match_count": 0,
  39.                   "shallow_advance_count": 0,
  40.                   "set_min_competitive_score": 0,
  41.                   "next_doc": 5485,
  42.                   "match": 0,
  43.                   "next_doc_count": 5,
  44.                   "score_count": 5,
  45.                   "compute_max_score_count": 0,
  46.                   "compute_max_score": 0,
  47.                   "advance": 3350,
  48.                   "advance_count": 3,
  49.                   "score": 5920,
  50.                   "build_scorer_count": 6,
  51.                   "create_weight": 429246,
  52.                   "shallow_advance": 0,
  53.                   "create_weight_count": 1,
  54.                   "build_scorer": 2221054
  55.                 }
  56.               }
  57.             ],
  58.             "rewrite_time": 12442,
  59.             "collector": [
  60.               {
  61.                 "name": "QueryCollectorManager",
  62.                 "reason": "search_multi",
  63.                 "time_in_nanos": 6786930,
  64.                 "reduce_time_in_nanos": 5892759,
  65.                 "max_slice_time_in_nanos": 5951808,
  66.                 "min_slice_time_in_nanos": 5798174,
  67.                 "avg_slice_time_in_nanos": 5876588,
  68.                 "slice_count": 3,
  69.                 "children": [
  70.                   {
  71.                     "name": "SimpleTopDocsCollectorManager",
  72.                     "reason": "search_top_hits",
  73.                     "time_in_nanos": 1340186,
  74.                     "reduce_time_in_nanos": 1084060,
  75.                     "max_slice_time_in_nanos": 457165,
  76.                     "min_slice_time_in_nanos": 433706,
  77.                     "avg_slice_time_in_nanos": 443332,
  78.                     "slice_count": 3
  79.                   },
  80.                   {
  81.                     "name": "NonGlobalAggCollectorManager: [histo]",
  82.                     "reason": "aggregation",
  83.                     "time_in_nanos": 5366791,
  84.                     "reduce_time_in_nanos": 4637260,
  85.                     "max_slice_time_in_nanos": 4526680,
  86.                     "min_slice_time_in_nanos": 4414049,
  87.                     "avg_slice_time_in_nanos": 4487122,
  88.                     "slice_count": 3
  89.                   }
  90.                 ]
  91.               }
  92.             ]
  93.           }
  94.         ],
  95.         "aggregations": [
  96.           {
  97.             "type": "NumericHistogramAggregator",
  98.             "description": "histo",
  99.             "time_in_nanos": 16454372,
  100.             "max_slice_time_in_nanos": 7342096,
  101.             "min_slice_time_in_nanos": 4413728,
  102.             "avg_slice_time_in_nanos": 5430066,
  103.             "breakdown": {
  104.               "min_build_leaf_collector": 4320259,
  105.               "build_aggregation_count": 3,
  106.               "post_collection": 9942,
  107.               "max_collect_count": 2,
  108.               "initialize_count": 3,
  109.               "reduce_count": 0,
  110.               "avg_collect": 146319,
  111.               "max_build_aggregation": 2826399,
  112.               "avg_collect_count": 1,
  113.               "max_build_leaf_collector": 4322299,
  114.               "min_build_leaf_collector_count": 1,
  115.               "build_aggregation": 3038635,
  116.               "min_initialize": 1057,
  117.               "max_reduce": 0,
  118.               "build_leaf_collector_count": 3,
  119.               "avg_reduce": 0,
  120.               "min_collect_count": 1,
  121.               "avg_build_leaf_collector_count": 1,
  122.               "avg_build_leaf_collector": 4321197,
  123.               "max_collect": 181266,
  124.               "reduce": 0,
  125.               "avg_build_aggregation": 954896,
  126.               "min_post_collection": 1236,
  127.               "max_initialize": 11603,
  128.               "max_post_collection": 5350,
  129.               "collect_count": 5,
  130.               "avg_post_collection": 2793,
  131.               "avg_initialize": 4860,
  132.               "post_collection_count": 3,
  133.               "build_leaf_collector": 4322299,
  134.               "min_collect": 78519,
  135.               "min_build_aggregation": 8543,
  136.               "initialize": 11971068,
  137.               "max_build_leaf_collector_count": 1,
  138.               "min_reduce": 0,
  139.               "collect": 181838
  140.             },
  141.             "debug": {
  142.               "total_buckets": 1
  143.             }
  144.           }
  145.         ]
  146.       }
  147.     ]
  148.   }
  149. }

Modified or added response fields

The following sections contain definitions of all modified or added response fields for concurrent segment search.

The query array

FieldDescription
time_in_nanosFor concurrent segment search, time_in_nanos is the cumulative amount of time taken to run all methods across all slices, in nanoseconds. This is not equivalent to the actual amount of time the query took to run because it does not take into account that multiple slices can run the methods in parallel.
breakdown.<method>For concurrent segment search, this field contains the total amount of time taken by all segments to run a method.
breakdown.<method>_countFor concurrent segment search, this field contains the total number of invocations of a <method> obtained by adding the number of method invocations for all segments.

The collector array

FieldDescription
time_in_nanosThe total elapsed time for this collector, in nanoseconds. For concurrent segment search, time_in_nanos is the total amount of time across all slices (max(slice_end_time) - min(slice_start_time)).
max_slice_time_in_nanosThe maximum amount of time taken by any slice, in nanoseconds.
min_slice_time_in_nanosThe minimum amount of time taken by any slice, in nanoseconds.
avg_slice_time_in_nanosThe average amount of time taken by any slice, in nanoseconds.
slice_countThe total slice count for this query.
reduce_time_in_nanosThe amount of time taken to reduce results for all slice collectors, in nanoseconds.

The aggregations array

FieldDescription
timein_nanosThe total elapsed time for this aggregation, in nanoseconds. For concurrent segment search, time_in_nanos is the total amount of time across all slices (max(slice_end_time) - min(slice_start_time)).
max_slice_time_in_nanosThe maximum amount of time taken by any slice to run an aggregation, in nanoseconds.
min_slice_time_in_nanosThe minimum amount of time taken by any slice to run an aggregation, in nanoseconds.
avg_slice_time_in_nanosThe average amount of time taken by any slice to run an aggregation, in nanoseconds.
<method>The total elapsed time across all slices (max(slice_end_time) - min(slice_start_time)). For example, for the collect method, it is the total time spent collecting documents into buckets across all slices.
max<method>The maximum amount of time taken by any slice to run an aggregation method.
min<method>The minimum amount of time taken by any slice to run an aggregation method.
avg<method>The average amount of time taken by any slice to run an aggregation method.
<method>countThe total method count across all slices. For example, for the collect method, it is the total number of invocations of this method needed to collect documents into buckets across all slices.
max<method>countThe maximum number of invocations of a <method> on any slice.
min<method>countThe minimum number of invocations of a <method> on any slice.
avg<method>_countThe average number of invocations of a <method> on any slice.