diff --git a/website/source/intro/getting-started/event-handlers.html.markdown b/website/source/intro/getting-started/event-handlers.html.markdown deleted file mode 100644 index 29c6432d02..0000000000 --- a/website/source/intro/getting-started/event-handlers.html.markdown +++ /dev/null @@ -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). diff --git a/website/source/intro/getting-started/user-events.html.markdown b/website/source/intro/getting-started/user-events.html.markdown deleted file mode 100644 index d29add9f66..0000000000 --- a/website/source/intro/getting-started/user-events.html.markdown +++ /dev/null @@ -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. - diff --git a/website/source/layouts/intro.erb b/website/source/layouts/intro.erb index c4acf1fc73..92e5102dd5 100644 --- a/website/source/layouts/intro.erb +++ b/website/source/layouts/intro.erb @@ -54,12 +54,12 @@ Join a Cluster - > - Event Handlers - + > + Services + - > - Custom User Events + > + Health Checks >