github.com/outbrain/consul@v1.4.5/website/source/api/event.html.md (about)

     1  ---
     2  layout: api
     3  page_title: Events - HTTP API
     4  sidebar_current: api-event
     5  description: |-
     6    The /event endpoints fire new events and to query the available events in
     7    Consul.
     8  ---
     9  
    10  # Event HTTP Endpoint
    11  
    12  The `/event` endpoints fire new events and to query the available events in
    13  Consul.
    14  
    15  ## Fire Event
    16  
    17  This endpoint triggers a new user event.
    18  
    19  | Method | Path                         | Produces                   |
    20  | ------ | ---------------------------- | -------------------------- |
    21  | `PUT`  | `/event/fire/:name`          | `application/json`         |
    22  
    23  The table below shows this endpoint's support for
    24  [blocking queries](/api/index.html#blocking-queries),
    25  [consistency modes](/api/index.html#consistency-modes),
    26  [agent caching](/api/index.html#agent-caching), and
    27  [required ACLs](/api/index.html#acls).
    28  
    29  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required  |
    30  | ---------------- | ----------------- | ------------- | ------------- |
    31  | `NO`             | `none`            | `none`        | `event:write` |
    32  
    33  ### Parameters
    34  
    35  - `name` `(string: <required>)` - Specifies the name of the event to fire. This
    36    is specified as part of the URL. This name must not start with an underscore,
    37    since those are reserved for Consul internally.
    38  
    39  - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
    40    the datacenter of the agent being queried. This is specified as part of the
    41    URL as a query parameter.
    42  
    43  - `node` `(string: "")` - Specifies a regular expression to filter by node name.
    44    This is specified as part of the URL as a query parameter.
    45  
    46  - `service` `(string: "")` - Specifies a regular expression to filter by service
    47    name. This is specified as part of the URL as a query parameter.
    48  
    49  - `tag` `(string: "")` - Specifies a regular expression to filter by tag. This
    50    is specified as part of the URL as a query parameter.
    51  
    52  ### Sample Payload
    53  
    54  The body contents are opaque to Consul and become the "payload" that is passed
    55  onto the receiver of the event.
    56  
    57  ```text
    58  Lorem ipsum dolor sit amet, consectetur adipisicing elit...
    59  ```
    60  
    61  ### Sample Request
    62  
    63  ```text
    64  $ curl \
    65      --request PUT \
    66      --data @payload \
    67      http://127.0.0.1:8500/v1/event/fire/my-event
    68  ```
    69  
    70  ### Sample Response
    71  
    72  ```json
    73  {
    74    "ID": "b54fe110-7af5-cafc-d1fb-afc8ba432b1c",
    75    "Name": "deploy",
    76    "Payload": null,
    77    "NodeFilter": "",
    78    "ServiceFilter": "",
    79    "TagFilter": "",
    80    "Version": 1,
    81    "LTime": 0
    82  }
    83  ```
    84  
    85  - `ID` is a unique identifier the newly fired event
    86  
    87  ## List Events
    88  
    89  This endpoint returns the most recent events (up to 256) known by the agent. As a
    90  consequence of how the [event command](/docs/commands/event.html) works, each
    91  agent may have a different view of the events. Events are broadcast using the
    92  [gossip protocol](/docs/internals/gossip.html), so they have no global ordering
    93  nor do they make a promise of delivery.
    94  
    95  | Method | Path                         | Produces                   |
    96  | ------ | ---------------------------- | -------------------------- |
    97  | `GET`  | `/event/list`                | `application/json`         |
    98  
    99  The table below shows this endpoint's support for
   100  [blocking queries](/api/index.html#blocking-queries),
   101  [consistency modes](/api/index.html#consistency-modes),
   102  [agent caching](/api/index.html#agent-caching), and
   103  [required ACLs](/api/index.html#acls).
   104  
   105  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
   106  | ---------------- | ----------------- | ------------- | ------------ |
   107  | `YES`            | `none`            | `none`        | `event:read` |
   108  
   109  ### Parameters
   110  
   111  - `name` `(string: <required>)` - Specifies the name of the event to filter.
   112    This is specified as part of the URL as a query parameter.
   113  
   114  - `node` `(string: "")` - Specifies a regular expression to filter by node name.
   115    This is specified as part of the URL as a query parameter.
   116  
   117  - `service` `(string: "")` - Specifies a regular expression to filter by service
   118    name. This is specified as part of the URL as a query parameter.
   119  
   120  - `tag` `(string: "")` - Specifies a regular expression to filter by tag. This
   121    is specified as part of the URL as a query parameter.
   122  
   123  ### Sample Request
   124  
   125  ```text
   126  $ curl \
   127      http://127.0.0.1:8500/v1/event/list
   128  ```
   129  
   130  ### Sample Response
   131  
   132  ```json
   133  [
   134    {
   135      "ID": "b54fe110-7af5-cafc-d1fb-afc8ba432b1c",
   136      "Name": "deploy",
   137      "Payload": "MTYwOTAzMA==",
   138      "NodeFilter": "",
   139      "ServiceFilter": "",
   140      "TagFilter": "",
   141      "Version": 1,
   142      "LTime": 19
   143    }
   144  ]
   145  ```
   146  
   147  ### Caveat
   148  
   149  The semantics of this endpoint's blocking queries are slightly different. Most
   150  blocking queries provide a monotonic index and block until a newer index is
   151  available. This can be supported as a consequence of the total ordering of the
   152  [consensus protocol](/docs/internals/consensus.html). With gossip, there is no
   153  ordering, and instead `X-Consul-Index` maps to the newest event that matches the
   154  query.
   155  
   156  In practice, this means the index is only useful when used against a single
   157  agent and has no meaning globally. Because Consul defines the index as being
   158  opaque, clients should not be expecting a natural ordering either.