Flecs: Metrics
Description: A fast entity component system (ECS) for C & C++

| Flecs v4.0 A fast entity component system (ECS) for C & C++

Loading...
Searching...
No Matches
Metrics
C API » Addons

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, ...)
| 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,
|  |  | ... )

Value:
ecs_metric_init(world, &(ecs_metric_desc_t) __VA_ARGS__ )
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.
ecs_metric_desc_t
Used with ecs_metric_init to create metric.
Definition metrics.h:76

Shorthand for creating a metric with ecs_metric_init().

Example:

ecs_metric(world, {
.member = ecs_lookup(world, "Position.x")
.kind = EcsGauge
});
ecs_metric
#define ecs_metric(world,...)
Shorthand for creating a metric with ecs_metric_init().
Definition metrics.h:163
ecs_lookup
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

  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)
ECS_IMPORT
#define ECS_IMPORT(world, id)
Wrapper around ecs_import().
Definition module.h:119

Parameters

  world | The world.