`session-summary`

session-summary computes summary metrics from entity-state records and emits a Legacy v1 dashboard payload. Every metric is defined in configuration, so one node template serves many simulation domains.

Entity-state records are the JSON records array that hydrate-protobuf-v2 emits with extractionTarget: EntityState. Each record carries a time value and one or more entities with a components array. The node evaluates JMESPath (a query language for JSON) expressions from the metrics list against those records and groups the results into stat cards.

The output is a Legacy v1 payload keyed combined-custom-top-stats, not a $heat-dataservice envelope. It feeds the Legacy dashboard node, described under Legacy dashboard components.

When to use

Use this node for a Legacy dashboard that needs a strip of headline numbers: time to first event, event counts, entity counts by type, and distance-band percentages. For a Next dashboard use entity-state-to-stats-summary or entity-state-to-flight-stats.

Pipeline position


input-node -> hydrate-protobuf-v2 (EntityState) -> session-summary -> dashboard (Legacy)

The node reads the latest output of one parent.

Configuration

Configuration is required. metrics must contain at least one entry.

Key	Type	Required	Default	Description
`entriesPath`	string	No	`records[*]`	JMESPath to the array of entries. Each entry holds a time value and one or more entities.
`timeField`	string	No	`simulation_time_seconds`	Dotted path from an entry to its simulation time.
`entitiesMultiPath`	string	No	`entity_state.entity`	JMESPath from an entry to its entity object or array of objects.
`metrics`	array	Yes	none	Metric definitions. See the table below.

Each item in metrics has these keys.

Key	Type	Required	Default	Description
`id`	string	Yes	none	Unique identifier for the metric.
`title`	string	Yes	none	Display title shown on the card.
`unit`	string	No	`""`	Unit label, for example `s` or `%`.
`type`	string	Yes	none	One of `first_event_time`, `count_events`, `count_entities_with_component_and_type`, `sonobuoy_lifecycle_timeline`, `distance_range`.
`config`	object	No	`{}`	Type-specific keys, listed below.

Metric types

first_event_time returns the first simulation time at which any entity gives a truthy result for config.eventQuery. The result is formatted as a duration string and the unit is cleared.

count_events counts every truthy result of config.eventQuery across all entities and entries.

count_entities_with_component_and_type counts unique entities whose config.typeQuery result equals config.typeValue and whose config.componentPresenceQuery result is non-empty. An optional config.namePattern regular expression restricts the count to entities whose name matches.

distance_range computes, for a pair of named entities, the percentage of frames in which their great-circle distance falls within each configured band. config needs entityValue, targetEntityValue, latField, lonField and rangeGroups. Each range group has label, min (inclusive) and max (exclusive) in kilometres. One card is produced per tracked entity.

sonobuoy_lifecycle_timeline builds a Legacy timeline chart for deployable sensors: a depth series per sensor and lifecycle markers for deployed, operating, scuttled and battery-depleted states. config needs typeQuery, typeValue, sonarBuoyQuery, depthField, lifetimeField and statusField, with optional namePattern, deployedThreshold and operatingQuery. This type writes to combined-custom-charts rather than the stats strip.

Output

A Legacy v1 payload. Values below are illustrative.


{
  "meta": {
    "template_name": "session-summary",
    "simulation_start_epoch": 1778681078777.0,
    "simulation_duration": "30s"
  },
  "combined-custom-top-stats": [
    {
      "value": [{ "title": "Time to first event", "result": "45s", "unit": "" }],
      "position": 0,
      "code": "session-summary-stats",
      "description": "Session Summary"
    },
    {
      "value": [{ "title": "ENTITY-A 0-5km", "result": "45.0%", "unit": "" }],
      "position": 1,
      "code": "distance-range-ENTITY-A",
      "description": "TARGET-1 to ENTITY-A"
    }
  ]
}

Metrics of type first_event_time, count_events and count_entities_with_component_and_type share the card at position 0.
Each distance_range metric gets its own card at position 1 onwards, sorted by entity name.
combined-custom-charts is present only when a sonobuoy_lifecycle_timeline metric matches at least one entity.

Limitations

Legacy only. The dashboard node consumes this payload. dashboard-v2 does not.
One parent. The node reads the latest output of the first parent only.
Distances use the great-circle formula with a mean Earth radius of 6371 km. Altitude is ignored.
The node fails when entriesPath yields no entries.

Legacy dashboard components describes the payload keys the Legacy dashboard reads.
dashboard (Legacy v1) publishes the dimension.
entity-state-to-stats-summary is the Next dashboard counterpart.

HEAT documentation team. Last updated 2 October 2026.

Opens your browser's print dialog. Choose "Save as PDF" as the destination.