rts: Post ticky entry counts to the eventlog

We currently only post the entry counters, not the other global
counters as in my experience the former are more useful. We use the heap
profiler's census period to decide when to dump.

Also spruces up the documentation surrounding ticky-ticky a bit.

3 files changed, 49 insertions, 4 deletions

diff --git a/docs/users_guide/eventlog-formats.rst b/docs/users_guide/eventlog-formats.rst
index 9be662d058..af172758bf 100644
--- a/docs/users_guide/eventlog-formats.rst
+++ b/docs/users_guide/eventlog-formats.rst
@@ -755,3 +755,34 @@ intended to provide insight into fragmentation of the non-moving heap.
    :field Word32: number of live blocks.
 
    Describes the occupancy of the *blk_sz* sub-heap.
+
+Ticky counters
+~~~~~~~~~~~~~~
+
+Programs compiled with :ghc-flag:`-ticky` and :ghc-flag:`-eventlog` and invoked
+with ``+RTS -lT`` will emit periodic samples of the ticky entry counters to the
+eventlog.
+
+.. event-type:: TICKY_COUNTER_DEF
+
+   :tag: 210
+   :length: variable
+   :field Word64: counter ID
+   :field Word16: arity/field count
+   :field String: argument kinds. This is the same as the synonymous field in the
+     textual ticky summary.
+   :field String: counter name
+
+   Defines a ticky counter.
+
+.. event-type:: TICKY_COUNTER_SAMPLE
+
+   :tag: 211
+   :length: fixed
+   :field Word64: counter ID
+   :field Word64: number of times closures of this type has been entered.
+   :field Word64: number of allocations (words)
+   :field Word64: number of times this has been allocated (words). Only
+     produced for modules compiled with :ghc-flag:`-ticky-allocd`.
+
+   Records the counter statistics at a moment in time.
diff --git a/docs/users_guide/expected-undocumented-flags.txt b/docs/users_guide/expected-undocumented-flags.txt
index 9b47e70a03..23b5a4abe7 100644
--- a/docs/users_guide/expected-undocumented-flags.txt
+++ b/docs/users_guide/expected-undocumented-flags.txt
@@ -118,5 +118,3 @@
 -syslib
 -this-component-id
 -ticky-LNE
--ticky-allocd
--ticky-dyn-thunk
diff --git a/docs/users_guide/profiling.rst b/docs/users_guide/profiling.rst
index 0b075429b5..ac1137ac84 100644
--- a/docs/users_guide/profiling.rst
+++ b/docs/users_guide/profiling.rst
@@ -1681,11 +1681,27 @@ Using “ticky-ticky” profiling (for implementors)
    single: ticky-ticky profiling
 
 .. ghc-flag:: -ticky
-    :shortdesc: :ref:`Turn on ticky-ticky profiling <ticky-ticky>`
+    :shortdesc: Turn on :ref:`ticky-ticky profiling <ticky-ticky>`
     :type: dynamic
     :category:
 
-    Enable ticky-ticky profiling.
+    Enable ticky-ticky profiling. By default this only tracks the allocations
+    *by* each closure type. See :ghc-flag:`-ticky-allocd` to keep track of
+    allocations *of* each closure type as well.
+
+.. ghc-flag:: -ticky-allocd
+    :shortdesc: Track the number of times each closure type is allocated.
+    :type: dynamic
+    :category:
+
+    Keep track of how much each closure type is allocated.
+
+.. ghc-flag:: -ticky-dyn-thunk
+    :shortdesc: Track allocations of dynamic thunks
+    :type: dynamic
+    :category:
+
+    Track allocations of dynamic thunks.
 
 Because ticky-ticky profiling requires a certain familiarity with GHC
 internals, we have moved the documentation to the GHC developers wiki.