---

   pmwebapi    ( 3 )

---

FULL TEXT SEARCH

The full text search capabilities provided by the pmsearch(1)
       command are also available through a REST API.  These queries
       provide access to an index over performance metric names,
       instances, instance domains and help text, suitable for a metric
       search engine, and in a fashion suited to efficient querying by
       any number of web applications.

       In order to use this functionality, the optional RediSearch
       module must be loaded in the redis-server at the time pmproxy is
       started, such that metrics, instances and help text it discovers
       can be automatically indexed.

   GET /search/text - pmSearchTextQuery(3)
       ┌───────────┬────────┬─────────────────────────────────────────────┐
       │Parameters │  Type  │                 Explanation                 │
       ├───────────┼────────┼─────────────────────────────────────────────┤
       │query      │ string │ Query string in pmsearch(1) format          │
       │highlight  │ fields │ Include matching markup in response fields  │
       │offset     │ number │ Result offset cursor for pagination         │
       │limit      │ number │ Maximum results to include in response      │
       │field      │ fields │ Queried fields (defaults to all)            │
       │return     │ fields │ Fields to actually return (defaults to all) │
       │type       │ types  │ Entity types to filter (defaults to all)    │
       └───────────┴────────┴─────────────────────────────────────────────┘
       Performs a text search query across metrics and instance domains
       - all forms of names and help texts.

       The mandatory search string is further described in pmsearch(1)
       and is passed to the server via the query parameter (HTTP GET).

         $ curl -s http://localhost:44322/search/text?query=halt | pmjson
         {
           "total": 2,
           "offset": 0,
           "limit": 10,
           "elapsed": 0.000504,
           "results": [
             {
               "name": "kvm.halt_exits",
               "type": "metric",
               "indom": "95.0.4",
               "oneline": "Number of guest exits due to halt calls.",
               "helptext": "This type of exit is usually seen when a guest is idle."
             },
             {
               "name": "kvm.halt_wakeup",
               "type": "metric",
               "indom": "95.0.6",
               "oneline": "Number of wakeups from a halt.",
             }
           ]
         }

       The available search entity types are metric, indom and instance.
       Query parameters highlight and field take name, oneline and
       helptext.

       Query parameter return takes name, type, oneline, helptext,
       indom.  There is typically both a name and help text associated
       with metrics. Contents of these are then matched against query.
       An instance domain has help text and a numeric identifier, while
       instances have a name only (which can be searched).

   GET /search/suggest - pmSearchTextSuggest(3)
       ┌───────────┬────────┬────────────────────────────────────┐
       │Parameters │  Type  │            Explanation             │
       ├───────────┼────────┼────────────────────────────────────┤
       │query      │ string │ Search query for search engine     │
       │limit      │ number │ Max results to include in response │
       └───────────┴────────┴────────────────────────────────────┘
       Provides search query suggestions, that is, metric and instance
       names.

       The mandatory search string is further described in pmsearch(1)
       and is passed to the server via the query parameter (HTTP GET).

         $ curl -s http://localhost:44322/search/suggest?query=disk&limit=4 | pmjson
         [
             "disk.all.avactive",
             "disk.all.aveq",
             "disk.all.blkread",
             "disk.all.blktotal"
         ]

   GET /search/indom - pmSearchTextInDom(3)
       ┌───────────┬────────┬─────────────────────────────────────┐
       │Parameters │  Type  │             Explanation             │
       ├───────────┼────────┼─────────────────────────────────────┤
       │query      │ string │ Target indom for search engine      │
       │offset     │ number │ Result offset cursor for pagination │
       │limit      │ number │ M results to include in response    │
       └───────────┴────────┴─────────────────────────────────────┘
       Provides all entities (instances, metrics) related to indom,
       including itself, that is passed to the server via the query
       parameter.

   GET /search/info - pmSearchInfo(3)
       Provides metrics relating to operation of the search engine, in
       particular showing document and text record counts.

         $ curl -s http://localhost:44322/search/info | pmjson
         {
             "docs": 1589,
             "terms": 3855,
             "records": 116831,
             "records_per_doc_avg": 73.52,
             "bytes_per_record_avg": 6.36,
             "inverted_sz_mb": 0.71,
             "inverted_cap_mb": 0.00,
             "inverted_cap_ovh": 0.00,
             "skip_index_size_mb": 0.00,
             "score_index_size_mb": 0.00,
             "offsets_per_term_avg": 9.41,
             "offset_bits_per_record_avg": 8.00
         }