From: Laura Flores <lflores@redhat.com>
Date: Wed, 9 Feb 2022 20:53:33 +0000 (+0000)
Subject: doc/dev: add section on using the gen_state_diagram.py script
X-Git-Tag: v18.0.0~1406^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F44963%2Fhead;p=ceph.git

doc/dev: add section on using the gen_state_diagram.py script

Commands sourced from Jianshen Liu's blog post on the Ceph peering state machine: https://jianshenliu.com/blog/development/ceph-peering-state-machine/

Also fixed the formatting of "PG info".

Signed-off-by: Laura Flores <lflores@redhat.com>
---

diff --git a/doc/dev/peering.rst b/doc/dev/peering.rst
index 7ee5debc9ca..3960e14ca33 100644
--- a/doc/dev/peering.rst
+++ b/doc/dev/peering.rst
@@ -60,7 +60,8 @@ Concepts
    accepting write operations, and *recovery* can proceed
    in the background.
 
-*PG info* basic metadata about the PG's creation epoch, the version
+*PG info*
+   basic metadata about the PG's creation epoch, the version
    for the most recent write to the PG, *last epoch started*, *last
    epoch clean*, and the beginning of the *current interval*.  Any
    inter-OSD communication about PGs includes the *PG info*, such that
@@ -253,7 +254,17 @@ The high level process is for the current PG primary to:
      old object (all of whose copies disappeared before they could be
      replicated on members of the current *acting set*).
 
-State Model
------------
+Generate a State Model
+----------------------
+
+Use the `gen_state_diagram.py <https://github.com/ceph/ceph/blob/master/doc/scripts/gen_state_diagram.py>`_ script to generate a copy of the latest peering state model::
+
+        $ git clone https://github.com/ceph/ceph.git
+        $ cd ceph
+        $ cat src/osd/PeeringState.h src/osd/PeeringState.cc | doc/scripts/gen_state_diagram.py > doc/dev/peering_graph.generated.dot
+        $ sed -i 's/7,7/1080,1080/' doc/dev/peering_graph.generated.dot
+        $ dot -Tsvg doc/dev/peering_graph.generated.dot > doc/dev/peering_graph.generated.svg
+
+Sample state model:
 
 .. graphviz:: peering_graph.generated.dot
diff --git a/doc/scripts/README.md b/doc/scripts/README.md
new file mode 100644
index 00000000000..e3d4c23e87b
--- /dev/null
+++ b/doc/scripts/README.md
@@ -0,0 +1,11 @@
+Script Usage
+============
+
+Peering State Model: gen_state_diagram.py
+------------------------------------------
+    $ git clone https://github.com/ceph/ceph.git
+    $ cd ceph
+    $ cat src/osd/PeeringState.h src/osd/PeeringState.cc | doc/scripts/gen_state_diagram.py > doc/dev/peering_graph.generated.dot
+    $ sed -i 's/7,7/1080,1080/' doc/dev/peering_graph.generated.dot
+    $ dot -Tsvg doc/dev/peering_graph.generated.dot > doc/dev/peering_graph.generated.svg
+