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

7.3 KiB Raw Blame History