bosun.org@v0.0.0-20210513094433-e25bc3e69a1f/docs/api.md (about)

     1  ---
     2  layout: default
     3  title: API Documentation
     4  ---
     5  
     6  <div class="row">
     7  <div class="col-sm-3" >
     8    <div  class="sidebar" data-spy="affix" data-offset-top="0" data-offset-bottom="0" markdown="1">
     9   
    10   * Some TOC
    11   {:toc}
    12   
    13    </div>
    14  </div>
    15  
    16  <div class="doc-body col-sm-9" markdown="1">
    17  
    18  <p class="title h1">API Documentation</p>
    19  
    20  <div class="admonition warning">
    21  <p class="admonition-title">Warning</p>
    22  <p>Unfortunately, the API documentation has not been properly maintained. When this is fixed this warning will be removed. Much of this documentation is still useful, but for now it is best to check the <a href="https://github.com/bosun-monitor/bosun/blob/master/cmd/bosun/web/web.go">code in web.go</a> as the canonical reference. The handler's in <code>Listen</code> list all possible API routes.</p>
    23  </div>
    24  
    25  # Sending Data
    26  
    27  You can send your OpenTSDB data to Bosun. Bosun will index the data for
    28  its search feature, then relay the data to OpenTSDB. We recommend using
    29  [tsdbrelay](https://godoc.org/bosun.org/cmd/tsdbrelay) instead of directly
    30  sending to Bosun, as tsdbrelay will continue to send data if Bosun is
    31  restarting or down for any reason.
    32  
    33  ### /api/put
    34  
    35  Sending data to Bosun is done by treating your bosun host exactly
    36  like an OpenTSDB host. That is, POST to `/api/put` with formats described at
    37  [http://opentsdb.net/docs/build/html/api_http/put.html](http://opentsdb.net/docs/build/html/api_http/put.html).
    38  This data will be relayed to your OpenTSDB host.
    39  
    40  Data sent to this route will be indexed by Bosun for searching and autocomplete
    41  if it is typed correctly (for example, timestamp must be a number). [Full
    42  JSON description.](http://godoc.org/bosun.org/opentsdb#DataPoint)
    43  
    44  ### /api/index
    45  
    46  Only perform search indexing; do not relay to OpenTSDB. Accepts in same
    47  format as `/api/put`.
    48  
    49  ## Metadata
    50  
    51  Metadata (units, gauge/rate/counter, description, etc.) can be POST'd to the `/api/metadata/put` endpoint, with the request body as a JSON list of objects. The objects have the following properties:
    52  
    53  * **Metric** (string, optional): metric name
    54  * **Tags** (object, optional): key=value tag pairs
    55  * **Name** (string): metadata key name, for example: `desc`, `rate`, `unit`
    56  * **Value** (string): metadata value
    57  
    58  For example, to set the rate and unit of various metrics:
    59  
    60  ```
    61  [
    62    {"Metric":"win.disk.spltio","Name":"unit","Value":"per second"},
    63    {"Metric":"linux.mem.drop_pagecache","Name":"rate","Value":"counter"}
    64  ]
    65  ```
    66  
    67  ### rate
    68  
    69  To send metric rate information (used to specify if a metric is a gauge, rate, or counter), use `rate` as the Name and `gauge`, `rate`, or `counter` as the Value. Tags should be omitted.
    70  
    71  ### unit
    72  
    73  To send metric unit information (used to specify a metric's units), use `unit` as the Name and the unit value as Value (for example, `bytes`, `per second`). Tags should be omitted.
    74  
    75  # Querying Data
    76  
    77  Most endpoints support both GET and POST requests. Listed parameters may be
    78  specified as either URL parameters for GETs, or body parameters for POSTs. Any
    79  base64-encoded data should be encoded using the standard (not URL) encoding
    80  (and, thus, must be then URL-encoded).
    81  
    82  ## Search Endpoints
    83  
    84  All Search endpoints return a sorted json array. The search data is populated by
    85  observing data that has been relayed through the instance of bosun.
    86  
    87  ### /api/host
    88  
    89  Returns dashboard-ready data for all hosts.
    90  
    91  ### /api/metric
    92  
    93  Returns the metrics that have been relayed through bosun.
    94  
    95  ### /api/metric/tagkey
    96  
    97  Returns the metrics that have been relayed through bosun and their associated tag keys.
    98  
    99  ### /api/metric/{tagk}/{tagv}
   100  
   101  Returns the metrics that are available for the specified tagk/tagv pair. For
   102  example, you can see what metrics are available for host=server01.
   103  
   104  ### /api/tagk/{metric}
   105  
   106  Get all the available tagks that exist for the specified metric
   107  
   108  ### /api/tagv/{tagk}
   109  
   110  Get all the available tagvs for the specified tagk
   111  
   112  ### /api/tagv/{tagk}/{metric}
   113  
   114  Get all the available tagvs for the specific tagk and metric combination. You
   115  can optionally add a query string of tagk=tagv pairs to filter it even more. For
   116  example: `/api/tagv/iface/os.net.bytes?host=server01&direction=in`
   117  
   118  ### /api/metadata/get
   119  
   120  Get latest values of all metadata. Optional parameters:
   121  
   122  * **metric**: filter by metric name. Ex: `/api/metadata/get?metric=os.cpu`.
   123  * **tagk** and **tagv** pairs: filter by tag values; must be correctly paired;
   124  many supported. Ex: `/api/metadata/get?tagk=key1&tagv=val1&tagk=key2&tagv=val2`.
   125  
   126  ### /api/metadata/metrics
   127  
   128  Get unit, type (rate, gauge, counter) and description information for metrics.
   129  
   130  ## Expression, Rule, and Graph Endpoints
   131  
   132  ### /api/expr?q={expression}
   133  
   134  The expression endpoint takes a URL-encoded bosun expression expression and
   135  returns the results and OpenTSDB queries. The results includes a breakdown of
   136  the computations involved in the expression, the result or value, and the group
   137  (OpenTSDB's tagset) of the expression. The queries are the [OpenTSDB
   138  requests](http://godoc.org/opentsdb#Request)
   139  generated by the query.
   140  
   141  ### /api/egraph/{expression}.svg?[autods=true][&now=timestamp]
   142  
   143  Returns an SVG graph of the base64-encoded expression. `autods` may be set to
   144  enable auto downsampling. `now` can be set to a Unix timestamp in seconds to set
   145  the time of the expression (defaults to now).
   146  
   147  ### /api/graph
   148  
   149  Graphing endpoint. Examine a request for details.
   150  
   151  ### /api/rule
   152  
   153  Test execution for rules. Can execute at various times and intervals, output
   154  templates, and send test emails. Example a request for details.
   155  
   156  ## Dashboard Endpoints
   157  
   158  ### /api/action
   159  
   160  Used to acknowledge, close, or forget alerts. Examine a request for details.
   161  
   162  ### /api/alerts?[filter=filter]
   163  
   164  Returns a list of alert summaries matching the given filter (defaults to all).
   165  
   166  ### /api/health
   167  
   168  Returns an object of internal health checks. True values are good, falses are
   169  bad.
   170  
   171  `Note: all health checks stats are kept in memory and reset upon bosun restart`
   172  
   173  ### /api/run
   174  
   175  Runs a rule check. Returns an error if one is already running (either from the
   176  web interface or the normal scheduled check).
   177  
   178  ### /api/silence/clear
   179  
   180  Reads the `id` field of the JSON object passed in the POST body and removes that
   181  silence.
   182  
   183  ### /api/silence/get
   184  
   185  Returns all silences.
   186  
   187  ### /api/silence/set
   188  
   189  Tests or sets a silence. Examine a request for details.
   190  
   191  ### /api/status?[ak=key][&ak=key]
   192  
   193  Returns details about the given alert keys.
   194  
   195  ## Configuration Endpoints
   196  
   197  ### /api/backup
   198  
   199  Returns the state file for backup. The state file is guaranteed to be in a
   200  consistent state. This route is implemented by creating an in-memory copy
   201  of the state file, then streaming that to the response, so as to not block
   202  writes to the state file by other parts of bosun.
   203  
   204  ### /api/config
   205  
   206  Returns the current configuration that bosun is loaded with as text.
   207  
   208  ### /api/config_test
   209  
   210  Reads a configuration file from the POST body then checks it for for syntax
   211  errors. Returns an error if invalid.
   212  
   213  ### /api/reload
   214  
   215  Reloads the rule configuration when `{ "Reload": true }` is POST'd to the endpoint.
   216  
   217  </div>
   218  </div>