plugins/org.eclipse.app4mc.help/docu/dev_atdb_new.textile

h1. AMALTHEA Trace Database (preview of new version)

The new AMALTHEA Trace DataBase (ATDB) primarily used to represent a runtime trace in a database format. As part of the rework, ATDB can also be used to calculate derived metrics from the trace data it holds. Since it is intended to be used in conjunction with AMALTHEA, the calculable metrics are a subset of the metrics found in AMALTHEA. However, the database schema allows for arbitrary events, entities, properties, and metrics.

The database is stored as "SQLite Database":http://www.sqlite.org/ with extension *.atdb*. It provides the data tables and several views to make the data contained in the data base more user-accessible. For performance reasons, there are some indices to speed up the access times. The general database structure and views will be described in the following sections.

h2. Database Structure

The database schema is defined completely static. Depending on the detail of data to be stored some of the tables are optional (they can be temporary to calculate metrics and do not need to be persisted). The following tables are defined:

* Default:
** MetaInformation
** Entity
** EntityType
** EntityInstance
** EventType
** Property
** PropertyValue
** Event
** Metric
** EntityMetricValue
** EntityInstanceMetricValue
** EntityMetricInstanceValue
* Optional:
** TraceEvent
** RunnableInstanceEventInfo
** ProcessInstanceEventInfo
** EventChainInstanceInfo

The database schema as Entity Relationship diagram:

!../pictures/atdb_db_schema.svg!

h3. Core Tables

The core tables refer to all white tables from the picture, without them, the database would not be meaningful. So these are mandatory to contain datasets.

h4. MetaInformation

This table contains simple key-value pairs containing information about the trace, how it was recorded, how long it is, etc. It may also contain other information, e.g., the file name(s) of the related AMALTHEA model.

* Columns
** name: text - Primary Key
** value: text - unique

So far, commonly used names include the following:

* *dbVersion*: version of the ATDB schema with syntax "v#.#.#". Current version is "v1.0.0"
* *eventsWritten*: number of events stored in the database
* *input*: path to the file, from which the information was produced
* *timeBase*: time unit in which time-values are stored

h4. Entity

The entity table contains information about all artifacts used in the database. This may include things that are not visible in the underlying trace, e.g., event chains.

* Columns
** id: integer - Primary Key
** name: text - unique, the name of the entity
** entityTypeId: integer - Foreign Key, reference to entityType.id

h4. EntityType

In order to classify entities, this table contains datasets about their types. These types can be referenced in the entityTypeId column of the entity table.

* Columns
** id: integer - Primary Key
** name: text - unique, the name of the entity type

Currently, the following type names are commonly used (also see BTF specification):

* *T*: task
* *I*: interrupt service routine
* *R*: runnable
* *EC*: event chain
* *SIM*: simulation
* *STI*: stimulus
* *ECU*: electronic control unit
* *Processor*: micro controller
* *C*: core
* *M*: memory
* *SCHED*: scheduler
* *SIG*: label/signal
* *SEM*: semaphore
* *EVENT*: operating system event (used for synchronization)

This table may contain more entity types as long as they are unique within this table.

h4. EntityInstance

Entities may be instantiated multiple times. In a trace this may be the time span between the start and terminate event of a runnable entity. For a periodic time stimulus an instance represents the nth occurence of the time stimulus. In order to differentiate between these instances this table holds two values which act as a unique identification for entity instances. They will be referenced from various entity-instance-specific tables.

* Columns
** entityId: integer - Foreign Key, references an entity
** sqcnr: integer - strictly sequential counting number (starting with 0) that will be counted up per unique entityId
** *Compound Primary Key*: entityId, sqcnr

h4. EventType

Similar to entity types this table contains types of events that can be referenced from the event and trace event tables. This also represents the connection between which events shall be observed (the ones in the event table) and which events are actually in the trace (the ones in the trace event table). The commonly used event type names are the intersection between the events from AMALTHEA and the events from the BTF specification. Just like for entity types, this table may contain additional event types (unique).

* Columns
** id: integer - Primary Key
** name: text - unique, the name of the event type

h3. Auxillary Data Tables

Additional information about entities which may help to understand and analyze the trace can be provided in auxillary tables. They are represented in yellow in the above data base schema diagram. Some information in these tables can be derived from the trace, e.g., the runnable to task mapping, other data (like event chains and events) will be sourced from the original AMALTHEA model.

h4. Property

A table for all possible properties that an entity may have in the database.

* Columns
** id: integer - Primary Key
** name: text - unique, the name of the property
** type: text - the type of the property

Currently, the following property names with their types are used:

* *simultionDuration*: time - the duration of the simulation that produced the trace, time is a double value, the global time unit can be specified in MetaInformation, if not specified defaults to nano seconds
* *initValue*: object - the initial value of a signal/label at the begin of the trace
* *processors*: entityIdRef - multi-valued reference to other entities acting as processors for this entity
* *cores*: entityIdRef - multi-valued reference to other entities acting as cores for this entity
* *frequencyInHz*: long - the clock frequency, e.g. of a core, usually an integer
* *executingCore*: entityIdRef - reference to an other entity acting as the executing core for this entity
* *runnables*: entityIdRef - multi-valued reference to other entities acting as runnables for this entity
* *ecItems*: entityIdRef - multi-valued reference to other event chain entities acting as items for this event chain entity
* *ecStimulus*: eventIdRef - reference to an event acting as the stimulus for this event chain entity (multiple values represent an event set)
* *ecResponse*: eventIdRef - reference to an event acting as the response for this event chain entity (multiple values represent an event set)

h4. PropertyValue

Here, the actual properties are set for entities. Multiple property values are represented with a strictly sequential counting number (sqcnr). In case of ordered multiple values, this acts as the index of the value within the list of values.

* Columns
** entityId: integer - Foreign Key, the id of the entity for which a row in this table holds a property value
** propertyId: integer - Foreign Key, the id of the property for which a row in this table holds a value
** sqcnr: integer - strictly sequential counting number (starting with 0) that will be counted up for each unique entityId - propertyId pair
** value: text - text representation of the value of the property
** *Compound Primary Key*: entityId, propertyId, sqcnr

h4. Event

Observable event specifications directly sourced from an AMALTHEA model can be stored in this table. Since event sets are handled via multi-valued properties, this table directly corresponds the abstract EntityEvent meta-class from AMALTHEA. The description field is left out. The name, eventType, and entity columns directly match the AMALTHEA pendants. The subtype-specific references in the EntityEvents are abstractly represented by the sourceEntity in this table. The events contained in this table are referenced in event chain entities.

* Columns
** id: integer - Primary Key
** name: text - unique, the name of the event
** eventTypeId: integer - Foreign Key, reference to the type of this event
** entityId: integer - Foreign Key, reference to the entity that shall experience this event
** sourceEntityId: integer - Foreign Key, reference to the source entity that shall emit this event

h3. Metric Tables

Derived information about entities and their instances which can be calculated (via metrics) based on an event trace may be stored in metric tables. In the above diagram these tables are colored in green.

h4. Metric

Similar to Property, this table contains the name and dimension for metrics which are referenced by the other metric tables. Commonly used metrics per entity type are defined in the Requirements section of the AMALTHEA data model [REFERENCE???].

* Columns
** id: integer - Primary Key
** name: text - unique, the name of the metric
** dimension: text - the dimension of the metric (e.g. time, count, percentage, ...)

h4. EntityMetricValue

Contains entity-specific values for given metrics.

* Columns
** entityId: integer - Foreign Key, the id of the entity for which the metric was calculated
** metricId: integer - Foreign Key, the id of the metric that was calculated for the entity
** value: text - textual representation of the metric's value
** *Compound Primary Key*: entityId, metricId

h4. EntityInstaneMetricValue

Contains entity-instance-specific values for given metrics.

* Columns
** entityId: integer - the entity id of the entity instance
** entityInstance: integer - the instance number of the entity
** metricId: integer - Foreign Key, the id of the metric that was calculated for the entity instance
** value: text - textual representation of the metric's value
** *Compound Primary Key*: entityId, entityInstance, metricId
** *Compound Foreign Key*: entityId, entityInstance of EntityInstance

h4. EntityMetricInstanceValue

Contains entity-specific values for given metrics. The sqcnr can be used to represent instances which are not differentiated by entity instances (e.g. by a constant sized time frame). Metrics like the average core load based on time slices can be stored here.

* Columns
** entityId: integer - Foreign Key, the id of the entity for which the metric instance was calculated
** metricId: integer - Foreign Key, the id of the metric whose instance was calculated for the entity
** sqcnr: integer - strictly sequential counting number (starting with 0) that will be counted up for each unique entityId - metricId pair
** value: text - textual representation of the metric instance's value
** *Compound Primary Key*: entityId, metricId, sqcnr

h3. Optional Tables

Depending on how much information shall be exchanged/contained in this data base the following tables do not have to be stored (they can be declared as TEMPORARY). They can, however, be quite usefull in calculating metrics about entities in a structured and comprehensive way. Once the metrics are calculated, there is no reference back to these optional tables. So, they do not have to remain in the data base. Since these tables represent a full event trace, omitting them can greatly reduce the size of the data base.

h4. TraceEvent

Opposite to the observable events, this table is used to store all events directly from a BTF trace (in timestamp ascending order). For multiple events happening at the same timestamp there is a strictly sequential counting number. All other columns of this table correspond to a typical event line in a BTF trace.

* Columns
** timestamp: integer - point in time at which the event occurred
** sqcnr: integer - strictly sequential counting number (starting with 0) that will be counted up for each unique timestamp
** entityId: integer - the entity id of the entity instance
** entityInstance: integer - the instance number of the entity
** sourceEntityId: integer - the entity id of the source entity instance
** entityInstance: integer - the instance number of the source entity
** eventTypeId: integer - Foreign Key, the id of the event's type
** value: text - in BTF this column is called _Note_, for signal/label write events this may hold the written value
** *Compound Primary Key*: timestamp, sqcnr
** *Compound Foreign Key*: entityId, entityInstance of EntityInstance
** *Compound Foreign Key*: sourceEntityId, sourceEntityInstance of EntityInstance

h4. RunnableInstanceTraceInfo

Derived information about runnable events for easier metric calculation. All values are derived from TraceEvent. The event counts per runnable instance stored in this table help to determine if the runnable instance is completely captured within the trace.

* Columns
** entityId: integer - the id of the runnable instance
** entityInstance: integer - the instance number of the runnable
** [RunnableEventType]EventCount: integer - the count of the respective event type for the runnable instance
** isComplete: boolean - derived from the event counts for each runnable instance, will be TRUE if the instance is completely captured in the trace, FALSE otherwise
** *Compound Primary Key*: entityId, entityInstance
** *Compound Foreign Key*: entityId, entityInstance of EntityInstance

h4. ProcessInstanceTraceInfo

Derived information about process (task or ISR) events for easier metric calculation. All values are derived from TraceEvent. The event counts per process instance stored in this table help to determine if the process instance is completely captured within the trace.

* Columns
** entityId: integer - the id of the processs instance
** entityInstance: integer - the instance number of the process
** [ProcessEventType]EventCount: integer - the count of the respective event type for the process instance
** isComplete: boolean - derived from the event counts for each process instance, will be TRUE if the instance is completely captured in the trace, FALSE otherwise
** *Compound Primary Key*: entityId, entityInstance
** *Compound Foreign Key*: entityId, entityInstance of EntityInstance

h4. EventChainInstanceInfo

Derived information about event chain instances for easier metric calculation. All values are derived from event chain entities (and their properties) and TraceEvent. This table connects the event chain instances in EntityInstance to their corresponding stimulus and response events (via Compound Foreign Key) in TraceEvent. Since event chains can be subject to EventChainLatencyConstraints and there are only two types of instances considered (age and reaction) this table holds information about whether the event chain instance is age, reaction, or both.

* Columns
** entityId: integer - the id of the event chain instance
** entityInstance: integer - the instance number of the event chain
** stimulusTimestamp: integer - the timestamp of the stimulus event of this event chain instance
** stimulusSqcnr: integer - the sqcnr of the stimulus timestamp
** responseTimestamp: integer - the timestamp of the response event of this event chain instance
** responseSqcnr: integer - the sqcnr of the response timestamp
** isAge: boolean - TRUE if this event chain instance represents the age
** isReaction: boolean - TRUE if this event chain instance represents the reaction
** *Compound Primary Key*: entityId, entityInstance
** *Compound Foreign Key*: entityId, entityInstance of EntityInstance
** *Compound Foreign Key*: stimulusTimestamp, stimulusSqcnr of TraceEvent
** *Compound Foreign Key*: responseTimestamp, responseSqcnr of TraceEvent

h2. Database Views

In order to better comprehend the contents of the database, SQLite offers the definition of views, which can be used to display the tables in a more readable way. With the help of views, the database contents can be presented in a standard database browser without knowing the meaning or significance of the table values - this is conveyed in views. This section will describe the views, which in turn can be understood as database tables, and how they are derived from the persisted tables from above. The _how_ will also be given as SQL statements.

h3. Core Views

The core tables include MetaInformation, Entity, EntityType, EntityInstance, and EventType. Since these tables only contain a small number of columns which are comprehensible on their own, there are no views defined for the core tables.

h3. Auxillary Data Views

The auxillary data tables contain more columns and refer to other tables to some extent. The following views are defined for ausillary tables:

h4. vProperty

This view shows the entity names and property names, with their corresponding values (multiple values are shown in one value entry, where the values are concatenated). In addition they also show the entity and property type names.

* Columns
** entityName: text - name of the entity with the property value
** entityType: text - name of the entity type of the entity
** propertyName: text - name of the property
** propertyType: text - type of the property
** value: text - value of the property, if there are multiple values: comma-seperated values

The corresponding SQL query to generate the view:

bc. SELECT
  (SELECT name FROM entity WHERE id = propertyValue.entityId) AS entityName,
  (SELECT name FROM entityType WHERE id = (SELECT entityTypeId FROM entity WHERE id = propertyValue.entityId)) AS entityType,
  (SELECT name FROM property WHERE id = propertyValue.propertyId) AS propertyName,
  (SELECT type FROM property WHERE id = propertyValue.propertyId) AS propertyType,
  (GROUP_CONCAT(CASE
    WHEN propertyValue.propertyId IN (SELECT id FROM property WHERE type = 'entityIdRef') THEN
      (SELECT name FROM entity WHERE id = propertyValue.value)
    WHEN propertyValue.propertyId IN (SELECT id FROM property WHERE type = 'eventIdRef') THEN
      (SELECT name FROM event WHERE id = propertyValue.value)
    ELSE
      propertyValue.value
  END, ', ')) AS value
FROM propertyValue GROUP BY entityId, propertyId ORDER BY entityId, propertyId

h4. vEvent

The observable event specification refers to EventType and Entity. This view resolves the referenced ids and presents the events in an understandable way.

* Columns
** name: text - name of the observable event
** eventType: text - name of the type of the observalbe event
** entityName: text - name of the entity that shall be subject to the observable event
** entityType: text - name of the type of the entity
** sourceEntityName: text - name of the source entity that is responsible for the observable event
** sourceEntityType: text - name of the type of the source entity

The corresponding SQL query to generate the Event view:

bc. SELECT
  name,
  (SELECT name FROM eventType WHERE id = eventTypeId) AS eventType,
  (SELECT name FROM entity WHERE id = entityId) AS entityName,
  (SELECT name FROM entityType WHERE id =
    (SELECT entityTypeId FROM entity WHERE id = event.entityId)
  ) AS entityType,
  (SELECT name FROM entity WHERE id = sourceEntityId) AS sourceEntityName,
  (SELECT name FROM entityType WHERE id =
    (SELECT entityTypeId FROM entity WHERE id = event.sourceEntityId)
  ) AS sourceEntityType
FROM event

h4. vEventChainEntity

As a special case, event chains are also stored as entities, however, they never act as a subject or source entity in the trace event table. In order to better present and highlight them among all other entities, this view provides a comprehensive representation of all event chain entities.

* Columns
** eventChainName: text - name from entity
** stimulus: text - name(s) of the observable stimulus event(s)
** response: text - name(s) of the observable response event(s)
** items: text - names of all event chain items
** minItemsCompleted: integer - number of parallel items that shall be completed until an instance of this event chain is considered complete
** isParallel: boolean - TRUE if the property with the name 'minItemsCompleted' is set

The corresponding SQL query to generate the event chain entity view:

bc. SELECT
  name AS eventChainName,
  (SELECT GROUP_CONCAT(name, ', ') FROM event  WHERE id IN (SELECT value FROM propertyValue WHERE entityId = ecEntity.id AND
    propertyId = (SELECT id FROM property WHERE name = 'ecStimulus'))) AS stimulus,
  (SELECT GROUP_CONCAT(name, ', ') FROM event  WHERE id IN (SELECT value FROM propertyValue WHERE entityId = ecEntity.id AND
    propertyId = (SELECT id FROM property WHERE name = 'ecResponse'))) AS response,
  (SELECT GROUP_CONCAT(name, ', ') FROM entity WHERE id IN (SELECT value FROM propertyValue WHERE entityId = ecEntity.id AND
    propertyId = (SELECT id FROM property WHERE name = 'ecItems'   ))) AS items,
  (SELECT value FROM propertyValue WHERE entityId = ecEntity.id AND propertyId =
    (SELECT id FROM property WHERE name = 'ecMinItemsCompleted')) AS minItemsCompleted,
  EXISTS(SELECT value FROM propertyValue WHERE entityId = ecEntity.id AND propertyId =
    (SELECT id FROM property WHERE name = 'ecMinItemsCompleted')) AS isParallel
FROM entity AS ecEntity WHERE entityTypeId = (SELECT id FROM entityType WHERE entityType.name = 'EC')

h3. Metric Views

The metric views resolve the entity and metric ids into the corresponding names and displays them. The three metric views are thus very similar.

h4. vEntityMetricValue

This view presents non-instance-specific entity metrics.

* Columns
** entityName: text - name of the entity for which this metric is stored
** entityType: text - name of the type of the entity
** metricName: text - name of the metric
** value: text - from EntityMetricValue

The corresponding SQL query to generate the entity metric value view:

bc. SELECT
  (SELECT name FROM entity WHERE id = entityMetricValue.entityId) AS entityName,
  (SELECT name FROM entityType WHERE id =
    (SELECT entityTypeId FROM entity WHERE id = entityMetricValue.entityId)
  ) AS entityType,
  (SELECT name FROM metric WHERE id = entityMetricValue.metricId) AS metricName,
  entityMetricValue.value
FROM entityMetricValue
ORDER BY entityId, metricId

h4. vEntityInstanceMetricValue

A representation of the entity instance-specific metrics is given with this view.

* Columns
** entityName: text - name of the entity for which this metric is stored
** entityType: text - name of the type of the entity
** entityInstance: integer - from EntityInstanceMetricValue
** metricName: text - name of the metric
** value: text - from EntityInstanceMetricValue

The corresponding SQL query to generate the entity instance metric value view:

bc. SELECT
  (SELECT name FROM entity WHERE id = entityInstanceMetricValue.entityId) AS entityName,
  (SELECT name FROM entityType WHERE id =
    (SELECT entityTypeId FROM entity WHERE id = entityInstanceMetricValue.entityId)
  ) AS entityType,
  entityInstanceMetricValue.entityInstance,
  (SELECT name FROM metric WHERE id = entityInstanceMetricValue.metricId) AS metricName,
  entityInstanceMetricValue.value
FROM entityInstanceMetricValue
ORDER BY entityId, entityInstance, metricId

h4. vEntityMetricInstanceValue

This view shows entity metrics that are not grouped by entity instances but by metric instances.

* Columns
** entityName: text - name of the entity for which this metric is stored
** entityType: text - name of the type of the entity
** metricName: text - name of the metric
** sqcnr: integer - from EntityMetricInstanceValue
** value: text - from EntityMetricInstanceValue

The corresponding SQL query to generate the entity metric instance value view:

bc. SELECT
  (SELECT name FROM entity WHERE id = entityMetricInstanceValue.entityId) AS entityName,
  (SELECT name FROM entityType WHERE id =
    (SELECT entityTypeId FROM entity WHERE id = entityMetricInstanceValue.entityId)
  ) AS entityType,
  (SELECT name FROM metric WHERE id = entityMetricInstanceValue.metricId) AS metricName,
  entityMetricInstanceValue.sqcnr,
  entityMetricInstanceValue.value
FROM entityMetricInstanceValue
ORDER BY entityId, metricId, sqcnr

h3. Optional Views

These views are derived from optional tables. So they may not be persisted in the database file.

h4. vTraceEvent

The trace event table itself is not readable like the BTF since all the references are ids. This view therefore offers a more BTF-like trace event table.

* Columns
** timestamp: integer - from TraceEvent
** sqcnr: integer - from TraceEvent
** entityName: text - name of the entity that is subject to the trace event
** entityType: text - name of the type of the entity
** entityInstance: integer - from TraceEvent
** sourceEntityName: text - name of the source entity that is responsible for the trace event
** sourceEntityType: text - name of the type of the source entity
** sourceEntityInstance: integer - from TraceEvent
** eventType: text - name of the type of the trace event
** value: text - from TraceEvent

The corresponding SQL query to generate the TraceEvent view:

bc. SELECT
  traceEvent.timestamp,
  traceEvent.sqcnr,
  (SELECT name FROM entity WHERE id = traceEvent.entityId) AS entityName,
  (SELECT name FROM entityType WHERE id =
    (SELECT entityTypeId FROM entity WHERE id = traceEvent.entityId)
  ) AS entityType,
  traceEvent.entityInstance,
  (SELECT name FROM entity WHERE id = traceEvent.sourceEntityId) AS sourceEntityName,
  (SELECT name FROM entityType WHERE id =
    (SELECT entityTypeId FROM entity WHERE id = traceEvent.sourceEntityId)
  ) AS sourceEntityType,
  traceEvent.sourceEntityInstance,
  (SELECT name FROM eventType WHERE id = traceEvent.eventTypeId) AS eventType,
  traceEvent.value
FROM traceEvent

h4. vRunnableInstanceRuntimeTraceEvent

This provides a filtered view on TraceEvent where the subject entity is a runnable.

* Columns
** timestamp: integer - from TraceEvent
** sqcnr: integer - from TraceEvent
** runnableName: text - name of the runnable entity
** entityInstance: integer - from TraceEvent
** sourceEntityName: text - name of the source entity that is responsible for the runnable trace event
** sourceEntityInstance: integer - from TraceEvent
** eventType: text - name of the type of the runnable trace event

The corresponding SQL query to generate the runnable instance TraceEvent view:

bc. SELECT
  timestamp,
  sqcnr,
  (SELECT name FROM entity WHERE id = entityId) AS runnableName,
  entityInstance,
  (SELECT name FROM entity WHERE id = sourceEntityId) AS sourceEntityName,
  sourceEntityInstance,
  (SELECT name FROM eventType WHERE id = eventTypeId) AS eventType
FROM (
  SELECT timestamp, sqcnr, entityId, entityInstance, sourceEntityId, sourceEntityInstance, eventTypeId
  FROM traceEvent WHERE
    eventTypeId IN (SELECT id FROM eventType WHERE name IN ('start', 'resume', 'terminate', 'suspend')) AND
    entityId IN (SELECT id FROM entity WHERE entityTypeId IN
      (SELECT id FROM entityType WHERE name IN ('R'))
    )
  GROUP BY entityId, entityInstance, timestamp, sqcnr
)

h4. vProcessInstanceRuntimeTraceEvent

This provides a filtered view on TraceEvent where the subject entity is a process (Task or ISR).

* Columns
** timestamp: integer - from TraceEvent
** sqcnr: integer - from TraceEvent
** processName: text - name of the process entity
** entityInstance: integer - from TraceEvent
** sourceEntityName: text - name of the source entity that is responsible for the process trace event
** sourceEntityInstance: integer - from TraceEvent
** eventType: text - name of the type of the process trace event

The corresponding SQL query to generate the process instance TraceEvent view:

bc. SELECT
  timestamp,
  sqcnr,
  (SELECT name FROM entity WHERE id = entityId) AS processName,
  entityInstance,
  (SELECT name FROM entity WHERE id = sourceEntityId) AS sourceEntityName,
  sourceEntityInstance,
  (SELECT name FROM eventType WHERE id = eventTypeId) AS eventType
FROM (
  SELECT timestamp, sqcnr, entityId, entityInstance, sourceEntityId, sourceEntityInstance, eventTypeId
  FROM traceEvent WHERE
    eventTypeId IN (SELECT id FROM eventType WHERE name IN ('activate', 'start', 'resume', 'run', 'terminate',
      'preempt', 'poll', 'wait', 'poll_parking', 'park', 'release_parking', 'release', 'boundedmigration',
      'fullmigration', 'mtalimitexceeded')) AND
    entityId IN (SELECT id FROM entity WHERE entityTypeId IN
      (SELECT id FROM entityType WHERE name IN ('T', 'I'))
    )
  GROUP BY entityId, entityInstance, timestamp, sqcnr
)

h4. vRunnableInstanceTraceInfo/vProcessInstanceTraceInfo

These two views directly represent the instance trace info tables, except that the entityId is resolved to the name of the entity.

h4. vEventChainInstanceInfo

This view maps event chain, stimulus event, and response event entities to their corresponding names, which makes the EventChainInstanceInfo table more comprehensible.

* Columns
** eventChainName: text - name of the event chain entity
** ecInstance: integer - entityInstance from eventChainInstanceInfo
** stimulusTimestamp: integer - timestamp of the stimulus event for this event chain instance
** stimulusEntityName: text - name of the entity that is subject to the stimulus event
** stimulusEntityInstance: integer - instance of the stimulus entity
** stimulusEvent: text - name of the type of the stimulus event
** responseTimestamp: integer - timestamp of the response event for this event chain instance
** responseEntityName: text - name of the entity that is subject to the response event
** responseEntityInstance: integer - instance of the response entity
** responseEvent: text - name of the type of the response event
** latencyType: text - either 'age', 'reaction', or 'age/reaction'

The corresponding SQL query to generate the EventChainInstanceInfo view:

bc. SELECT
  (SELECT name FROM entity WHERE id = entityId) AS eventChainName,
  entityInstance AS ecInstance,
  stimulusTimestamp,
  (SELECT name FROM entity WHERE id = (SELECT entityId FROM traceEvent WHERE timestamp = stimulusTimestamp AND
    sqcnr = stimulusSqcnr)) AS stimulusEntityName,
  (SELECT entityInstance FROM traceEvent WHERE timestamp = stimulusTimestamp AND sqcnr = stimulusSqcnr) AS stimulusEntityInstance,
  (SELECT name FROM eventType WHERE id = (SELECT eventTypeId FROM traceEvent WHERE timestamp = stimulusTimestamp AND
    sqcnr = stimulusSqcnr)) AS stimulusEvent,
  responseTimestamp,
  (SELECT name FROM entity WHERE id = (SELECT entityId FROM traceEvent WHERE timestamp = responseTimestamp AND
    sqcnr = responseSqcnr)) AS responseEntityName,
  (SELECT entityInstance FROM traceEvent WHERE timestamp = responseTimestamp AND
    sqcnr = responseSqcnr) AS responseEntityInstance,
  (SELECT name FROM eventType WHERE id = (SELECT eventTypeId FROM traceEvent WHERE timestamp = responseTimestamp AND
    sqcnr = responseSqcnr)) AS responseEvent,
  (CASE WHEN isAge AND isReaction THEN 'age/reaction' WHEN isAge THEN 'age' WHEN isReaction THEN 'reaction' END) AS latencyType
FROM eventChainInstanceInfo