TriTih
/
eventhub
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
eventhub/docs/runtime-event-processing.md

8.9 KiB
Raw Blame History

Runtime event processing

Runtime processing is now centered on processing executions. An execution loads canonical EventHub runtime events from selected sources, optionally partitions the event set, then runs a configured processing plan made of common EPL and/or Java modules.

The preferred endpoint is:

POST /api/eventhub/runtime-processing/executions

List available plans:

GET /api/eventhub/runtime-processing/executions/plans

The older endpoint is still available for compatibility:

POST /api/eventhub/runtime-processing/event-processing

but it should be treated as a legacy profile adapter. New clients should use processingPlanKey, not profileKey.

Assembly terminology

runtime-event-assembly collects driver seed events and, when enabled, additional events for vehicles discovered in the driver scope. The resulting collection is an aggregated runtime scope. It is only canonically de-duplicated and ordered at this stage; semantic card/VU evidence mixing and vehicle-usage interval reconciliation are performed by later modules.

For API compatibility, UnifiedRuntimeEventBundle still exposes this collection as mergedEvents. New internal assembly-stage code uses the alias aggregatedEvents, and assembly-module metadata exposes aggregatedEventCount while retaining mergedEventCount as a compatibility alias.

First predefined plan

The first predefined plan is:

driver-working-time-v1

Legacy alias:

tachograph-driver-esper-v1

This plan runs the source-neutral driver working-time chain over canonical runtime events. Tachograph file/database data is only one possible source of those canonical events. Its modules include:

event-to-activity-intervals
event-to-vehicle-usage-intervals
vehicle-evidence-attachment
support-evidence-normalization
driving-derived-projections

The important design point is that runtime processing is not tachograph-specific. Tachograph is now treated as a source/compatibility layer; the working-time plan consumes canonical driver activity, vehicle usage, and support-evidence events from any supported source.

Example execution

{
  "processingPlanKey": "driver-working-time-v1",
  "sourceSelection": {
    "tenantKey": "default",
    "driverKey": "12:12345678901234",
    "occurredFrom": "2026-05-01T00:00:00Z",
    "occurredTo": "2026-05-31T23:59:59Z",
    "sourceInputs": [
      {
        "sourceFamily": "TACHOGRAPH_FILE_SESSION",
        "eventBackend": "SOURCE_DB",
        "sessionIds": [
          "11111111-1111-1111-1111-111111111111",
          "22222222-2222-2222-2222-222222222222"
        ]
      },
      {
        "sourceFamily": "TACHOGRAPH_DB",
        "eventBackend": "EVENTHUB_DB"
      },
      {
        "sourceFamily": "YELLOWFOX_DB",
        "eventBackend": "SOURCE_DB"
      }
    ],
    "expandVehicleEvents": true
  },
  "partitioning": {
    "strategy": "DRIVER",
    "includeAllPartitions": true,
    "attachVehicleEvidence": true,
    "vehicleEvidencePaddingMinutes": 15,
    "includeDebug": true
  },
  "parameters": {
    "significantDrivingMinutes": 3,
    "minimumRestPeriodMinutes": 720,
    "includePartitionDebug": true,
    "includePartitionMetadata": true,
    "includePartitionModuleResults": true,
    "includeExecutionModuleResults": true,
    "includeSupportEvidenceNormalization": true
  }
}

sourceFamilies + eventBackend is still accepted as a legacy shorthand when every selected family uses the same backend. Use sourceInputs when one runtime request must mix direct-source and EventHub-backed inputs.

Conceptual flow

source selection
 -> runtime event loaders
 -> canonical EventHub events
 -> partitioning
 -> vehicle evidence attachment
 -> support evidence normalization
 -> event-to-interval EPL modules
 -> driver working-time derived projection EPL/Java modules
 -> partition result map

Why processing plans instead of profiles

A plan describes which modules should run over a runtime event set. This matches the EventHub goal better than domain-oriented profiles.

Future plans can reuse the same event-loading infrastructure:

vehicle-trip-detection-v1
vehicle-stop-detection-v1
driver-settlement-v1
mixed-driver-vehicle-correlation-v1
telematics-poi-clustering-v1

Each plan may use different partitioning and modules, but the source loading and canonical event model remain common.

Compatibility

Legacy profile endpoint:

POST /api/eventhub/runtime-processing/event-processing

with:

{
  "profileKey": "tachograph-driver-esper-v1",
  "scope": {},
  "partitioning": {},
  "parameters": {}
}

internally delegates to:

processingPlanKey = driver-working-time-v1

Source-neutral driver working-time modules

The former tachograph-named processing artifacts are now represented by source-neutral driver working-time names:

runtime-driver-event-interval-preprocessor.epl
driver-working-time-derived-projections.epl
DriverWorkingTimeProcessingResultDto
DriverWorkingTimeProcessingCore
RuntimeDriverWorkingTimeScopeProcessingService

Legacy tachograph names are kept as compatibility adapters for existing file-session endpoints and Postman requests. New runtime code should use the driver-working-time-* classes/resources and the driver-working-time-v1 processing plan.

Module execution results

/api/eventhub/runtime-processing/executions now exposes module execution metadata explicitly.

Top-level execution response includes:

moduleResults

This map contains one entry per executed module. The top-level entries are intentionally sanitized: they expose status, warnings, and metadata without duplicating the full partition output payload.

Each partition result also includes:

partitionResults[*].moduleResults

For driver-working-time-v1, the partition-level module results currently expose:

vehicle-evidence-attachment
support-evidence-normalization
driving-derived-projections

The first implementation uses wrapper modules around the existing validated driver-working-time scope service. Logical phase modules such as event-to-activity-intervals, event-to-vehicle-usage-intervals, and vehicle-usage-merge are registered and executed as delegated modules so they can later be split into true standalone EPL/Java modules without changing the external processing-plan contract.

First-class EPL modules

Runtime processing now supports modules implemented directly with Esper EPL through the common RuntimeEplModuleExecutor.

The first source-neutral EPL modules are:

Module key Engine EPL resource Output statement
event-to-activity-intervals EPL esper/runtime-driver-activity-intervals.epl driverActivityIntervals
event-to-vehicle-usage-intervals EPL esper/runtime-driver-vehicle-usage-intervals.epl driverVehicleUsageIntervals

These modules operate on canonical EventHub runtime events, not on tachograph-specific source rows. They are currently used as first-class phase modules in driver-working-time-v1; the final driving-derived-projections module remains a compatibility adapter over the validated working-time projection service until the remaining projection stages are split into direct EPL modules.

Response shaping

driver-working-time-v1 supports a small set of optional request parameters to trim diagnostic payloads from /api/eventhub/runtime-processing/executions and the legacy /api/eventhub/runtime-processing/event-processing adapter.

All of these default to true to preserve current behavior:

includeExecutionModuleResults
includePartitionMetadata
includePartitionModuleResults
includeSupportEvidenceNormalization
includePartitionDebug

Meaning:

  • includeExecutionModuleResults: include top-level moduleResults on /executions
  • includePartitionMetadata: include partitionResults[*].metadata
  • includePartitionModuleResults: include partitionResults[*].moduleResults
  • includeSupportEvidenceNormalization: include supportEvidenceNormalization in each partition result payload
  • includePartitionDebug: include partitionDebug in each partition result payload

Example slim response request:

{
  "processingPlanKey": "driver-working-time-v1",
  "sourceSelection": {
    "tenantKey": "default",
    "driverKey": "12:12345678901234",
    "occurredFrom": "2026-05-01T00:00:00Z",
    "occurredTo": "2026-05-31T23:59:59Z",
    "sourceInputs": [
      {
        "sourceFamily": "TACHOGRAPH_FILE_SESSION",
        "eventBackend": "SOURCE_DB",
        "sessionIds": [
          "11111111-1111-1111-1111-111111111111"
        ]
      }
    ]
  },
  "partitioning": {
    "strategy": "DRIVER"
  },
  "parameters": {
    "includeExecutionModuleResults": false,
    "includePartitionMetadata": false,
    "includePartitionModuleResults": false,
    "includeSupportEvidenceNormalization": false,
    "includePartitionDebug": false
  }
}