src/components/artemis/documentation/previous/2.52.0/data-retention.html

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.23">
<link rel="icon" type="image/png" href="images/favicon.png">
<title>Data Retention</title>
<link rel="stylesheet" href="css/asciidoctor.css">
<link rel="stylesheet" href="css/font-awesome.css">
<link rel="stylesheet" href="css/rouge-github.css">
<script>
    document.addEventListener("DOMContentLoaded", function() {
        const pathSegments = window.location.pathname.split('/');
        if (window.location.hostname == "artemis.apache.org" && pathSegments[pathSegments.length - 2] != "latest") {
            var message = document.createElement("div");
            message.style.margin = "20px";
            message.style.textAlign = "center";
            message.style.backgroundColor = "#FFFFE0";
            message.textContent = "Please be aware that this documentation is out of date. ";

            var link = document.createElement("a");
            link.href = "../../latest";
            link.textContent = "Here is the latest documentation.";
            message.appendChild(link);

            document.body.insertBefore(message, document.body.firstChild);
        }
    });
</script>
</head>
<body class="book toc2 toc-left">
<div id="header">
<h1>Data Retention</h1>
<div id="toc" class="toc2">
<div id="toctitle"><a href="index.html">User Manual for 2.52.0</a></div>
<ul class="sectlevel3">
<li><a href="#paging-and-large-messages">1. Paging and Large Messages</a></li>
<li><a href="#non-persistent-messages">2. Non Persistent Messages</a></li>
<li><a href="#recovering-data-from-retention">1. Recovering data from retention</a>
<ul class="sectlevel2">
<li><a href="#cli-recover-operation">1.1. CLI recover operation</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>If you enable <code>journal-retention-directory</code> in <code>broker.xml</code> a copy of every journal file used by the broker will be kept in this folder.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt">&lt;configuration...&gt;</span>
   <span class="nt">&lt;core...&gt;</span>
      ...
      <span class="nt">&lt;journal-retention-directory</span> <span class="na">unit=</span><span class="s">"DAYS"</span> <span class="na">period=</span><span class="s">"365"</span> <span class="na">storage-limit=</span><span class="s">"10G"</span><span class="nt">&gt;</span>history<span class="nt">&lt;/journal-retention-directory&gt;</span>
      ...
   <span class="nt">&lt;/core&gt;</span>
<span class="nt">&lt;/configuration&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The broker will keep a copy of each generated journal file, up to the configured retention period at the unit chosen.
In the example above, the system would keep all the journal files up to 365 days.</p>
</div>
<div class="paragraph">
<p>It is also possible to limit the number of files kept in the retention directory.
You can define <code>storage-limit</code> and older files will be removed when this limit is exceeded.</p>
</div>
<div class="paragraph">
<p>Notice <code>storage-limit</code> is optional, but you need to be careful to not run out of disk space in the retention folder or the broker might be shutdown because of a critical IO failure.</p>
</div>
<div class="paragraph">
<p>You can use the CLI tools to inspect and recover data from the history, by just passing the journal folder being the retention directory.</p>
</div>
<div class="paragraph">
<p>Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight nowrap"><code data-lang="shell">./artemis data print <span class="nt">--journal</span> ../data/history</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="paging-and-large-messages"><a class="anchor" href="#paging-and-large-messages"></a><a class="link" href="#paging-and-large-messages">1. Paging and Large Messages</a></h4>
<div class="paragraph">
<p>When retention is enabled, paging and large messages are also stored on the retention folder for replaying, so replay will also work for both paged and large messages.</p>
</div>
</div>
<div class="sect3">
<h4 id="non-persistent-messages"><a class="anchor" href="#non-persistent-messages"></a><a class="link" href="#non-persistent-messages">2. Non Persistent Messages</a></h4>
<div class="paragraph">
<p>Non persistent messages are never stored anywhere in the broker. If you intend to retain data your producers should be using Durable messages.</p>
</div>
</div>
<div class="sect1">
<h2 id="recovering-data-from-retention"><a class="anchor" href="#recovering-data-from-retention"></a><a class="link" href="#recovering-data-from-retention">1. Recovering data from retention</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>To recover data from the retention folder, you can use the method <a href="https://artemis.apache.org/components/artemis/documentation/javadocs/javadoc-latest/org/apache/activemq/artemis/api/core/management/ActiveMQServerControl.html#replay(java.lang.String,java.lang.String,java.lang.String,java.lang.String,java.lang.String)">replay</a> on the management console:</p>
</div>
<div class="imageblock text-center">
<div class="content">
<img src="images/replay-method.png" alt="replay method">
</div>
</div>
<div class="paragraph">
<p>The broker will scan the set of files accordingly to the parameters you passed and it will send these methods to a target queue that you selected.</p>
</div>
<div class="sect2">
<h3 id="cli-recover-operation"><a class="anchor" href="#cli-recover-operation"></a><a class="link" href="#cli-recover-operation">1.1. CLI recover operation</a></h3>
<div class="paragraph">
<p>The CLI recover operation is intended as a low level operation, where data is read and recovered directly into a set of journal files.
Notice uou should never manipulate journal files that are being used by an active broker as that could risk the integrity of your data files and running broker.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight nowrap"><code data-lang="shell">./artemis data recovery <span class="nt">--journal</span> ../data/history <span class="nt">--target</span> ../data/recovered <span class="nt">--large-messages</span> ../data/large-messages</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</body>
</html>