README.html #21

  • //
  • guest/
  • perforce_software/
  • p4survey/
  • README.html
  • View
  • Commits
  • Open Download .zip Download (20 KB)
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc 3.10" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
  <title>p4survey</title>
  <style>
    /* Default styles provided by pandoc.
    ** See https://pandoc.org/MANUAL.html#variables-for-html for config info.
    */
    html {
      color: #1a1a1a;
      background-color: #fdfdfd;
    }
    body {
      margin: 0 auto;
      max-width: 36em;
      padding-left: 50px;
      padding-right: 50px;
      padding-top: 50px;
      padding-bottom: 50px;
      hyphens: auto;
      overflow-wrap: break-word;
      text-rendering: optimizeLegibility;
      font-kerning: normal;
    }
    @media (max-width: 600px) {
      body {
        font-size: 0.9em;
        padding: 12px;
      }
      h1 {
        font-size: 1.8em;
      }
    }
    @media print {
      html {
        background-color: white;
      }
      body {
        background-color: transparent;
        color: black;
        font-size: 12pt;
      }
      p, h2, h3 {
        orphans: 3;
        widows: 3;
      }
      h2, h3, h4 {
        page-break-after: avoid;
      }
    }
    p {
      margin: 1em 0;
    }
    a {
      color: #1a1a1a;
    }
    a:visited {
      color: #1a1a1a;
    }
    img {
      max-width: 100%;
    }
    svg {
      height: auto;
      max-width: 100%;
    }
    h1, h2, h3, h4, h5, h6 {
      margin-top: 1.4em;
    }
    h5, h6 {
      font-size: 1em;
      font-style: italic;
    }
    h6 {
      font-weight: normal;
    }
    ol, ul {
      padding-left: 1.7em;
      margin-top: 1em;
    }
    li > ol, li > ul {
      margin-top: 0;
    }
    blockquote {
      margin: 1em 0 1em 1.7em;
      padding-left: 1em;
      border-left: 2px solid #e6e6e6;
      color: #606060;
    }
    code {
      white-space: pre-wrap;
      font-family: Menlo, Monaco, Consolas, 'Lucida Console', monospace;
      font-size: 85%;
      margin: 0;
      hyphens: manual;
    }
    pre {
      margin: 1em 0;
      overflow: auto;
    }
    pre code {
      padding: 0;
      overflow: visible;
      overflow-wrap: normal;
    }
    .sourceCode {
     background-color: transparent;
     overflow: visible;
    }
    hr {
      border: none;
      border-top: 1px solid #1a1a1a;
      height: 1px;
      margin: 1em 0;
    }
    table {
      margin: 1em 0;
      border-collapse: collapse;
      width: 100%;
      overflow-x: auto;
      display: block;
      font-variant-numeric: lining-nums tabular-nums;
    }
    table caption {
      margin-bottom: 0.75em;
    }
    tbody {
      margin-top: 0.5em;
      border-top: 1px solid #1a1a1a;
      border-bottom: 1px solid #1a1a1a;
    }
    th {
      border-top: 1px solid #1a1a1a;
      padding: 0.25em 0.5em 0.25em 0.5em;
    }
    td {
      padding: 0.125em 0.5em 0.25em 0.5em;
    }
    header {
      margin-bottom: 4em;
      text-align: center;
    }
    #TOC li {
      list-style: none;
    }
    #TOC ul {
      padding-left: 1.3em;
    }
    #TOC > ul {
      padding-left: 0;
    }
    #TOC a:not(:hover) {
      text-decoration: none;
    }
    span.smallcaps{font-variant: small-caps;}
    div.columns{display: flex; gap: 1.5em;}
    div.column{flex: auto;}
    @media screen {
    div.columns{gap: min(4vw, 1.5em);}
    div.column{overflow-x: auto;}
    }
    div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
    /* The extra [class] is a hack that increases specificity enough to
       override a similar rule in reveal.js */
    ul.task-list[class]{list-style: none;}
    ul.task-list li input[type="checkbox"] {
      font-size: inherit;
      width: 0.8em;
      margin: 0 0.8em 0.2em -1.6em;
      vertical-align: middle;
    }
    .display.math{display: block; text-align: center; margin: 0.5rem auto;}
    /* CSS for syntax highlighting */
    html { -webkit-text-size-adjust: 100%; }
    pre > code.sourceCode { white-space: pre; position: relative; }
    pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
    pre > code.sourceCode > span:empty { height: 1.2em; }
    .sourceCode { overflow: visible; }
    code.sourceCode > span { color: inherit; text-decoration: inherit; }
    div.sourceCode { margin: 1em 0; }
    pre.sourceCode { margin: 0; }
    @media screen {
    div.sourceCode { overflow: auto; }
    }
    @media print {
    pre > code.sourceCode { white-space: pre-wrap; }
    pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
    }
    pre.numberSource code
      { counter-reset: source-line 0; }
    pre.numberSource code > span
      { position: relative; left: -4em; counter-increment: source-line; }
    pre.numberSource code > span > a:first-child::before
      { content: counter(source-line);
        position: relative; left: -1em; text-align: right; vertical-align: baseline;
        border: none; display: inline-block;
        -webkit-touch-callout: none; -webkit-user-select: none;
        -khtml-user-select: none; -moz-user-select: none;
        -ms-user-select: none; user-select: none;
        padding: 0 4px; width: 4em;
        color: #aaaaaa;
      }
    pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa;  padding-left: 4px; }
    div.sourceCode
      {   }
    @media screen {
    pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
    }
    code span.al { color: #ff0000; font-weight: bold; } /* Alert */
    code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
    code span.at { color: #7d9029; } /* Attribute */
    code span.bn { color: #40a070; } /* BaseN */
    code span.bu { color: #008000; } /* BuiltIn */
    code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
    code span.ch { color: #4070a0; } /* Char */
    code span.cn { color: #880000; } /* Constant */
    code span.co { color: #60a0b0; font-style: italic; } /* Comment */
    code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
    code span.do { color: #ba2121; font-style: italic; } /* Documentation */
    code span.dt { color: #902000; } /* DataType */
    code span.dv { color: #40a070; } /* DecVal */
    code span.er { color: #ff0000; font-weight: bold; } /* Error */
    code span.ex { } /* Extension */
    code span.fl { color: #40a070; } /* Float */
    code span.fu { color: #06287e; } /* Function */
    code span.im { color: #008000; font-weight: bold; } /* Import */
    code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
    code span.kw { color: #007020; font-weight: bold; } /* Keyword */
    code span.op { color: #666666; } /* Operator */
    code span.ot { color: #007020; } /* Other */
    code span.pp { color: #bc7a00; } /* Preprocessor */
    code span.sc { color: #4070a0; } /* SpecialChar */
    code span.ss { color: #bb6688; } /* SpecialString */
    code span.st { color: #4070a0; } /* String */
    code span.va { color: #19177c; } /* Variable */
    code span.vs { color: #4070a0; } /* VerbatimString */
    code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
  </style>
  <style>
    :root {
      color: #1f2933;
      background: #eef3f6;
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
      line-height: 1.6;
    }

    body {
      box-sizing: border-box;
      max-width: 58rem;
      margin: 2.5rem auto;
      padding: 3rem clamp(1.5rem, 5vw, 4.5rem);
      background: #ffffff;
      border-top: 5px solid #4b778d;
      box-shadow: 0 0.75rem 2.5rem rgb(31 41 51 / 12%);
    }

    h1, h2, h3 {
      color: #173f52;
      line-height: 1.2;
    }

    h1 {
      margin-top: 0;
      padding-bottom: 0.7rem;
      border-bottom: 1px solid #d6e1e6;
      font-size: 2.4rem;
    }

    h2 {
      margin-top: 2.4rem;
      padding-bottom: 0.35rem;
      border-bottom: 1px solid #d6e1e6;
      font-size: 1.55rem;
    }

    h3 {
      margin-top: 1.8rem;
      font-size: 1.2rem;
    }

    a, a:visited {
      color: #0d6b85;
    }

    a:hover {
      color: #a74725;
    }

    #TOC {
      margin: 2rem 0;
      padding: 1.25rem 1.5rem;
      background: #f3f7f8;
      border-left: 4px solid #4b778d;
    }

    #TOC > ul { margin-bottom: 0; }
    #TOC li { margin: 0.3rem 0; }

    code {
      padding: 0.1em 0.3em;
      background: #edf2f4;
      border-radius: 3px;
      color: #173f52;
    }

    pre {
      padding: 1rem 1.2rem;
      background: #edf2f4;
      border-left: 4px solid #4b778d;
      border-radius: 4px;
      box-shadow: inset 0 0 0 1px #d6e1e6;
    }

    pre code {
      padding: 0;
      background: transparent;
      color: #1f2933;
    }

    pre code.sourceCode > span { color: #1f2933; }
    pre code.sourceCode span.cf,
    pre code.sourceCode span.im,
    pre code.sourceCode span.kw,
    pre code.sourceCode span.ot { color: #18753d; }
    pre code.sourceCode span.ch,
    pre code.sourceCode span.sc,
    pre code.sourceCode span.st,
    pre code.sourceCode span.vs { color: #a55310; }
    pre code.sourceCode span.co,
    pre code.sourceCode span.cv { color: #4d6572; }
    pre code.sourceCode span.fu,
    pre code.sourceCode span.va { color: #155f87; }
    pre code.sourceCode span.op { color: #445761; }

    img {
      display: block;
      margin: 1.5rem auto;
      border: 1px solid #d6e1e6;
      box-shadow: 0 0.4rem 1.2rem rgb(31 41 51 / 14%);
    }

    @media (max-width: 600px) {
      body {
        margin: 0;
        padding: 1.5rem;
        box-shadow: none;
      }

      h1 { font-size: 2rem; }
    }

    @media print {
      :root { background: #ffffff; }
      body {
        max-width: none;
        margin: 0;
        padding: 0;
        border: 0;
        box-shadow: none;
      }
    }
  </style>
</head>
<body>
<header id="title-block-header">
<h1 class="title">p4survey</h1>
</header>
<nav id="TOC" role="doc-toc">
<ul>
<li><a href="#p4survey" id="toc-p4survey">p4survey</a>
<ul>
<li><a href="#overview" id="toc-overview">Overview</a></li>
<li><a href="#quick-start" id="toc-quick-start">Quick start</a></li>
<li><a href="#download" id="toc-download">Download</a></li>
<li><a href="#help" id="toc-help">Help</a></li>
<li><a href="#topology-diagram" id="toc-topology-diagram">Topology
Diagram</a></li>
<li><a href="#more-detail" id="toc-more-detail">More detail</a></li>
</ul></li>
</ul>
</nav>
<h1 id="p4survey">p4survey</h1>
<p>A survey tool to gather basic information about a P4
installation.</p>
<p><a href="#download">Download</a> and run it as a logged-in Perforce
<code>super</code> user. For the most complete report, run it on the
central commit or master server; running from a client machine is also
supported, but host-level information may be unavailable.</p>
<p>To send us accompanying pre-consulting survey information, <a
href="https://swarm.workshop.perforce.com/downloads/guest/perforce_software/p4survey/docs/survey-questionnaire.html">download
the survey questionnaire</a>, open the downloaded file in a browser, and
complete it locally (saving it as Markdown report).</p>
<p><em>Table of Contents</em></p>
<ul>
<li><a href="#p4survey">p4survey</a>
<ul>
<li><a href="#overview">Overview</a></li>
<li><a href="#quick-start">Quick start</a></li>
<li><a href="#download">Download</a></li>
<li><a href="#help">Help</a></li>
<li><a href="#topology-diagram">Topology Diagram</a></li>
<li><a href="#more-detail">More detail</a></li>
</ul></li>
</ul>
<h2 id="overview">Overview</h2>
<p>Download the binary for your platform and execute it. The tool writes
a Markdown report that can be zipped and sent to Perforce Consulting or
Support (or the person who emailed you the link).</p>
<p>The following settings can be supplied through the environment or
command-line parameters:</p>
<ul>
<li><code>P4PORT</code>: the p4d server to query</li>
<li><code>P4USER</code>: the p4d (super) user account to use</li>
<li><code>P4BIN</code>: the path to <code>p4</code> or
<code>p4.exe</code> if it is not on your shell <code>PATH</code></li>
</ul>
<p>You must already be logged in to the p4d server and have
<code>super</code> privileges. The tool exits with an error
otherwise.</p>
<h2 id="quick-start">Quick start</h2>
<p>On Linux, download the appropriate binary, decompress it, make it
executable, and run the survey:</p>
<div class="sourceCode" id="cb1"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="fu">wget</span> https://swarm.workshop.perforce.com/downloads/guest/perforce_software/p4survey/bin/p4survey.linux-amd64.gz</span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="fu">gunzip</span> p4survey.linux-amd64.gz</span>
<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a><span class="fu">chmod</span> +x p4survey.linux-amd64</span>
<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a><span class="fu">mv</span> p4survey.linux-amd64  p4survey</span>
<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a><span class="co"># Execute it - with parameters if required.</span></span>
<span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a><span class="ex">./p4survey</span></span></code></pre></div>
<p>On Windows, use PowerShell to download the executable and remove the
security marker that Windows adds to files downloaded from the
internet:</p>
<div class="sourceCode" id="cb2"><pre
class="sourceCode powershell"><code class="sourceCode powershell"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="fu">Invoke-WebRequest</span> <span class="op">-</span>Uri <span class="st">&quot;https://swarm.workshop.perforce.com/downloads/guest/perforce_software/p4survey/bin/p4survey.windows-amd64.exe&quot;</span> <span class="op">-</span>OutFile <span class="st">&quot;.\p4survey.exe&quot;</span></span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="fu">Unblock-File</span> <span class="op">-</span>Path <span class="st">&quot;.\p4survey.exe&quot;</span></span>
<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="co"># Execute it - with parameters if required.</span></span>
<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a><span class="op">&amp;</span> <span class="st">&quot;.\p4survey.exe&quot;</span></span></code></pre></div>
<p>The tool reports the generated filename, for example:</p>
<pre class="text"><code>Running p4survey analysis as user &quot;jbloggs&quot; on P4PORT &quot;some-server:2001&quot;
Topology data written: p4_topology_data.XXXX.json
Markdown report written: p4survey.XXXX.md
Email the generated survey report, topology data, and completed survey questionnaire to Perforce Consulting or Support.</code></pre>
<p>Send the resulting report to Perforce Consulting or Support.</p>
<h2 id="download">Download</h2>
<p>Click a download link directly, or copy its target to use with
<code>wget</code> or <code>curl</code>.</p>
<table>
<colgroup>
<col style="width: 33%" />
<col style="width: 33%" />
<col style="width: 33%" />
</colgroup>
<thead>
<tr>
<th>Platform</th>
<th>Download</th>
<th>History</th>
</tr>
</thead>
<tbody>
<tr>
<td>Linux amd64</td>
<td><a
href="https://swarm.workshop.perforce.com/downloads/guest/perforce_software/p4survey/bin/p4survey.linux-amd64.gz">Download</a></td>
<td><a
href="https://swarm.workshop.perforce.com/files/guest/perforce_software/p4survey/bin/p4survey.linux-amd64.gz">History</a></td>
</tr>
<tr>
<td>Linux arm64</td>
<td><a
href="https://swarm.workshop.perforce.com/downloads/guest/perforce_software/p4survey/bin/p4survey.linux-arm64.gz">Download</a></td>
<td><a
href="https://swarm.workshop.perforce.com/files/guest/perforce_software/p4survey/bin/p4survey.linux-arm64.gz">History</a></td>
</tr>
<tr>
<td>macOS arm64</td>
<td><a
href="https://swarm.workshop.perforce.com/downloads/guest/perforce_software/p4survey/bin/p4survey.darwin-arm64.gz">Download</a></td>
<td><a
href="https://swarm.workshop.perforce.com/files/guest/perforce_software/p4survey/bin/p4survey.darwin-arm64.gz">History</a></td>
</tr>
<tr>
<td>macOS amd64</td>
<td><a
href="https://swarm.workshop.perforce.com/downloads/guest/perforce_software/p4survey/bin/p4survey.darwin-amd64.gz">Download</a></td>
<td><a
href="https://swarm.workshop.perforce.com/files/guest/perforce_software/p4survey/bin/p4survey.darwin-amd64.gz">History</a></td>
</tr>
<tr>
<td>Windows amd64</td>
<td><a
href="https://swarm.workshop.perforce.com/downloads/guest/perforce_software/p4survey/bin/p4survey.windows-amd64.exe">Download</a></td>
<td><a
href="https://swarm.workshop.perforce.com/files/guest/perforce_software/p4survey/bin/p4survey.windows-amd64.exe">History</a></td>
</tr>
</tbody>
</table>
<p>For the accompanying pre-consulting checklist, <a
href="https://swarm.workshop.perforce.com/downloads/guest/perforce_software/p4survey/docs/survey-questionnaire.html">download
the survey questionnaire</a>, open the downloaded file in a browser,
complete it locally, and download the responses as Markdown.</p>
<h2 id="help">Help</h2>
<pre class="text"><code>usage: p4survey [&lt;flags&gt;]

A survey tool for Perforce P4 servers. Will report on the server configuration.

Must be run as a logged in superuser.


Flags:
  -h, --help           Show context-sensitive help (also try --help-long and --help-man).
  -u, --p4user=P4USER  (Optional) Perforce user (default $P4USER)
  -p, --p4port=P4PORT  (Optional) Perforce server port (default $P4PORT)
      --p4bin=P4BIN    (Optional) Full path of p4 CLI (default is &#39;p4&#39; in $PATH)
      --no-topology    Do not collect topology data
      --topology-svg   Collect topology data and render a pure-Go SVG diagram
      --topology-layout=layered
        SVG layout: layered or sfdp
      --topology-input=TOPOLOGY-INPUT
                       Render a pure-Go SVG diagram from saved topology JSON
      --debug          Debug output
  -V, --version        Show application version.</code></pre>
<p>The output is a Markdown report and topology data in a JSON file that
can be sent to Perforce Consulting or Support. Use
<code>--no-topology</code> to omit topology data.</p>
<h2 id="topology-diagram">Topology Diagram</h2>
<p>Topology data is collected by default. Use <code>--no-topology</code>
to omit it, or use <code>--topology-svg</code> to also create an
interactive SVG showing servers and their hostnames. The default
<code>layered</code> layout is deterministic and pure Go: it does not
require CGO, Graphviz, or Python. The SVG can be opened in a browser to
rearrange nodes and download the edited layout.</p>
<p>Use <code>--topology-layout=sfdp</code> when Graphviz
<code>sfdp</code> is installed and on <code>PATH</code>. To create an
SVG from previously saved topology JSON without connecting to P4,
run:</p>
<div class="sourceCode" id="cb5"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="ex">./p4survey</span> <span class="at">--topology-input</span> p4_topology_data.example.json</span></code></pre></div>
<p>This writes <code>p4_topology_data.example.svg</code> beside the
input file.</p>
<p>For Mermaid, HTML, AsciiDoc, alternate SVG layouts, and the legacy
Python renderer, see <a href="docs/topology-renderer.md">Topology
renderer</a>.</p>
<h2 id="more-detail">More detail</h2>
<ul>
<li><a href="docs/data-collected.md">Data collected and P4 commands
run</a></li>
<li><a href="docs/topology-renderer.md">Topology renderer</a></li>
<li><a
href="https://swarm.workshop.perforce.com/downloads/guest/perforce_software/p4survey/docs/survey-questionnaire.html">Survey
questionnaire</a>: download it, open the local file in a browser,
collect review context, and download it as Markdown to email to us.</li>
</ul>
</body>
</html>
# Change User Description Committed
#21 34019 Robert Cowham Update of tweaked instructions
#20 34015 Robert Cowham Update questionnaire to say it needs to be downloaded and completed offline
#19 33967 Robert Cowham Tweak text
#18 33966 Robert Cowham Cut down version
#17 33965 Robert Cowham Cut down version
#16 33962 Robert Cowham Release v0.7
#15 33961 Robert Cowham Simplify user page
#14 33926 Robert Cowham Moved seedreplica to another project
#13 33918 Robert Cowham Enhance p4survey topology and report summaries

- Add pure-Go editable SVG topology output, including saved JSON input and
 optional Graphviz sfdp layout.
- Include the p4survey version and change number in generated reports.
- Add compact counts for labels and client workspaces.
- On Linux SDP hosts, summarize recent checkpoint duration and p4verify status
 and error totals from SDP logs, including rotated log files.
- Update documentation and test coverage.
#12 33869 Robert Cowham Remove libraries which didn't work
#11 33868 Robert Cowham Call out to Graphiz sfdp if installed
#10 33867 Robert Cowham Trying layout options in pure Go
#9 33864 Robert Cowham Make topology compatible with python version
#8 33863 Robert Cowham Sample topology implementation
#7 33853 Robert Cowham Collect topology data optionally
#6 33850 Robert Cowham Improve HTML formatting
#5 33808 Robert Cowham Tweak download links
#4 33253 Robert Cowham Update help text
#3 33249 Robert Cowham Option to specify SVG file to save
#2 33240 Robert Cowham Improve formatting
#1 33239 Robert Cowham add html to show picture