Production Metrics
Defined in package com.scandit.datacapture.core.metrics
- MetricGroup
Added in version 8.7.0
A group of signals that production metrics can emit. Selecting a group in MetricsSettings emits its events.
- SCAN
Added in version 8.7.0
One event per recognition.
- MSAR
Added in version 8.7.0
One event per MatrixScan AR frame.
- FRAME
Added in version 8.7.0
One event per sampled processed frame.
- ENVIRONMENT
Added in version 8.7.0
Ambient and device conditions, sampled periodically.
- CAMERA
Added in version 8.7.0
Camera lifecycle transitions.
- FRAME_CAPTURE
Added in version 8.7.0
Captured frames and their images.
- LIFECYCLE
Added in version 8.7.0
The app leaving and returning to the foreground.
- CONTEXT
Added in version 8.7.0
Data capture context status changes.
- CAMERA_CONFIG
Added in version 8.7.0
Camera configuration snapshots.
- LABEL_CONFIG
Added in version 8.7.0
Label capture configuration snapshots. Their payload is not public API yet, so these events reach a sink with no payload set.
- SensitiveField
Added in version 8.7.0
A field withheld from events unless opted into.
- SCAN_DATA
Added in version 8.7.0
The recognized barcode content.
- FRAME_IMAGE
Added in version 8.7.0
The pixels of a captured frame, delivered alongside the frame-capture row.
- MetricsSink
interface MetricsSinkAdded in version 8.7.0
Consumer of production metrics, registered with ProductionMetrics.addSink().
These three methods are the whole interface. New signals arrive as new payloads on MetricEvent, which a sink that does not know them ignores.
An implementation has to be thread-safe. Event deliveries run on the metrics queue rather than on the thread that emitted the event; flush runs on whichever thread asked for it, including the one that disposes of the data capture context, so two calls to one sink can overlap.
- onMetricEvents(events)
fun onMetricEvents(events: List<MetricEvent>)
Added in version 8.7.0
Delivers a batch of events. Every event of a session follows that session’s config event, the one whose MetricEvent.config is set. Events carry no sequence number, so a sink that splits its output across several destinations is the party that has to preserve the order it received them in.
- onFrameCaptured(capture)
fun onFrameCaptured(capture: FrameCapture)
Added in version 8.7.0
Delivers the pixels for a FrameCaptureMetrics row, keyed to it by FrameCapture.captureId. On Android FrameCapture.data is a view that is valid only for the duration of this call, so copy it to keep the image; on iOS the capture owns the bytes for as long as you hold it.
- flush()
fun flush()Added in version 8.7.0
Requests that everything buffered so far reaches its destination. Called when the session ends, so a sink that batches has one guaranteed opportunity to finish. A backgrounded app can be terminated without its session ending, so it is also called each time the app leaves the foreground, and one session can see several calls.
- ProductionMetrics
class ProductionMetricsAdded in version 8.7.0
On-device production metrics for one DataCaptureContext. The signal groups selected in MetricsSettings are delivered as MetricEvent instances to every registered MetricsSink; the bundled CsvMetricsSink writes them to disk, and any other sink receives them in the app.
A context runs one instance and keeps it alive: creating another one through forDataCaptureContext() replaces it, sinks included. Reconfigure the instance through applySettings() and isEnabled instead.
On Android the context also holds this object, so it stays reachable. On iOS it is only a handle and the context exposes no accessor for it, so keep it for as long as you want to call applySettings(), isEnabled or removeSink(); dropping it leaves the registered sinks receiving events with nothing left to reach them through.
Event deliveries to a sink run on the metrics queue rather than on the thread that emitted the event; flush runs on whichever thread asked for it, including the one that disposes of the context, so two calls to one sink can overlap.
- forDataCaptureContext(dataCaptureContext, settings)
fun ProductionMetrics.forDataCaptureContext(dataCaptureContext: DataCaptureContext, settings: MetricsSettings): ProductionMetrics
Added in version 8.7.0
Creates the production metrics of the context with the given settings, replacing the instance the context had before. Disabled until isEnabled is set.
- isEnabled
var isEnabled:
BooleanAdded in version 8.7.0
Whether events are delivered. Nothing is delivered while false; enabling delivers the session’s config event before anything else. False when the instance is created.
- settings
val settings: MetricsSettings
Added in version 8.7.0
The configuration in force. Changes to the returned object take effect through applySettings().
- applySettings(settings)
fun applySettings(settings: MetricsSettings)
Added in version 8.7.0
Applies the settings while running. A changed configuration is reported to every sink as a new config event.
- addSink(sink)
fun addSink(sink: MetricsSink)
Added in version 8.7.0
Registers the sink, if it is not registered already. While a session is running and enabled, the sink receives that session’s config event first.
On Android the registration keeps the sink alive until removeSink(). On iOS an app-provided sink is referenced weakly, like every listener of this SDK, so the app is what keeps it alive; the bundled CsvMetricsSink is the exception and keeps writing until removeSink() even when the app drops it, but only the instance that was added removes it, so keep a reference to it for as long as it may need removing.
- removeSink(sink)
fun removeSink(sink: MetricsSink)
Added in version 8.7.0
Unregisters the sink. Events emitted before this call still reach it, followed by one call to MetricsSink.flush(); events emitted after it do not. The call returns without waiting for those deliveries, so keep a reference to the sink until its MetricsSink.flush() has run. A sink that was never registered is ignored.
- MetricsSettings
class MetricsSettingsAdded in version 8.7.0
Configuration of a ProductionMetrics: which signal groups are emitted, which sensitive fields their events may carry, and how often the frame group samples. It takes effect when passed to ProductionMetrics.forDataCaptureContext() or ProductionMetrics.applySettings(); changing it afterwards changes nothing until it is applied again.
- MetricsSettings()
MetricsSettings()Added in version 8.7.0
Creates settings that emit no group and carry no sensitive field.
- enabledGroups
var enabledGroups: Set<MetricGroup>
Added in version 8.7.0
The signal groups whose events are emitted. Empty by default.
- enabledSensitiveFields
var enabledSensitiveFields: Set<SensitiveField>
Added in version 8.7.0
The sensitive fields an emitted event may carry, such as the scanned data. Empty by default.
- frameMetricsSampleRate
var frameMetricsSampleRate:
IntAdded in version 8.7.0
Every Nth processed frame contributes a frame-metrics event. Values below 1 read as 1.
- maxBufferedCaptures
var maxBufferedCaptures:
IntAdded in version 8.7.0
Frame captures copied but not yet delivered. A recognition arriving while this many are in flight is dropped and counted. Held between 1 and 2.
- maxCaptureBytes
var maxCaptureBytes:
LongAdded in version 8.7.0
The largest capture delivered, in bytes. A larger frame is downscaled by a whole factor until it fits, never truncated, so a frame just over the cap arrives at half its width and height. Values below 1 read as 1.
- CsvMetricsSink
class CsvMetricsSink : MetricsSink
Added in version 8.7.0
The bundled MetricsSink: writes one plaintext CSV file per signal group per session into its directory, which it creates on first write, and captured frame images next to them. Rows are buffered and reach disk in batches, on flush(), when the app leaves the foreground, and when the session ends. A file that grows too large is rotated and nothing bounds the directory’s total size. Write failures are logged and counted, never thrown.
- CsvMetricsSink()
CsvMetricsSink(directory: String)
Added in version 8.7.0
Creates a sink writing into the directory at the given path.
- onMetricEvents(events)
fun onMetricEvents(events: List<MetricEvent>)
Added in version 8.7.0
Buffers the events as CSV rows.
- onFrameCaptured(capture)
fun onFrameCaptured(capture: FrameCapture)
Added in version 8.7.0
Writes the captured image next to the CSV files.
- flush()
fun flush()Added in version 8.7.0
Writes the buffered rows to disk.