9.3 KiB

Raw Blame History

Runtime Event Processing

Runtime Processing is now source-neutral. The API receives a runtime scope, selects a processing profile, partitions the normalized EventHub-style events, and delegates execution to the selected profile.

The tachograph Esper processing is no longer the root concept. It is one profile:

tachograph-driver-esper-v1

Profile discovery endpoint

GET /api/eventhub/runtime-processing/event-processing/profiles

Example response:

[
  {
    "profileKey": "tachograph-driver-esper-v1",
    "displayName": "Tachograph Driver Esper Processing",
    "description": "Runs the shared tachograph driver Esper processing pipeline over Runtime Processing event scopes.",
    "defaultPartitioningStrategy": "DRIVER",
    "supportedPartitioningStrategies": ["DRIVER"],
    "requiredParameters": [],
    "optionalParameters": [
      "significantDrivingMinutes",
      "minimumRestPeriodMinutes",
      "attachVehicleOnlyEvents",
      "vehicleEvidencePaddingMinutes",
      "includePartitionDebug"
    ]
  }
]

Clients should prefer this endpoint instead of hardcoding profile metadata.

Generic execution endpoint

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

Request shape

{
  "profileKey": "tachograph-driver-esper-v1",
  "scope": {
    "sessionIds": [
      "11111111-1111-1111-1111-111111111111",
      "22222222-2222-2222-2222-222222222222"
    ],
    "sourceFamilies": ["TACHOGRAPH_FILE_SESSION"],
    "occurredFrom": "2026-05-01T00:00:00Z",
    "occurredTo": "2026-05-31T23:59:59Z",
    "expandVehicleEvents": true,
    "vehicleExpansionPaddingMinutes": 15
  },
  "partitioning": {
    "strategy": "DRIVER",
    "includeAllPartitions": true,
    "attachVehicleEvidence": true,
    "vehicleEvidencePaddingMinutes": 15,
    "includeDebug": true
  },
  "parameters": {
    "significantDrivingMinutes": 3,
    "minimumRestPeriodMinutes": 720,
    "attachVehicleOnlyEvents": true,
    "vehicleEvidencePaddingMinutes": 15,
    "includePartitionDebug": true
  }
}

Response shape

{
  "profileKey": "tachograph-driver-esper-v1",
  "partitioningStrategy": "DRIVER",
  "inputEventCount": 1234,
  "selectedPartitionCount": 2,
  "discoveredVehicleCount": 3,
  "partitionResults": {
    "12:12345678901234": {
      "partitionType": "DRIVER",
      "partitionKey": "12:12345678901234",
      "resultType": "UnifiedRuntimeDerivedProjectionResultDto",
      "result": {
        "projection": {
          "activityIntervals": [],
          "drivingIntervals": [],
          "drivingInterruptionIntervals": [],
          "dailyWeeklyRestCandidateIntervals": [],
          "dailyWeeklyRestCandidateCoverageIntervals": [],
          "unclassifiedDailyWeeklyRestCandidateCoverageIntervals": [],
          "potentialHomeOvernightStayIntervals": [],
          "potentialInVehicleOvernightStayIntervals": [],
          "potentialInVehicleTripIntervals": [],
          "vehicleUsageIntervals": [],
          "vuCardAbsentIntervals": [],
          "supportGeoEvents": []
        }
      }
    }
  },
  "notes": [],
  "warnings": []
}

Concepts

Scope

scope is the existing runtime selection model. It can select events from:

TACHOGRAPH_FILE_SESSION
TACHOGRAPH_DB
YELLOWFOX_DB

and can use:

SOURCE_DB
EVENTHUB_DB

where supported.

For uploaded tachograph files, the scope can use:

sessionId
sessionIds
compositeSessionId

Profile

A profile owns domain-specific processing semantics. It defines:

profile key
expected partitioning strategy
profile-specific parameters
result type

Current profile:

tachograph-driver-esper-v1

Future profiles can include:

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

Partitioning

The common API supports generic partitioning options:

NONE
DRIVER
VEHICLE
DRIVER_VEHICLE
SOURCE_FAMILY
CUSTOM_PROFILE

The first tachograph profile currently supports DRIVER partitioning. The service partitions mixed event scopes in Java before invoking Esper so that existing single-driver EPL windows cannot mix driver states.

Partition debug / audit output

For mixed-source scopes, request debug output when validating why events were or were not attached to a driver partition:

{
  "partitioning": {
    "strategy": "DRIVER",
    "includeAllPartitions": true,
    "attachVehicleEvidence": true,
    "vehicleEvidencePaddingMinutes": 15,
    "includeDebug": true
  },
  "parameters": {
    "includePartitionDebug": true
  }
}

When enabled, each generic partitionResults[*].metadata.partitionDebug contains:

directDriverEventCount
vehicleUsageIntervalCount
candidateVehicleEvidenceEventCount
attachedVehicleEvidenceEventCount
ignoredVehicleEvidenceEventCount
mergedEventCount
vehicleUsageIntervals
vehicleEvidenceDecisions
notes
warnings

vehicleEvidenceDecisions explains every relevant decision, for example:

DIRECT_DRIVER_EVENT
ATTACHED_VEHICLE_EVIDENCE
IGNORED_NO_OVERLAPPING_VEHICLE_USAGE
IGNORED_ATTACHMENT_DISABLED

The compatibility response type also has partitionDebugByDriver; use the generic endpoint when you need to enable debug output explicitly. Keep debug disabled for high-volume production requests unless you need attribution diagnostics, because the decision list can be large.

Compatibility endpoint

The old tachograph endpoint remains available:

POST /api/eventhub/runtime-processing/tachograph/esper-processing

It now acts as a compatibility adapter for:

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

with:

profileKey = tachograph-driver-esper-v1
partitioning.strategy = DRIVER

Tachograph profile processing flow

runtime event scope
 -> broad event assembly
 -> driver partition discovery
 -> for each driver:
      direct driver events
      reconstruct driver vehicle-usage intervals
      attach only vehicle-scoped events whose vehicle matches and whose timestamp falls inside a usage interval plus configured padding
      shared event-input Esper projection pipeline
 -> generic partitionResults map

The tachograph profile reuses the same TachographEsperProcessingCore used by the file-session endpoint. This prevents the file-session API and runtime-processing API from drifting into separate rule chains.

Vehicle-only evidence attachment

For driver-partitioned profiles, vehicle-only events are no longer attached only by vehicle identity. They are attached to a driver partition only when there is temporal evidence:

vehicle-only event.vehicleKey/registrationKey matches a reconstructed driver vehicle-usage interval
and event.occurredAt is inside [usage.from - padding, usage.to + padding]

This prevents unrelated vehicle events from being copied into a driver result simply because the driver used the same vehicle on another day. The tachograph profile currently uses:

{
  "partitioning": {
    "attachVehicleEvidence": true,
    "vehicleEvidencePaddingMinutes": 15,
    "includeDebug": true
  },
  "parameters": {
    "attachVehicleOnlyEvents": true,
    "vehicleEvidencePaddingMinutes": 15,
    "includePartitionDebug": true
  }
}

parameters take precedence in the tachograph profile. The compatibility endpoint maps these values to expandVehicleEvents and vehicleExpansionPaddingMinutes.

Tachograph parity validation

A validation endpoint is available to compare the legacy tachograph file-session Esper endpoint with the generic runtime event-processing profile:

POST /api/eventhub/runtime-processing/event-processing/validation/tachograph-parity

This endpoint runs both paths for the selected session(s) and driver(s):

legacy file-session path
  /api/eventhub/tachograph-file-sessions/{sessionId}/drivers/{driverKey}/processing/esper-events

runtime event-processing path
  /api/eventhub/runtime-processing/event-processing
  profileKey = tachograph-driver-esper-v1

Example request:

{
  "sessionId": "{{sessionId}}",
  "driverKey": "{{driverKey}}",
  "occurredFrom": "2026-05-01T00:00:00Z",
  "occurredTo": "2026-05-31T23:59:59Z",
  "expandVehicleEvents": true,
  "vehicleExpansionPaddingMinutes": 15,
  "significantDrivingMinutes": 3,
  "minimumRestPeriodMinutes": 720,
  "includeDebug": true
}

For multiple uploaded tachograph sessions, use sessionIds or compositeSessionId. The validation service resolves the selected drivers, executes the generic runtime profile, then compares count-level parity per driver.

Compared categories include:

activityIntervals
drivingIntervals
drivingInterruptionIntervals
drivingInterruptionVehicleChangeIntervals
dailyWeeklyRestCandidateIntervals
dailyWeeklyRestCandidateCoverageIntervals
unclassifiedDailyWeeklyRestCandidateCoverageIntervals
potentialHomeOvernightStayIntervals
potentialInVehicleOvernightStayIntervals
potentialInVehicleTripIntervals
vehicleUsageIntervals
vuCardAbsentIntervals
supportGeoEvents

For a single session, this is a direct parity check against the original file-session endpoint. For multiple sessions, the reference side is the sum of the individual file-session endpoint results per driver; runtime processing may intentionally deduplicate or merge across session boundaries, so differences should be reviewed with the debug/audit output.

9.3 KiB Raw Blame History