p4survey

A survey tool to gather basic information about a P4 installation.

Includes an optional python script to create topology diagrams of your servers.

Table of Contents

• p4survey
  • Overview
  • Downloads
  • Help
  • P4 commands run by p4survey
  • p4_topology_diagram.py
    • Download
    • Installation
    • Usage
    • Example output

Overview

Download for your platform and execute.

The following should be defined in your environment (easiest) or can be provided as parameters to the tool:

• P4PORT - the p4d server you are talking to
• P4USER - the p4d user account you are using
• P4BIN - the path to the p4 or p4.exe if it is not in your $PATH for your shell

Please note you should have logged in to the p4d server already, and have super privileges (to be able to execute some commands)

Tool with exit with an error if not being run as a logged in super user!

Downloads

• For Linux AMD64
• For Linux ARM64
• For Mac/DARWIN ARM64
• For Mac/DARWIN AMD64
• For Windows AMD64

After downloading, unzip (gunzip) and if necessary make executable.

E.g. for Linux:

wget https://swarm.workshop.perforce.com/files/guest/perforce_software/p4survey/bin/p4survey.linux-amd64.gz
gunzip p4survey.linux-amd64.gz
chmod +x p4survey.linux-amd64

./p4survey.linux-amd64 -h

To run:

./p4survey.linux-amd64
Running p4survey analysis as user "jbloggs" on P4PORT "some-server:2001"
Markdown report written: p4survey.XXXX.md
If you have any questions, please contact [email protected]

Send the resulting file: p4survey.XXXX.md

Help

usage: p4survey [<flags>]

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).
      --p4user=P4USER  (Optional) Perforce user (default $P4USER)
      --p4port=P4PORT  (Optional) Perforce server port (default $P4PORT)
      --p4bin=P4BIN    (Optional) Full path of p4 CLI (default is 'p4' in $PATH)
      --debug          Debug output
  -V, --version        Show application version.

The output will be a Markdown formatted file which can be zipped and sent to consulting or support.

P4 commands run by p4survey

The following commands are run:

p4 -ztag info
p4 license -u
p4 diskspace
p4 configure show allservers
p4 servers -J
p4 -ztag servers
p4 -ztag depots
p4 triggers -o
p4 extension --list --type extensions
p4 extension --list --type global
p4 extension --list --type instance
p4 extension --list --type certs
p4 property -n P4.Swarm.URL -l
p4 keys -e "swarm-*" -m 1
p4 keys -e "git-*" -m 1
p4 typemap -o
p4 jobspec -o
p4 counter change
p4 dbstat -s
p4 journals -m 3
p4 protects -u remote

p4_topology_diagram.py

This script will create a topology diagram in different output formats (svg, html with D3, mermaid for markdown or asciidoc).

It runs the following 2 commands against your server and matches up the output.

• p4 servers
• p4 topology -t 2 (last 2 days worth of data)

Download

See:

• p4_topology_diagram.py

Installation

Requires python3 and p4python:

if ! command -v uv >/dev/null 2>&1; then
    curl -LsSf "https://astral.sh/uv/install.sh" | sh
    export PATH="$HOME/.local/bin:$PATH"
fi
uv python install
uv venv .venv
source .venv/bin/activate
uv pip install p4python

You need to run it as a p4 user with super permissions.

Usage

Note that it is likely a good idea to try installing Graphviz locally which allows you to use different --layout options below.

./p4_topology_diagram.py -h
usage: p4_topology_diagram.py [-h] [--input-json INPUT_JSON] [--json-output JSON_OUTPUT] [--mermaid-output MERMAID_OUTPUT]
                              [--markdown-output MARKDOWN_OUTPUT] [--asciidoc-output ASCIIDOC_OUTPUT] [--html-output HTML_OUTPUT]
                              [--svg-output SVG_OUTPUT] [--layout {auto,sugiyama,dot,neato,fdp,sfdp,circo,twopi,osage,grid}] [--title TITLE]
                              [--p4port P4PORT] [--p4user P4USER]

Collect Perforce topology data and render a Mermaid diagram or other output formats.

The script can either:
1. run the live commands needed to collect topology data (p4 servers/p4 topology), or
2. render from a previously collected JSON file.

Outputs:
- JSON intermediate file with raw command output and normalized records
- Mermaid diagram source
- Markdown file wrapping the Mermaid diagram in a fenced block
- AsciiDoc block wrapping the Mermaid diagram for direct inclusion
- SVG diagram with drag-and-save support
- HTML page with interactive D3.js diagram

If you have Graphviz installed, you can use the --layout option to generate a more compact SVG layout.
If you have the fast-sugiyama python pip package installed, it will be used first
for a better layout unless --layout is set to one of its various options.
If neither fast-sugiyama nor Graphviz are available, a simple grid layout will be used.

options:
  -h, --help            show this help message and exit
  --input-json INPUT_JSON
                        Use an existing JSON intermediate file instead of running live commands.
  --json-output JSON_OUTPUT
                        Path to write the JSON intermediate file.
  --mermaid-output MERMAID_OUTPUT
                        Path to write the Mermaid diagram source.
  --markdown-output MARKDOWN_OUTPUT
                        Path to write the Markdown file containing the Mermaid diagram.
  --asciidoc-output ASCIIDOC_OUTPUT
                        Path to write an AsciiDoc Mermaid block.
  --html-output HTML_OUTPUT
                        Path to write the interactive D3.js HTML diagram.
  --svg-output SVG_OUTPUT
                        Path to write a laid-out SVG diagram with drag-and-save support.
  --layout {auto,sugiyama,dot,neato,fdp,sfdp,circo,twopi,osage,grid}
                        SVG layout engine (auto tries fast-sugiyama, then graphviz dot, then a simple grid).
  --title TITLE         Title to embed in the generated Markdown output.
  --p4port P4PORT       Perforce server port to use for live data collection.
  --p4user P4USER       Perforce user to use for live data collection.

If you just run it then it defaults to writing the various output files using your current P4PORT and P4USER environment settings.

Example output

Produced from: p4_topology.svg