12 lines
7.4 KiB
HTML
12 lines
7.4 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>Commands: Event - 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-Commands: Event"> <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="/docs/index.html">Documentation Home</a> </li> <li> <a href="/docs/upgrading.html">Upgrading and Compatibility</a> <ul class=nav> <li> <a href="/docs/upgrading.html">Upgrading Serf</a> </li> <li> <a href="/docs/compatibility.html">Compatibility Promise</a> </li> </ul> </li> <li> <a href="/docs/internals/index.html">Serf Internals</a> <ul class=nav> <li> <a href="/docs/internals/gossip.html">Gossip Protocol</a> </li> <li> <a href="/docs/internals/security.html">Security Model</a> </li> <li> <a href="/docs/internals/simulator.html">Convergence Simulator</a> </li> </ul> </li> <li class=active> <a href="/docs/commands/index.html">Serf Commands (CLI)</a> <ul class=nav> <li> <a href="/docs/commands/agent.html">agent</a> </li> <li class=active> <a href="/docs/commands/event.html">event</a> </li> <li> <a href="/docs/commands/force-leave.html">force-leave</a> </li> <li> <a href="/docs/commands/join.html">join</a> </li> <li> <a href="/docs/commands/keygen.html">keygen</a> </li> <li> <a href="/docs/commands/leave.html">leave</a> </li> <li> <a href="/docs/commands/members.html">members</a> </li> <li> <a href="/docs/commands/monitor.html">monitor</a> </li> </ul> </li> <li> <a href="/docs/agent/basics.html">Serf Agent</a> <ul class=nav> <li> <a href="/docs/agent/basics.html">Running and Stopping</a> </li> <li> <a href="/docs/agent/options.html">Configuration</a> </li> <li> <a href="/docs/agent/event-handlers.html">Event Handlers</a> </li> <li> <a href="/docs/agent/encryption.html">Encryption</a> </li> <li> <a href="/docs/agent/rpc.html">RPC Protocol</a> </li> </ul> <li> <a href="/docs/roadmap.html">Roadmap</a> </li> </ul> </div> </div> <div class=col-md-8 role=main> <div class=bs-docs-section> <h1 id=toc_0>Serf Event</h1> <p>Command: <code>serf event</code></p> <p>The <code>serf event</code> command dispatches a custom user event into a Serf cluster, leveraging Serf's gossip layer for scalable broadcasting of the event to clusters of any size.</p> <p>Nodes in the cluster can listen for these custom events and react to them. Example use cases of custom events are to trigger deploys across web nodes by sending a "deploy" event, possibly with a commit payload. Another use case might be to send a "restart" event, asking the cluster members to restart.</p> <p>Ultimately, <code>serf event</code> is used to send custom events of your choosing that you can respond to in <em>any way</em> you want. The power in Serf's custom events is the scalability over other systems.</p> <h2 id=toc_1>Usage</h2> <p>Usage: <code>serf event [options] name [payload]</code></p> <p>The following command-line options are available for this command. Every option is optional:</p> <ul> <li><p><code>-coalesce=true/false</code> - Sets whether or not this event can be coalesced by Serf. By default this is set to true. Read the section on event coalescing for more information on what this means.</p></li> <li><p><code>-rpc-addr</code> - Address to the RPC server of the agent you want to contact to send this command. If this isn't specified, the command will contact "127.0.0.1:7373" which is the default RPC address of a Serf agent.</p></li> </ul> <h2 id=toc_2>Sending an Event</h2> <p>To send an event, use <code>serf event NAME</code> where NAME is the name of the event to send. This call will return immediately, and Serf will use its gossip layer to broadcast the event.</p> <p>An event may also contain a payload. You may specify the payload using the second parameter. For example: <code>serf event deploy 1234567890</code> would send the "deploy" event with "1234567890" as the payload.</p> <h2 id=toc_3>Receiving an Event</h2> <p>The events can be handled by registering an <a href="/docs/agent/event-handlers.html">event handler</a> with the Serf agent. The documentation for how the user event is dispatched is all contained within that linked page.</p> <h2 id=toc_4>Event Coalescing</h2> <p>By default, Serf coalesces events of the same name within a short time period. This means that if many events of the same name are received within a short amount of time, the event handler is only invoked once, with the last event of that name received during that time period.</p> <p>Event coalescense works great for idempotent events such as "restart" or events where only the last value in the payload really matters, like the commit in a "deploy" event. In these cases, things just work.</p> <p>Some events, however, shouldn't be coalesced. For example, if you had an event "queue" that queues some item, then you want to make sure all of those events are seen, even if many are sent in a short period of time. In this case, the <code>-coalesce=false</code> flag should be passed to the <code>serf event</code> command.</p> <p>If you send some events of the same name with coalescence enabled and some without, then only the events that have coalescing enabled will actually coalesce. The others will always be delivered.</p> </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> |