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
});

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

world	The world.
desc	Metric description.

Returns

The metric entity.

FlecsMetricsImport()

FLECS_API void FlecsMetricsImport

(

ecs_world_t *

world

)

Metrics module import function.

Usage:

ECS_IMPORT(world, FlecsMetrics)

Parameters

world

The world.