mirror of https://github.com/hashicorp/consul
Armon Dadgar
11 years ago
parent
a4343875c9
commit
dfde11212c
@ -1,96 +0,0 @@
|
||||
---
|
||||
layout: "intro"
|
||||
page_title: "Event Handlers"
|
||||
sidebar_current: "gettingstarted-eventhandlers"
|
||||
---
|
||||
|
||||
# Event Handlers
|
||||
|
||||
We've now seen how to start Serf agents and join them into a cluster.
|
||||
While this is cool to see on its own, the true power and utility of Serf
|
||||
is being able to react to membership changes and other events that Serf
|
||||
invokes. By specifying _event handlers_, Serf will invoke custom scripts
|
||||
whenever an event is received.
|
||||
|
||||
## Our First Event Handler
|
||||
|
||||
To start, let's create our first event handler. Create a shell script
|
||||
named `handler.sh` with the following contents and make sure that it is
|
||||
set to be executable (`chmod +x handler.sh`).
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
echo
|
||||
echo "New event: ${SERF_EVENT}. Data follows..."
|
||||
while read line; do
|
||||
printf "${line}\n"
|
||||
done
|
||||
```
|
||||
|
||||
This will be the script that we'll tell Serf to invoke for any event.
|
||||
The script outputs the event, which Serf puts into the `SERF_EVENT`
|
||||
environmental variable. The data for a Serf event always comes in via
|
||||
stdin, so the script then reads stdin and outputs any data it received.
|
||||
|
||||
By sending data to stdin, Serf works extremely well with standard Unix
|
||||
tools such as `grep`, `sed`, `awk`, etc. Shell commands work when specifying
|
||||
event handlers, so by using standard Unix methodologies, complex event
|
||||
handlers can often be built up without resorting to custom scripts.
|
||||
|
||||
## Specifying an Event Handler
|
||||
|
||||
With the event handler written, let's start an agent with that event handler.
|
||||
By setting the log-level to "debug", Serf will output the stdout/stderr
|
||||
of the event handlers, so we can see them being run:
|
||||
|
||||
```
|
||||
$ serf agent -log-level=debug -event-handler=handler.sh
|
||||
==> Starting Serf agent...
|
||||
==> Serf agent running!
|
||||
Node name: 'foobar'
|
||||
Bind addr: '0.0.0.0:7946'
|
||||
RPC addr: '127.0.0.1:7373'
|
||||
|
||||
==> Log data will now stream in as it occurs:
|
||||
|
||||
2013/10/22 06:54:04 [INFO] Serf agent starting
|
||||
2013/10/22 06:54:04 [INFO] serf: EventMemberJoin: mitchellh 127.0.0.1
|
||||
2013/10/22 06:54:04 [INFO] Serf agent started
|
||||
2013/10/22 06:54:04 [INFO] agent: Received event: member-join
|
||||
2013/10/22 06:54:04 [DEBUG] Event 'member-join' script output:
|
||||
New event: member-join. Data follows...
|
||||
mitchellh.local 127.0.0.1
|
||||
```
|
||||
|
||||
As you can see from the tail end of the output, the event script was
|
||||
executed and displayed the event that was run along with the data
|
||||
of that event.
|
||||
In this case, the event was a "member-join" event and the data was
|
||||
a single member, ourself.
|
||||
|
||||
In practice, an event script would do something like adding a web
|
||||
server to a load balancer, monitoring that node with Nagios, etc.
|
||||
|
||||
## Types of Events
|
||||
|
||||
There are currently four types of events that Serf invokes:
|
||||
|
||||
* `member-join` - One or more members have joined the cluster.
|
||||
* `member-leave` - One or more members have gracefully left the cluster.
|
||||
* `member-failed` - One or more members have failed, meaning that they
|
||||
didn't properly respond to ping requests.
|
||||
* `member-update` - One or members have updated, likely to update the
|
||||
associated tags
|
||||
* `user` - A custom user event, covered later in this guide.
|
||||
|
||||
## Multiple Event Scripts, Filtering, And More
|
||||
|
||||
For the purposes of introduction, we showed how to use a single event
|
||||
handler with Serf. This event handler responded to all events. However,
|
||||
the event handling system is actually far more robust: Serf is able
|
||||
to invoke multiple event handlers as well as invoke certain event handlers
|
||||
for only certain Serf events.
|
||||
|
||||
To learn more about these features, see the full documentation section
|
||||
of [event handlers](/docs/agent/event-handlers.html).
|
||||
@ -1,73 +0,0 @@
|
||||
---
|
||||
layout: "intro"
|
||||
page_title: "Custom User Events"
|
||||
sidebar_current: "gettingstarted-userevents"
|
||||
---
|
||||
|
||||
# Custom User Events
|
||||
|
||||
In addition to the standard membership-related events that Serf fires,
|
||||
Serf is able to propagate custom events across the cluster. Custom events
|
||||
are useful for tasks such as: triggering deploys, telling the cluster to
|
||||
restart, etc.
|
||||
|
||||
## Sending Custom Events
|
||||
|
||||
First, start a Serf agent so we can see the event being sent. Since we'll
|
||||
just be running a single agent, running `serf agent` by itself is fine.
|
||||
Then, to send a custom event, use the `serf event` command:
|
||||
|
||||
```
|
||||
$ serf event hello-there
|
||||
```
|
||||
|
||||
If you look at the output of `serf agent`, you should see that it received
|
||||
the user event:
|
||||
|
||||
```
|
||||
...
|
||||
2013/10/22 07:06:32 [INFO] agent: Received event: user-event: hello-there
|
||||
```
|
||||
|
||||
If the cluster were made up of multiple members, all of the members
|
||||
would have received this event, eventually.
|
||||
|
||||
Just like normal Serf events, event handlers can respond to user events.
|
||||
For example, if we had a "restart" custom event, we might create an
|
||||
event handler that restarts some server when it receives that event.
|
||||
|
||||
## Event Payloads
|
||||
|
||||
Events are not limited to just an event name. The event can also contain
|
||||
a payload: arbitrary data associated with the event. With our same agent
|
||||
running, let's deliver an event with a payload: `serf event my-name-is Mitchell`
|
||||
|
||||
In practice, event payloads can contain information such as the git commit
|
||||
to deploy if you're using Serf as a deployment tool. Or perhaps it contains
|
||||
some updated configuration to modify on the nodes. It can contain anything
|
||||
you'd like; it is up to the event handler to use it in some meaningful way.
|
||||
|
||||
## Custom Event Limitations
|
||||
|
||||
Custom events are delivered using the Serf gossip layer. The benefits of
|
||||
this approach is that you get completely decentralized messaging across
|
||||
your entire cluster that is fault tolerant. Even if a node is down, it will
|
||||
eventually receive that event message.
|
||||
|
||||
Due to the mechanics of gossip, custom
|
||||
events are highly scalable: Serf doesn't need to connect to each and every
|
||||
node to send the message, it only needs to connect to a handful, regardless
|
||||
of cluster size.
|
||||
|
||||
Custom events come with some trade-offs, however:
|
||||
|
||||
* Events are eventually consistent: Because events are delivered over
|
||||
gossip, the messages _eventually_ arrive at every node. In theory
|
||||
(and anecdotally in practice), the state of the cluster
|
||||
[converges rapidly](/docs/internals/simulator.html).
|
||||
|
||||
* Payload size is limited: Serf gossips via UDP, so the payload must fit
|
||||
within a single UDP packet (alongside any other data Serf sends). This
|
||||
limits the potential size of a payload to less than 1 KB. In practice,
|
||||
Serf limits the payload to a much smaller size.
|
||||
|
||||
Loading…
Reference in new issue