15 lines
6.5 KiB
HTML
15 lines
6.5 KiB
HTML
<!DOCTYPE html> <html lang=en> <head> <meta charset=utf-8> <meta name=viewport content="width=device-width, initial-scale=1.0"> <meta name=description content=""> <meta name=author content=""> <title>Custom User Events - Serf</title> <link href="/stylesheets/bootstrap.min-82fe1490.css" media=screen rel=stylesheet /><link href="/stylesheets/main-e5014f86.css" media=screen rel=stylesheet /> <!--[if lt IE 9]><script src="/javascripts/html5shiv-310dd184.js"></script> <script src="/javascripts/respond.min-88c91176.js"></script><![endif]--> <script>
|
|
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
|
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
|
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
|
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
|
|
|
|
ga('create', 'UA-45101516-1', 'serfdom.io');
|
|
ga('send', 'pageview');
|
|
|
|
</script> </head> <body class="page-Custom User Events"> <div id=header> <div class=container> <a class="navbar-brand logo" href="/"> <span></span> </a> <a class="navbar-brand text rls-l" href="/">SERF</a> <ul class="buttons nav navbar-nav navbar-right rls-sb"> <li class=first><a href="/downloads.html">Download</a></li> <li><a href="https://github.com/hashicorp/serf">Github</a></li> </ul> <ul class="main-links nav navbar-nav navbar-right rls-sb"> <li><a href="/intro/index.html">Intro</a></li> <li><a href="/docs/index.html">Docs</a></li> <li><a href="/community.html">Community</a></li> </ul> </div> </div> <div class=container> <div class=col-md-4> <div class="docs-sidebar hidden-print affix-top" role=complementary> <ul class="nav docs-sidenav"> <li> <a href="/intro/index.html">What is Serf?</a> </li> <li> <a href="/intro/use-cases.html">Use Cases</a> </li> <li> <a href="/intro/vs-other-sw.html">Serf vs. Other Software</a> <ul class=nav> <li> <a href="/intro/vs-zookeeper.html">ZooKeeper, doozerd, etcd</a> </li> <li> <a href="/intro/vs-chef-puppet.html">Chef, Puppet, etc.</a> </li> <li> <a href="/intro/vs-fabric.html">Fabric</a> </li> <li> <a href="/intro/vs-custom.html">Custom Solutions</a> </li> </ul> </li> <li class=active> <a href="/intro/getting-started/install.html">Getting Started</a> <ul class=nav> <li> <a href="/intro/getting-started/install.html">Install Serf</a> </li> <li> <a href="/intro/getting-started/agent.html">Run the Agent</a> </li> <li> <a href="/intro/getting-started/join.html">Join a Cluster</a> </li> <li> <a href="/intro/getting-started/event-handlers.html">Event Handlers</a> </li> <li class=active> <a href="/intro/getting-started/user-events.html">Custom User Events</a> </li> <li> <a href="/intro/getting-started/next-steps.html">Next Steps</a> </li> </ul> </li> </ul> </div> </div> <div class=col-md-8 role=main> <div class=bs-docs-section> <h1 id=toc_0>Custom User Events</h1> <p>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.</p> <h2 id=toc_1>Sending Custom Events</h2> <p>First, start a Serf agent so we can see the event being sent. Since we'll just be running a single agent, running <code>serf agent</code> by itself is fine. Then, to send a custom event, use the <code>serf event</code> command:</p> <pre><code>$ serf event hello-there
|
|
</code></pre> <p>If you look at the output of <code>serf agent</code>, you should see that it received the user event:</p> <pre><code>...
|
|
2013/10/22 07:06:32 [INFO] agent: Received event: user-event: hello-there
|
|
</code></pre> <p>If the cluster were made up of multiple members, all of the members would have received this event, eventually.</p> <p>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.</p> <h2 id=toc_2>Event Payloads</h2> <p>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: <code>serf event my-name-is Mitchell</code></p> <p>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.</p> <h2 id=toc_3>Custom Event Limitations</h2> <p>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.</p> <p>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.</p> <p>Custom events come with some trade-offs, however:</p> <ul> <li><p>Events are eventually consistent: Because events are delivered over gossip, the messages <em>eventually</em> arrive at every node. In theory (and anecdotally in practice), the state of the cluster <a href="/docs/internals/simulator.html">converges rapidly</a>.</p></li> <li><p>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.</p></li> </ul> </div> </div> </div> <div id=footer> <div class=container> <div class=footer-links> <ul class="main-links nav navbar-nav rls-sb"> <li><a href="/intro/index.html">Intro</a></li> <li class=active><a href="/docs/index.html">Docs</a></li> <li><a href="/community.html">Community</a></li> </ul> <ul class="buttons nav navbar-nav rls-sb"> <li class=first><a href="/downloads.html">Download</a></li> <li><a href="https://github.com/hashicorp/serf">Github</a></li> </ul> </div> <div class=footer-logo> <span></span> </div> <div class="footer-hashi os"> <span>© 2013. A <a href="//www.hashicorp.com">HashiCorp</a> Project.</span> <a href="//www.hashicorp.com"><img src="/images/hashi-logo-s-3644fe63.png"></a> </div> </div> </div> <script src="javascripts/lib/d3.v3.min.js"></script> <script src="javascripts/app/deploy/site.js"></script> <script>
|
|
Serf.initialize();
|
|
</script> </body> </html> |