github.com/outbrain/consul@v1.4.5/website/source/docs/commands/event.html.markdown.erb (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Commands: Event"
     4  sidebar_current: "docs-commands-event"
     5  description: |-
     6    The event command provides a mechanism to fire a custom user event to an entire datacenter. These events are opaque to Consul, but they can be used to build scripting infrastructure to do automated deploys, restart services, or perform any other orchestration action. Events can be handled by using a watch.
     7  ---
     8  
     9  # Consul Event
    10  
    11  Command: `consul event`
    12  
    13  The `event` command provides a mechanism to fire a custom user event to an
    14  entire datacenter. These events are opaque to Consul, but they can be used
    15  to build scripting infrastructure to do automated deploys, restart services,
    16  or perform any other orchestration action. Events can be handled by
    17  [using a watch](/docs/agent/watches.html).
    18  
    19  Under the hood, events are propagated using the [gossip protocol](/docs/internals/gossip.html).
    20  
    21  While the details are not important for using events, an understanding of
    22  the semantics is useful. The gossip layer will make a best-effort to deliver
    23  the event, but there is **no guaranteed delivery**. Unlike most Consul data, which is
    24  replicated using [consensus](/docs/internals/consensus.html), event data
    25  is purely peer-to-peer over gossip. This means it is not persisted and does
    26  not have a total ordering. In practice, this means you cannot rely on the
    27  order of message delivery. An advantage however is that events can still
    28  be used even in the absence of server nodes or during an outage.
    29  
    30  The underlying gossip also sets limits on the size of a user event
    31  message. It is hard to give an exact number, as it depends on various
    32  parameters of the event, but the payload should be kept very small
    33  (< 100 bytes). Specifying too large of an event will return an error.
    34  
    35  ## Usage
    36  
    37  Usage: `consul event [options] [payload]`
    38  
    39  The only required option is `-name` which specifies the event name. An optional
    40  payload can be provided as the final argument.
    41  
    42  #### API Options
    43  
    44  <%= partial "docs/commands/http_api_options_client" %>
    45  <%= partial "docs/commands/http_api_options_server" %>
    46  
    47  #### Command Options
    48  
    49  * `-name` - The name of the event.
    50  
    51  * `-node` - Regular expression to filter nodes which should evaluate the event.
    52  
    53  * `-service` - Regular expression to filter to only nodes with matching services.
    54  
    55  * `-tag` - Regular expression to filter to only nodes with a service that has
    56    a matching tag. This must be used with `-service`. As an example, you may
    57    do `-service mysql -tag secondary`.
    58