Configuring Tracker

This microservice does not require GPU resources.

The Tracker microservice processes the record from a source topic and writes the result to its target topic.

Tracker can run in batch mode. When running in batch mode, the microservice stops after processing the last record. Otherwise it keeps running and waits for more records.

Environment Variables

  • KAFKA_TRACKER_MS_PROPERTY_FILE_PATHS: property file list

Properties

The values of properties with the .file extension are the paths of the .json files, while the values of properties with the .data extension are the .json configurations themselves.

Note Setting .data and .file properties are exclusive to each other, setting both of them results in an error.

ultinous.service.kafka.tracker.ms.config.data

Propertyultinous.service.kafka.tracker.ms.config.data
DescriptionTracker microservice configuration, and optionally authentication and functional configuration. Content must be in one-liner JSON format described in Superconfig Topic Definitions.
RequiredRequired if ultinous.service.kafka.tracker.ms.config.file not given.

ultinous.service.kafka.tracker.ms.config.file

Propertyultinous.service.kafka.tracker.ms.config.file
DescriptionPath to a microservice configuration file.
The file contents must be in JSON format, according to ultinous.service.kafka.tracker.ms.config.data above.
RequiredRequired if ultinous.service.kafka.tracker.ms.config.data not given.

Microservice Configuration Example:

{
  "source_options": {
    "start":"START_DATETIME",
    "start_date_time": "2019-05-31T10:30:00.000 +02:00",
    "end":"END_NEVER"
  },
  "source": {
    "broker_list": "127.0.0.1:6499",
    "name": "some_kafka_topic.ObjectDetectionRecord.json"
  },
  "target_options": {
    "handling": "REPLACE"
  },
  "target": {
    "broker_list": "127.0.0.1:6499",
    "name": "some_other_kafka_topic.TrackChangeRecord.json"
  },
  "config_data": { "...": "..." }
}

In this example, the sources are set to be read from the given date and never stop reading them. One source topic is defined with broker list and name. Existing messages in the target stream are replaced.

ultinous.service.kafka.tracker.config.data

Propertyultinous.service.kafka.tracker.config.data
DescriptionTracker functional configuration.
The TrackingConfigRecord definition should be in JSON format as defined in the Kafka configuration proto, see the example below.
RequiredOptional
Value Typestring

ultinous.service.kafka.tracker.config.file

Propertyultinous.service.kafka.tracker.config.file
DescriptionPath to a functional configuration file.
The file contents must be in JSON format, according to ultinous.service.kafka.tracker.config.data above.
RequiredOptional
Value Typestring

ultinous.service.kafka.tracker.auth.defs.data

Propertyultinous.service.kafka.tracker.auth.defs.data
DescriptionAuthentication definition data in one-liner JSON format corresponding to the definitions described in Superconfig Authentication Definitions.
RequiredOptional
NoteRequired if ID based authentication is used in ultinous.service.kafka.tracker.ms.config.*

ultinous.service.kafka.tracker.auth.defs.file

Propertyultinous.service.kafka.tracker.auth.defs.file
DescriptionAuthentication definition file path. Content of the file should be in JSON format described described in Superconfig Authentication Definitions.
RequiredOptional
NoteRequired if ID based authentication is used in ultinous.service.kafka.tracker.ms.config.*

ultinous.service.kafka.tracker.monitoring.port

Propertyultinous.service.kafka.tracker.monitoring.port
DescriptionMonitoring server port.
RequiredRequired
Value Typeuint16

ultinous.service.kafka.tracker.monitoring.threads

Propertyultinous.service.kafka.tracker.monitoring.threads
DescriptionMonitoring server thread pool size.
RequiredN/A
Value Typeuint16
Default Value1

For an example of Tracker properties, see Tracker Template Properties.

Changing the Configuration

It is possible to modify the configuration while Tracker is running. When you modify the configuration files on disk, Tracker will not automatically reload them. Instead, this can be achieved by posting a HTTP reload request through the monitoring port of the microservice. (The monitoring port is given in the Tracker property file, e.g. the Tracker Template Properties.)

For example:

$ curl -X POST http://localhost:6496/reload

will reload the configuration files.

Note The values of the ultinous.service.kafka.tracker.monitoring.port and ultinous.service.kafka.tracker.monitoring.threads properties cannot be changed.

The result of the reload operation is the same as if the service was stopped and restarted with the new configuration. However, it can be done using the microservice API, without maintenance privileges.

Empty Configuration

It is also possible to start Tracker with an "empty" configuration and switch to a valid configuration later. In this case, the service will be running and healthy but it will not process any inputs until an acceptable configuration is reloaded.

Attention In order for the service to run, even the "empty" configuration must contain a valid value for ultinous.service.kafka.tracker.monitoring.port.

Invalid Configuration

Invalid configuration is treated the same way as empty configuration, i.e. Tracker will run without processing any inputs. Note, however, that at least ultinous.service.kafka.tracker.monitoring.port needs to be provided for the service to run.

If changing the configuration results in any error, e.g. because of invalid configuration, the reload request returns the error code 500. In this case, Tracker will also continue running without processing any inputs.

Output Schemas

The schema definition of ObjectDetectionRecord and TrackChangeRecord can be found in the Kafka data proto.

Example of a TrackChangeRecord from Kafka:

{
  "timestamp": 1558509708748,
  "key": "1558509707748_0",
  "value": {
    "end_of_track": false,
    "detection_key": "1558509708748_0",
    "point": {
      "x": 1487,
      "y": 503
    }
  },
  "headers": "[\n  ('type', b'TrackChange'),\n  ('format', b'json')\n]"
}

Empty Detection Key The detection_key is empty if there is no real detection and the change is a prediction of the next track position (or an end of a track). This means that there is no reference to any video frames or detections in another Kafka topic but these records are necessary for processing the whole "lifecycle" of a track.

Feature Demo

For the Tracker feature demo, see Tracker Demo.

← Configuring Multi-Graph RunnerConfiguring Pass Detector →