From b72225dee214da781295b2e512fb6cd017f6ff6a Mon Sep 17 00:00:00 2001 From: Aurelien DARRAGON Date: Tue, 16 Sep 2025 18:44:02 +0200 Subject: [PATCH] DOC: internals: document the shm-stats-file format/mapping Add some documentation about shm stats file structure to help writing tools that can parse the file to use the shared stats counters. This file was written for shm stats file version 1.0 specifically, it may need to be updated when the shm stats file structure changes in the future. --- doc/internals/shm-stats-file-description.txt | 53 ++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 doc/internals/shm-stats-file-description.txt diff --git a/doc/internals/shm-stats-file-description.txt b/doc/internals/shm-stats-file-description.txt new file mode 100644 index 000000000..0fa088851 --- /dev/null +++ b/doc/internals/shm-stats-file-description.txt @@ -0,0 +1,53 @@ +2025/09/16 - SHM stats file storage description and hints + +Shm stats file (used to share thread-groupable statistics over multiple +process through the "shm-stats-file" directive) is made of: + +- a main header which describes the file version, the processes making + use of it, the common clock source and hints about the number of + objects that are currently stored or provisionned in the file. +- an indefinite number of "objects" blocks coming right after the + main header, all blocks have the same size which is the size of the + maximum underlying object that may be stored. The main header tells + how many objects are stored in the file. + +File header looks like this (32/64 bits systems): + +0 8 16 32 48 64 ++-------+---------+----------------+-------------------+-------------------+ +| VERSION | 2 bytes | global_now_ms (global mono date in ms)| +|MAJOR | MINOR | hole | | ++----------------------------------+---------------------------------------+ +| global_now_ns (global mono date in ns) | ++--------------------------------------------------------------------------+ +| now_offset (offset applied to global monotonic date | +| on startup) | ++--------------------------------------------------------------------------+ +| Process slot : | 1byte x 64 +| pid | heartbeat (ticks) | ++----------------------------------+---------------------------------------+ +| objects | objects slots | +| (used objects) | (available for use) | ++----------------------------------+---------------------------------------+ +| padding (for future use) | 128 bytes ++--------------------------------------------------------------------------+ + +Object block looks like this: + +0 8 16 32 48 64 ++-------+---------+----------------+-------------------+-------------------+ +| GUID | 128 bytes ++ (zero terminated) + +| | ++-------+---------+--------------------------------------------------------+ +| tgid | type | padding | ++-------+---------+--------------------------------------------------------+ +| users (bitmask of process slots making use of the obj) | ++--------------------------------------------------------------------------+ +| object data | +| (version dependent) | +| struct be_counters_shared_tg or | +| struct fe_counters_shared_tg | ++--------------------------------------------------------------------------+ +| padding (to anticipate evolutions) | 64 bytes ++--------------------------------------------------------------------------+