Deployed 84d9b92 with MkDocs version: 1.6.1

This commit is contained in:
2026-07-07 04:51:21 +00:00
parent 6dcc804d48
commit 7a802311e3
26 changed files with 952 additions and 362 deletions
+8 -8
View File
@@ -2085,7 +2085,7 @@
<p>The debug log is created during a <code>dl</code> run (and by <a href="../cli-reference/#import"><code>import</code></a>, which wraps <code>dl</code>). The path is:</p>
<div class="language-text highlight"><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>&lt;logs directory&gt;/unshackle_debug_&lt;service&gt;_&lt;timestamp&gt;.jsonl
</span></code></pre></div>
<p>For example, <code>unshackle_debug_NETFLIX_20260703-142530.jsonl</code>. The <code>&lt;service&gt;</code> tag and the timestamp mean each download gets its own file, so runs never overwrite each other.</p>
<p>For example, <code>unshackle_debug_EXAMPLE_20260703-142530.jsonl</code>. The <code>&lt;service&gt;</code> tag and the timestamp mean each download gets its own file, so runs never overwrite each other.</p>
<div class="admonition tip">
<p class="admonition-title">Find your logs directory</p>
<p>The logs directory defaults to a <code>logs</code> folder inside the package data directory, but it can be relocated with the <code>directories.logs</code> config key. To see the exact resolved path on your machine, run <a href="#env-info"><code>unshackle env info</code></a> and read the <strong>Directories</strong> table.</p>
@@ -2152,16 +2152,16 @@
<h3 id="reading-and-filtering-the-log">Reading and filtering the log<a class="headerlink" href="#reading-and-filtering-the-log" title="Permanent link">&para;</a></h3>
<p>Because each line is independent JSON, <code>jq</code> is the natural tool:</p>
<div class="language-console highlight"><pre><span></span><code><span id="__span-5-1"><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="gp"># </span>Show<span class="w"> </span>only<span class="w"> </span>error-level<span class="w"> </span>entries
</span><span id="__span-5-2"><a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="go">jq &#39;select(.level == &quot;ERROR&quot;)&#39; unshackle_debug_NETFLIX_20260703-142530.jsonl</span>
</span><span id="__span-5-2"><a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="go">jq &#39;select(.level == &quot;ERROR&quot;)&#39; unshackle_debug_EXAMPLE_20260703-142530.jsonl</span>
</span><span id="__span-5-3"><a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a>
</span><span id="__span-5-4"><a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="gp"># </span>List<span class="w"> </span>every<span class="w"> </span>operation<span class="w"> </span>and<span class="w"> </span>whether<span class="w"> </span>it<span class="w"> </span>succeeded
</span><span id="__span-5-5"><a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a><span class="go">jq -c &#39;{operation, success}&#39; unshackle_debug_NETFLIX_20260703-142530.jsonl</span>
</span><span id="__span-5-5"><a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a><span class="go">jq -c &#39;{operation, success}&#39; unshackle_debug_EXAMPLE_20260703-142530.jsonl</span>
</span><span id="__span-5-6"><a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a>
</span><span id="__span-5-7"><a id="__codelineno-5-7" name="__codelineno-5-7" href="#__codelineno-5-7"></a><span class="gp"># </span>Pull<span class="w"> </span>the<span class="w"> </span>traceback<span class="w"> </span>out<span class="w"> </span>of<span class="w"> </span>the<span class="w"> </span>first<span class="w"> </span>error
</span><span id="__span-5-8"><a id="__codelineno-5-8" name="__codelineno-5-8" href="#__codelineno-5-8"></a><span class="go">jq -r &#39;select(.error) | .error.traceback[]&#39; unshackle_debug_NETFLIX_20260703-142530.jsonl</span>
</span><span id="__span-5-8"><a id="__codelineno-5-8" name="__codelineno-5-8" href="#__codelineno-5-8"></a><span class="go">jq -r &#39;select(.error) | .error.traceback[]&#39; unshackle_debug_EXAMPLE_20260703-142530.jsonl</span>
</span><span id="__span-5-9"><a id="__codelineno-5-9" name="__codelineno-5-9" href="#__codelineno-5-9"></a>
</span><span id="__span-5-10"><a id="__codelineno-5-10" name="__codelineno-5-10" href="#__codelineno-5-10"></a><span class="gp"># </span>Show<span class="w"> </span>only<span class="w"> </span>DRM<span class="w"> </span>/<span class="w"> </span>licensing<span class="w"> </span>operations
</span><span id="__span-5-11"><a id="__codelineno-5-11" name="__codelineno-5-11" href="#__codelineno-5-11"></a><span class="go">jq &#39;select(.operation | startswith(&quot;drm_&quot;))&#39; unshackle_debug_NETFLIX_20260703-142530.jsonl</span>
</span><span id="__span-5-11"><a id="__codelineno-5-11" name="__codelineno-5-11" href="#__codelineno-5-11"></a><span class="go">jq &#39;select(.operation | startswith(&quot;drm_&quot;))&#39; unshackle_debug_EXAMPLE_20260703-142530.jsonl</span>
</span></code></pre></div>
<p>The session's binary-tool versions (Shaka Packager, mp4decrypt, mkvmerge, FFmpeg, FFprobe) are logged near the start of a <code>dl</code> run, which is often the fastest way to confirm a muxing or decryption failure is really a wrong-version problem.</p>
<hr />
@@ -2199,7 +2199,7 @@
<li><strong>Local paths</strong>: install-root, virtualenv, and home-directory prefixes are replaced with tokens, so your username and machine layout don't appear in logs.</li>
</ul>
<p>Path redaction is controlled by the <code>redact_paths</code> config key, which is <strong>on by default</strong>:</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-10-1"><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="nt">redact_paths</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span><span class="w"> </span><span class="c1"># default — mask local base directories in logged paths</span>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-10-1"><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="nt">redact_paths</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span><span class="w"> </span><span class="c1"># default - mask local base directories in logged paths</span>
</span></code></pre></div>
<p>Set <code>redact_paths: false</code> if you are debugging a path problem locally and want to see full, unmasked paths in the console and logs. Secret and URL redaction in the JSON debug log are always applied and are not affected by this toggle.</p>
<hr />
@@ -2258,7 +2258,7 @@
<h3 id="env-clear"><code>env clear</code><a class="headerlink" href="#env-clear" title="Permanent link">&para;</a></h3>
<p>Stale cache or leftover temp files can cause confusing behaviour (an old cached title list, a half-written temp file). <code>env clear</code> wipes those directories safely:</p>
<div class="language-console highlight"><pre><span></span><code><span id="__span-13-1"><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a><span class="go">unshackle env clear cache # clear the whole cache directory</span>
</span><span id="__span-13-2"><a id="__codelineno-13-2" name="__codelineno-13-2" href="#__codelineno-13-2"></a><span class="go">unshackle env clear cache NETFLIX # clear just one service&#39;s cache subdirectory</span>
</span><span id="__span-13-2"><a id="__codelineno-13-2" name="__codelineno-13-2" href="#__codelineno-13-2"></a><span class="go">unshackle env clear cache EXAMPLE # clear just one service&#39;s cache subdirectory</span>
</span><span id="__span-13-3"><a id="__codelineno-13-3" name="__codelineno-13-3" href="#__codelineno-13-3"></a><span class="go">unshackle env clear temp # clear the temp working directory</span>
</span></code></pre></div>
<p>Each command reports how many files it removed and how much space it freed, then recreates the empty directory.</p>
@@ -2313,7 +2313,7 @@
<p class="admonition-title">Log levels are a flow skeleton, not just severity</p>
<p>Treat <code>level</code> as structure, not decoration. Emit exactly <strong>one <code>INFO</code> milestone per pipeline stage</strong> so that <code>jq 'select(.level=="INFO")'</code> reads back the whole end-to-end flow of a run. Everything internal goes to <code>DEBUG</code>; failures go to <code>ERROR</code>. Keeping <code>INFO</code> sparse is the whole point. It is the line a developer skims first to see where a run got to before it broke.</p>
<div class="language-console highlight"><pre><span></span><code><span id="__span-14-1"><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a><span class="gp"># </span>Read<span class="w"> </span>the<span class="w"> </span>pipeline<span class="err">&#39;</span>s<span class="w"> </span>high-level<span class="w"> </span>flow,<span class="w"> </span>one<span class="w"> </span>line<span class="w"> </span>per<span class="w"> </span>stage
</span><span id="__span-14-2"><a id="__codelineno-14-2" name="__codelineno-14-2" href="#__codelineno-14-2"></a><span class="go">jq &#39;select(.level == &quot;INFO&quot;)&#39; unshackle_debug_NETFLIX_20260703-142530.jsonl</span>
</span><span id="__span-14-2"><a id="__codelineno-14-2" name="__codelineno-14-2" href="#__codelineno-14-2"></a><span class="go">jq &#39;select(.level == &quot;INFO&quot;)&#39; unshackle_debug_EXAMPLE_20260703-142530.jsonl</span>
</span></code></pre></div>
</div>
<div class="admonition warning">