Skip to content

System Events ADR

Submitters

  • Lenny Goodell (Intel)

Change Log

Referenced Use Case(s)

Context

System Events, aka Control Plane Events (CPE), are new to EdgeX. This ADR addresses the System Events for Devices use case with an extensible design that can address other System Event use cases that may be identified in the future. This extensible design approach and the fact that System Events are produced and consumed by different EdgeX services makes it architecturally significant warranting this ADR.

Proposed Design

To address the System Events for Devices use case, Core Metadata will publish a new SystemEvent DTO to the EdgeX MessageBus when a device is added, updated or deleted. Consumers of these System Events will subscribe to the MessageBus to receive the new SystemEvent DTO .

Data Transfer Object (DTO)

This new SystemEvent DTO will contain the following data describing the System Event:

  • Source - Publisher of the System Event, i.e. core-metadata
  • Type - Type of System Event, i.e. device
  • Action - The Action that triggered the System Event, i.e. add/update/delete
  • Timestamp - Creation date/time for the System Event
  • Owner - Owner the data for the System Event, i.e device-onvif-camera as the device owner
    • Optional based on the Type
  • Tags - Key value pairs to add addition context to the System Event, i.e. device-profile=onvif-camera
    • Optional based on the Type and/or Action
  • Details - Data details important to the System Event, i.e. Device DTO of added/updated/deleted device
    • Optional object which varies based on the Type and/or Action
    • This an object similar to ObjectValue in Reading DTO

Note

As defined, this DTO should suffice for future System Event use cases.

MessageBus

Services that publish System Events (Core Metadata) must connect to the EdgeX MessageBus and have MessageBus configuration similar to that of Core Data's here. This design assumes that Core Metadata will have this capability and configuration due to planned implementation of Service Metrics.

The PublishTopicPrefix property in Core Metadata's MessageQueue configuration will be used for System Events and set to edgex/system-event.

MessageBus Topic

The new SystemEvent DTO will be published to a multi-level topic allowing subscribers to filter by topic. The format of this topic for System Events will be:

​ {PublishTopicPrefix}/{source}/{type}/{action}

where

  • {source} = Publisher of the System Event, i.e. core-metadata
  • {type} = Type of System Event, i.e. device
  • {action} = The Action that triggered the System Event, i.e. add

Specific use cases may add additional levels as needed. The Device System Events use case will add the following levels

  • {owner} = Owner the data for the System Event, i.e device-onvif-camera as the device owner`
  • {profile} = Device profile associated with the Device, i.e onvif-camera

Example - System Event subscription topics

edgex/system-event/# - All system events
edgex/system-event/core-metadata/# - only system events from Core Metadata
edgex/system-event/core-metadata/device/# - only device system events from Core Metadata
edgex/system-event/core-metadata/device/add/device-onvif-camera/# - only add device system events for device-onvif-camera
edgex/system-event/core-metadata/device/#/#/onvif-camera - only device system events for devices created for the onvif-camera device profile

Consumers

Consumers of Device System Events will likely be custom application services as described in System Events for Devices . No changes are required to the App Functions SDK since it already supports processing of different types via the Target Type capability. Developers of custom application services that consume System Events will need to do the following:

  • Set the Target Type to &dtos.SystemEvent{} when creating an instance of ApplicationService using the NewAppServiceWithTargetType factory function.
  • Write custom pipeline function that expects the new SystemEvent DTO and process it accordingly. Similar to how the ToLineProtocol pipeline function expects the Metric DTO.

Services/Modules impacted

  • Core Metadata service
    • This service is the single point for device Add/Update/Delete and will be the producer of Device System Events.
  • Core Contracts module
    • The new SystemEvent DTO will be added to this repository
  • Camera Management App Service Example
    • Once Device System Events are implemented, the Camera Management example can be updated to consume them.
  • Device SDK/Service (future)
    • Once Device System Events are implemented, the Device SDKs can switch to receiving them via MesssageBus rather than the REST callbacks from Core Metadata. Anything beyond recognizing this future enhancement, it is out-of-scope for this ADR.

Considerations

  • This design approach can be used for future use cases, such as System Events for Device Profiles and System Events for Device Services when/if they are deemed needed.
  • Another design approach that was considered is to use Support Notifications to send the System Events via REST. This would require consumers to create subscriptions to receive the Systems Events via REST to some endpoint on the consuming service. This subscription would be created using the existing Support Notifications subscription REST API. Likely each subscription would be for a specific Event Type. System Events would be Published by POSTing them to Support Notification notification REST API, which would them forward them via REST POST to each service subscribed to the particular System Event. The System Event DTO would still be used, just sent via the REST. This approach is more complex, requires consumer services to have new REST endpoint(s) to receive the System Events and relies on REST rather than messaging, thus this approach was not chosen.

Decision

This design will satisfy the System Events for Devices use case as well as possibly other future System Event use cases.

References