Flecs v4.0
A fast entity component system (ECS) for C & C++
Loading...
Searching...
No Matches
Metrics

Collect user-defined metrics from ECS data. More...

Collaboration diagram for Metrics:

Classes

struct  EcsMetricValue
 Component that stores metric value. More...
 
struct  EcsMetricSource
 Component that stores metric source. More...
 
struct  ecs_metric_desc_t
 Used with ecs_metric_init to create metric. More...
 

Macros

#define ecs_metric(world, ...)    ecs_metric_init(world, &(ecs_metric_desc_t) __VA_ARGS__ )
 Shorthand for creating a metric with ecs_metric_init().
 

Typedefs

typedef struct EcsMetricValue EcsMetricValue
 Component that stores metric value.
 
typedef struct EcsMetricSource EcsMetricSource
 Component that stores metric source.
 
typedef struct ecs_metric_desc_t ecs_metric_desc_t
 Used with ecs_metric_init to create metric.
 

Functions

FLECS_API ECS_COMPONENT_DECLARE (FlecsMetrics)
 Flecs metrics module.
 
FLECS_API ECS_TAG_DECLARE (EcsMetric)
 Tag added to metrics, and used as first element of metric kind pair.
 
FLECS_API ECS_TAG_DECLARE (EcsCounter)
 Metric that has monotonically increasing value.
 
FLECS_API ECS_TAG_DECLARE (EcsCounterIncrement)
 Counter metric that is auto-incremented by source value.
 
FLECS_API ECS_TAG_DECLARE (EcsCounterId)
 Counter metric that counts the number of entities with an id.
 
FLECS_API ECS_TAG_DECLARE (EcsGauge)
 Metric that represents current value.
 
FLECS_API ECS_TAG_DECLARE (EcsMetricInstance)
 Tag added to metric instances.
 
FLECS_API ECS_COMPONENT_DECLARE (EcsMetricValue)
 Component with metric instance value.
 
FLECS_API ECS_COMPONENT_DECLARE (EcsMetricSource)
 Component with entity source of metric instance.
 
FLECS_API ecs_entity_t ecs_metric_init (ecs_world_t *world, const ecs_metric_desc_t *desc)
 Create a new metric.
 
FLECS_API void FlecsMetricsImport (ecs_world_t *world)
 Metrics module import function.
 

Detailed Description

Collect user-defined metrics from ECS data.

Macro Definition Documentation

◆ ecs_metric

#define ecs_metric ( world,
... )    ecs_metric_init(world, &(ecs_metric_desc_t) __VA_ARGS__ )

Shorthand for creating a metric with ecs_metric_init().

Example:

ecs_metric(world, {
.member = ecs_lookup(world, "Position.x")
.kind = EcsGauge
});
#define ecs_metric(world,...)
Shorthand for creating a metric with ecs_metric_init().
Definition metrics.h:163
ecs_entity_t ecs_lookup(const ecs_world_t *world, const char *path)
Lookup an entity by it's path.

Definition at line 163 of file metrics.h.

Function Documentation

◆ ecs_metric_init()

FLECS_API ecs_entity_t ecs_metric_init ( ecs_world_t * world,
const ecs_metric_desc_t * desc )

Create a new metric.

Metrics are entities that store values measured from a range of different properties in the ECS storage. Metrics provide a single unified interface to discovering and reading these values, which can be useful for monitoring utilities, or for debugging.

Examples of properties that can be measured by metrics are:

  • Component member values
  • How long an entity has had a specific component
  • How long an entity has had a specific target for a relationship
  • How many entities have a specific component

Metrics can either be created as a "gauge" or "counter". A gauge is a metric that represents the value of something at a specific point in time, for example "velocity". A counter metric represents a value that is monotonically increasing, for example "miles driven".

There are three different kinds of counter metric kinds:

  • EcsCounter When combined with a member, this will store the actual value of the member in the metric. This is useful for values that are already counters, such as a MilesDriven component. This kind creates a metric per entity that has the member/id.
  • EcsCounterIncrement When combined with a member, this will increment the value of the metric by the value of the member * delta_time. This is useful for values that are not counters, such as a Velocity component. This kind creates a metric per entity that has the member.
  • EcsCounterId This metric kind will count the number of entities with a specific (component) id. This kind creates a single metric instance for regular ids, and a metric instance per target for wildcard ids when targets is set.
Parameters
worldThe world.
descMetric description.
Returns
The metric entity.

◆ FlecsMetricsImport()

FLECS_API void FlecsMetricsImport ( ecs_world_t * world)

Metrics module import function.

Usage:

ECS_IMPORT(world, FlecsMetrics)
#define ECS_IMPORT(world, id)
Wrapper around ecs_import().
Definition module.h:119
Parameters
worldThe world.