<commit_before><?xml-stylesheet type="text/xml" href="page.xsl"?>
<!--
Copyright (c) 2007-2018 Pivotal Software, Inc.

All rights reserved. This program and the accompanying materials
are made available under the terms of the under the Apache License,
Version 2.0 (the "License”); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:doc="http://www.rabbitmq.com/namespaces/ad-hoc/doc"
      xmlns:x="http://www.rabbitmq.com/2011/extensions">
  <head>
    <title>Detecting Dead TCP Connections with Heartbeats and TCP Keepalives</title>
  </head>
  <body>
    <doc:section name="intro">
      <doc:heading>Introduction</doc:heading>
      <p>
        Network can fail in many ways, sometimes pretty subtle
        (e.g. high ratio packet loss).  Disrupted TCP connections take
        a moderately long time (about 11 minutes with default
        configuration on Linux, for example) to be detected by the
        operating system. AMQP 0-9-1 offers a <i>heartbeat</i> feature
        to ensure that the application layer promptly finds out about
        disrupted connections (and also completely unresponsive
        peers). Heartbeats also defend against certain network
        equipment which may terminate "idle" TCP connections when
        there is no activity on them for a certain period of time.
      </p>

      <p>
        TCP keepalives is a TCP stack feature that serves a similar
        purpose and can be very useful (possibly in combination with heartbeats)
        but requires kernel tuning in order to be practical with most operating
        systems and distributions.
      </p>
    </doc:section>


    <doc:section name="heartbeats-timeout">
      <doc:heading>Heartbeat Timeout Value</doc:heading>
      <p>
        The <code>heartbeat timeout</code> value defines after what period of time
        the peer TCP connection should be considered unreachable (down) by RabbitMQ
        and client libraries. This value is negotiated between the
        client and RabbitMQ server at the time of connection. The
        client must be configured to request heartbeats.
      </p>
      <p>
        The broker and client will attempt to negotiate
        heartbeats by default. When both values are non-0, the lower of the requested
        values will be used. If one side uses a zero value (attempts to disable heartbeats)
        but the other does not, the non-zero value will be used.
      </p>
      <p>
        The timeout is in seconds, and default value is <code>60</code>.
        Older releases used <code>580</code> seconds by default.
      </p>
    </doc:section>

    <doc:section name="heartbeats-delivery">
      <doc:heading>Heartbeat Frames</doc:heading>
      <p>
        Heartbeat frames are sent about every <code>heartbeat timeout / 2</code>
        seconds. This value is sometimes referred to as the <code>heartbeat interval</code>.
        After two missed heartbeats, the peer is considered
        to be unreachable. Different clients manifest this differently
        but the TCP connection will be closed. When a client detects
        that RabbitMQ node is unreachable due to a heartbeat, it needs
        to re-connect.
      </p>
      <p>
        It is important to not confuse the timeout value with the interval one.
        RabbitMQ <a href="/configure.html">configuration</a> exposes the timeout value,
        so do the officially supported client libraries. However some clients might expose
        the interval, potentially causing confusion.
      </p>
      <p>
        Any traffic (e.g. protocol operations, published messages, <a
        href="/confirms.html">acknowledgements</a>) counts for a valid
        heartbeat. Clients may choose to send heartbeat frames
        regardless of whether there was any other traffic on the
        connection but some only do it when necessary.
      </p>
    </doc:section>

    <doc:section name="disabling">
      <doc:heading>How to Disable Heartbeats</doc:heading>

      <p>
        Heartbeats can be disabled by setting the timeout interval to <code>0</code> on both client and server ends.
      </p>
      <p>
        Alternatively a very high (say, 1800 seconds) value can be used on both ends to effectively disable heartbeats
        as frame delivery will be too infrequent to make a practical difference.
      </p>
    </doc:section>

    <doc:section name="using-heartbeats-in-java">
      <doc:heading>Enabling Heartbeats with Java Client</doc:heading>
      <p>
        To configure the heartbeat timeout in the Java client, set it with
        <code>ConnectionFactory#setRequestedHeartbeat</code> before
        creating a connection:
      </p>

<pre class="sourcecode java">
ConnectionFactory cf = new ConnectionFactory();

// set the heartbeat timeout to 60 seconds
cf.setRequestedHeartbeat(60);
</pre>

      <p>
        Note that in case RabbitMQ server has a non-zero heartbeat timeout
        configured (which is the default in versions starting with 3.6.x),
        the client can only lower the value but not increase it.
      </p>
    </doc:section>

    <doc:section name="using-heartbeats-in-dotnet"><commit_msg>Mention that heartbeats should not be disabled unless TCP keepalives are used<commit_after><?xml-stylesheet type="text/xml" href="page.xsl"?>
<!--
Copyright (c) 2007-2018 Pivotal Software, Inc.

All rights reserved. This program and the accompanying materials
are made available under the terms of the under the Apache License,
Version 2.0 (the "License”); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:doc="http://www.rabbitmq.com/namespaces/ad-hoc/doc"
      xmlns:x="http://www.rabbitmq.com/2011/extensions">
  <head>
    <title>Detecting Dead TCP Connections with Heartbeats and TCP Keepalives</title>
  </head>
  <body>
    <doc:section name="intro">
      <doc:heading>Introduction</doc:heading>
      <p>
        Network can fail in many ways, sometimes pretty subtle
        (e.g. high ratio packet loss).  Disrupted TCP connections take
        a moderately long time (about 11 minutes with default
        configuration on Linux, for example) to be detected by the
        operating system. AMQP 0-9-1 offers a <i>heartbeat</i> feature
        to ensure that the application layer promptly finds out about
        disrupted connections (and also completely unresponsive
        peers). Heartbeats also defend against certain network
        equipment which may terminate "idle" TCP connections when
        there is no activity on them for a certain period of time.
      </p>

      <p>
        TCP keepalives is a TCP stack feature that serves a similar
        purpose and can be very useful (possibly in combination with heartbeats)
        but requires kernel tuning in order to be practical with most operating
        systems and distributions.
      </p>
    </doc:section>


    <doc:section name="heartbeats-timeout">
      <doc:heading>Heartbeat Timeout Value</doc:heading>
      <p>
        The <code>heartbeat timeout</code> value defines after what period of time
        the peer TCP connection should be considered unreachable (down) by RabbitMQ
        and client libraries. This value is negotiated between the
        client and RabbitMQ server at the time of connection. The
        client must be configured to request heartbeats.
      </p>
      <p>
        The broker and client will attempt to negotiate
        heartbeats by default. When both values are non-0, the lower of the requested
        values will be used. If one side uses a zero value (attempts to disable heartbeats)
        but the other does not, the non-zero value will be used.
      </p>
      <p>
        The timeout is in seconds, and default value is <code>60</code>.
        Older releases used <code>580</code> seconds by default.
      </p>
    </doc:section>

    <doc:section name="heartbeats-delivery">
      <doc:heading>Heartbeat Frames</doc:heading>
      <p>
        Heartbeat frames are sent about every <code>heartbeat timeout / 2</code>
        seconds. This value is sometimes referred to as the <code>heartbeat interval</code>.
        After two missed heartbeats, the peer is considered
        to be unreachable. Different clients manifest this differently
        but the TCP connection will be closed. When a client detects
        that RabbitMQ node is unreachable due to a heartbeat, it needs
        to re-connect.
      </p>
      <p>
        It is important to not confuse the timeout value with the interval one.
        RabbitMQ <a href="/configure.html">configuration</a> exposes the timeout value,
        so do the officially supported client libraries. However some clients might expose
        the interval, potentially causing confusion.
      </p>
      <p>
        Any traffic (e.g. protocol operations, published messages, <a
        href="/confirms.html">acknowledgements</a>) counts for a valid
        heartbeat. Clients may choose to send heartbeat frames
        regardless of whether there was any other traffic on the
        connection but some only do it when necessary.
      </p>
    </doc:section>

    <doc:section name="disabling">
      <doc:heading>How to Disable Heartbeats</doc:heading>

      <p>
        Heartbeats can be disabled by setting the timeout interval to <code>0</code> on both client and server ends.
      </p>
      <p>
        Alternatively a very high (say, 1800 seconds) value can be used on both ends to effectively disable heartbeats
        as frame delivery will be too infrequent to make a practical difference.
      </p>

      <p>
        Neither practice is recommended unless <a href="#tcp-keepalives">TCP keepalives</a> are used
        instead.
      </p>
    </doc:section>

    <doc:section name="using-heartbeats-in-java">
      <doc:heading>Enabling Heartbeats with Java Client</doc:heading>
      <p>
        To configure the heartbeat timeout in the Java client, set it with
        <code>ConnectionFactory#setRequestedHeartbeat</code> before
        creating a connection:
      </p>

<pre class="sourcecode java">
ConnectionFactory cf = new ConnectionFactory();

// set the heartbeat timeout to 60 seconds
cf.setRequestedHeartbeat(60);
</pre>

      <p>
        Note that in case RabbitMQ server has a non-zero heartbeat timeout
        configured (which is the default in versions starting with 3.6.x),
        the client can only lower the value but not increase it.
      </p>
    </doc:section>

    <doc:section name="using-heartbeats-in-dotnet">
{'fraction_non_alphanumeric': 0.07362714235746765, 'fraction_numerical': 0.007694998251136761, 'mean_word_length': 2.8690798376184032, 'pattern_counts': {'":': 0, '<': 157, '<?xml version=': 0, '>': 157, 'https://': 0, 'lorem ipsum': 0, 'www.': 8, 'xml': 10}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5282824', 'n_tokens_mistral': 3073, 'n_tokens_neox': 2917, 'n_words': 1341}