Metrics Module

The metrics module gives Lua automation scripts a straightforward way to record analytics data. It takes care of locating or creating a CoCore.Analytics.Metric before inserting a new CoCore.Analytics.DataPoint, so scripts can focus on supplying measurements.

Function

metrics.create_data_point(metric_attrs, data_point_attrs)

Ensures the described metric exists and records a data point against it. The function returns {true, data_point} on success or {false, reason} if validation fails.

Metric Attributes (metric_attrs):

• name (string, required) – Metric name. Combined with resource_id to find an existing metric.
• kind (string, required) – One of "speed", "count", "temperature", "consumption", "waste", or "other".
• resource_id (string, optional but recommended) – Resource the metric belongs to. Distinguishes metrics with the same name across resources.
• unit (string, optional) – Display unit such as "iph" or "°C".
• description (string, optional) – Free-form description to help operators understand the metric.
• tags (table, optional) – Additional metadata stored on the metric. Defaults to an empty table.

Data Point Attributes (data_point_attrs):

• value (number, required) – Measurement value. Cast to a decimal internally.
• timestamp (string, optional) – ISO 8601 timestamp for the reading. Defaults to the current time if omitted.
• operation_id (string, optional) – Associates the measurement with a production operation.
• component_id (string, optional) – Associates the measurement with a production component.
• tags (table, optional) – Metadata for the data point, such as { source = "sensor-a" }. Defaults to an empty table.

Returns:

• {true, table} – On success, returns the stored data point as a Lua table.
• {false, string} – Describes why the operation failed (missing fields, validation errors, etc.).

Examples

Record Speed Data for a Resource

local success, point = metrics.create_data_point({
    name = "press_speed",
    resource_id = resource.id,
    kind = "speed",
    unit = "iph",
    tags = { scope = "production" }
}, {
    value = 126.8,
    tags = { source = "line-1" }
})

if success then
    print("Data point created at", point.timestamp)
else
    error("Failed to record speed: " .. point)
end

Attach Measurements to Operations

local ok, point = metrics.create_data_point({
    name = "waste_trimming",
    resource_id = resource.id,
    kind = "waste",
    unit = "kg"
}, {
    value = 1.42,
    operation_id = operation.id,
    timestamp = time.utc_now(),
    tags = { shift = "night" }
})

if not ok then
    log.error("Could not capture waste metric: " .. point)
end

Handle Validation Errors

local success, reason = metrics.create_data_point({}, { value = 10 })

if not success then
    print("Metric creation failed:", reason)
end

Implementation Notes

• The metric lookup uses the name and resource_id pair. When resource_id is omitted, metrics are matched solely on name.
• Metrics are created with empty tag maps when none are provided to keep Timescale queries predictable.
• Data point values are stored as decimals; floats passed from Lua are safely cast during persistence.
• The caller's actor permissions apply to both the metric lookup/creation and the data point insert.