266 lines
8.2 KiB
Markdown
266 lines
8.2 KiB
Markdown
# 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:
|
|
|
|
```http
|
|
POST /api/eventhub/runtime-processing/executions
|
|
```
|
|
|
|
List available plans:
|
|
|
|
```http
|
|
GET /api/eventhub/runtime-processing/executions/plans
|
|
```
|
|
|
|
The older endpoint is still available for compatibility:
|
|
|
|
```http
|
|
POST /api/eventhub/runtime-processing/event-processing
|
|
```
|
|
|
|
but it should be treated as a legacy profile adapter. New clients should use `processingPlanKey`, not `profileKey`.
|
|
|
|
## First predefined plan
|
|
|
|
The first predefined plan is:
|
|
|
|
```text
|
|
driver-working-time-v1
|
|
```
|
|
|
|
Legacy alias:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```http
|
|
POST /api/eventhub/runtime-processing/event-processing
|
|
```
|
|
|
|
with:
|
|
|
|
```json
|
|
{
|
|
"profileKey": "tachograph-driver-esper-v1",
|
|
"scope": {},
|
|
"partitioning": {},
|
|
"parameters": {}
|
|
}
|
|
```
|
|
|
|
internally delegates to:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
partitionResults[*].moduleResults
|
|
```
|
|
|
|
For `driver-working-time-v1`, the partition-level module results currently expose:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
}
|
|
}
|
|
```
|