status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Website: cleanup for docs/agent/http/event.

This commit is contained in:
Ryan Breen 2015-02-09 11:24:23 -05:00
parent ebee060dcd
commit 6c9edb4eba
1 changed files with 15 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
website/source/docs/agent/http/event.html.markdown
View File

@ -20,15 +20,16 @@ The following endpoints are supported:
### <a name="event_fire"></a> /v1/event/fire/\<name\> ### <a name="event_fire"></a> /v1/event/fire/\<name\>
The fire endpoint is used to trigger a new user event. A user event The fire endpoint is used to trigger a new user event. A user event
needs a name, and optionally takes a number of parameters. needs a `name`, provided on the path. The endpoint also supports several
optional parameters on the query string.
By default, the agent's local datacenter is used, but another datacenter By default, the agent's local datacenter is used, but another datacenter
can be specified using the "?dc=" query parameter. can be specified using the "?dc=" query parameter.
The fire endpoint expects a PUT request, with an optional body. The fire endpoint expects a PUT request with an optional body.
The body contents are opaque to Consul, and become the "payload" The body contents are opaque to Consul and become the "payload"
of the event. Any names starting with the "_" prefix should be considered of the event. Names starting with the "_" prefix should be considered
reserved, and for Consul's internal use. reserved for Consul's internal use.
The `?node=`, `?service=`, and `?tag=` query parameters may optionally The `?node=`, `?service=`, and `?tag=` query parameters may optionally
be provided. They respectively provide a regular expression to filter be provided. They respectively provide a regular expression to filter
@ -49,7 +50,7 @@ The return code is 200 on success, along with a body like:
} }
``` ```
This is used to provide the ID of the newly fired event. The `ID` field uniquely identifies the newly fired event.
### <a name="event_list"></a> /v1/event/list ### <a name="event_list"></a> /v1/event/list
@ -57,33 +58,31 @@ This endpoint is hit with a GET and returns the most recent
events known by the agent. As a consequence of how the events known by the agent. As a consequence of how the
[event command](/docs/commands/event.html) works, each agent [event command](/docs/commands/event.html) works, each agent
may have a different view of the events. Events are broadcast using may have a different view of the events. Events are broadcast using
the [gossip protocol](/docs/internals/gossip.html), which means the [gossip protocol](/docs/internals/gossip.html), so
they have no total ordering, nor do they make a promise of delivery. they have no global ordering nor do they make a promise of delivery.
Additionally, each node applies the node, service and tag filters Additionally, each node applies the `node`, `service` and `tag` filters
locally before storing the event. This means the events at each agent locally before storing the event. This means the events at each agent
may be different depending on their configuration. may be different depending on their configuration.
This endpoint does allow for filtering on events by name by providing This endpoint allows for filtering on events by name by providing
the `?name=` query parameter. the `?name=` query parameter.
To support [watches](/docs/agent/watches.html), this endpoint supports To support [watches](/docs/agent/watches.html), this endpoint supports
blocking queries. However, the semantics of this endpoint are slightly blocking queries. However, the semantics of this endpoint are slightly
different. Most blocking queries provide a monotonic index, and block different. Most blocking queries provide a monotonic index and block
until a newer index is available. This can be supported as a consequence until a newer index is available. This can be supported as a consequence
of the total ordering of the [consensus protocol](/docs/internals/consensus.html). of the total ordering of the [consensus protocol](/docs/internals/consensus.html).
With gossip, there is no ordering, and instead `X-Consul-Index` maps With gossip, there is no ordering, and instead `X-Consul-Index` maps
to the newest event that matches the query. to the newest event that matches the query.
In practice, this means the index is only useful when used against a In practice, this means the index is only useful when used against a
single agent, and has no meaning globally. Because Consul defines single agent and has no meaning globally. Because Consul defines
the index as being opaque, clients should not be expecting a natural the index as being opaque, clients should not be expecting a natural
ordering either. ordering either.
Agents only buffer the most recent entries. The number of entries should Agents only buffer the most recent entries. The current buffer size is
not be depended upon, but currently defaults to 256. This value could 256, but this value could change in the future.
change in the future. The buffer should be large enough for most clients
and watches.
It returns a JSON body like this: It returns a JSON body like this: