Statistics Parser

The statistics parser in Yuneta handles requests for retrieving and managing statistics from a GObj. It operates by collecting attributes marked with specific statistical flags (SDF_STATS, SDF_RSTATS, and SDF_PSTATS) and providing a structured way to query, reset, or persist these attributes.

The statistics parser integrates with the gobj_stats API, dynamically selecting between a global parser or a GClass-specific mt_stats method if defined.

json_t *gobj_stats(hgobj gobj, const char *stats, json_t *kw, hgobj src);

Source code in:

How the Internal Statistics Parser Works¶

1. Attribute Collection¶

When gobj_stats() is called:

Attributes marked with SDF_STATS, SDF_RSTATS, or SDF_PSTATS are collected.
These attributes are treated as statistics and included in the response.

2. Querying Statistics¶

If the stats parameter contains the name of an attribute, the value of that specific attribute is returned.
If the stats parameter is empty, all attributes marked with SDF_STATS are returned.

3. Resetting Statistics¶

The internal global parser includes a special name, __reset__:

When __reset__ is passed as the stats parameter, all attributes marked with SDF_RSTATS are reset to their default values.

4. Persistence of Statistics¶

Attributes marked with SDF_PSTATS serve dual purposes:

They are treated as persistent attributes and saved when gobj_save_persistent_attrs() is called.
They are also included as part of the statistics queried via gobj_stats().

5. Custom GClass Handling¶

If a GClass defines an mt_stats method, gobj_stats() calls this method instead of the global parser.
This allows GClasses to implement custom logic for managing and returning statistics.

Flags Relevant to Statistics¶

Flag	Description
`SDF_STATS`	Marks the attribute as a statistic to be retrieved by the statistics parser.
`SDF_RSTATS`	Indicates that the attribute is a resettable statistic. Can be reset via `__reset__`.
`SDF_PSTATS`	Combines `SDF_STATS` with persistence. The attribute is saved as a persistent statistic.

API for Statistics¶

API	Description
`gobj_stats()`	Retrieve or reset statistics for a GObj.

Parameter	Description
`gobj`	The GObj instance for which statistics are being requested.
`stats`	The name of the statistic to retrieve, or `__reset__` to reset all resettable statistics.
`kw`	Additional parameters for the statistics request.
`src`	The source GObj sending the statistics request.

Workflow for `gobj_stats()`¶

Receiving a Statistics Request:
- A request is sent to a GObj using gobj_stats().
- The stats and kw parameters define the requested statistics and additional options.
Attribute Collection:
- The parser collects attributes marked with SDF_STATS, SDF_RSTATS, and SDF_PSTATS.
Parsing and Validation:
- If a specific statistic name is provided, its value is returned.
- If no name is provided, all SDF_STATS attributes are returned.
Custom or Global Handling:
- If the GClass defines mt_stats, it is invoked for custom processing.
- Otherwise, the global parser processes the request.
Resetting Statistics:
- If __reset__ is passed, all attributes marked with SDF_RSTATS are reset.

Benefits of the Statistics Parser¶

Dynamic Querying: Supports both specific and bulk statistics requests.
Customizability: GClasses can define their own mt_stats method for specialized handling.
Persistence Integration: Attributes marked with SDF_PSTATS are automatically persisted.
Reset Capability: The __reset__ keyword simplifies resetting of statistics.

Use Cases¶

1. Monitoring and Reporting¶

Retrieve runtime statistics for performance monitoring or system diagnostics.

2. Dynamic Configuration¶

Integrate with external systems to query or modify statistical attributes dynamically.

3. State Management¶

Reset runtime statistics programmatically to maintain operational consistency.