Recording Rules

Define rules that automatically evaluate recordings and take actions when conditions match. Rules run on incoming recording data and can tag recordings, create timeline events, flag items for human review, or trigger notifications — without any manual intervention.

Fleet Management is in preview. APIs and features described on this page may change.

How Rules Work

You define a rule with a condition (what to look for) and one or more actions (what to do when found).
When a recording finishes processing, all active rules evaluate against its data.
If a rule’s condition matches, its actions execute automatically.
Rule evaluation results are logged for auditing and debugging.

Rules evaluate against topic data, recording metadata, and event patterns within a recording. They can target specific devices, device groups, or apply fleet-wide.

Rule Types

Rule Type	Description	Example Use Case
`threshold`	Numeric value exceeds or falls below a limit	Motor temperature > 80C, latency > 100ms
`pattern`	Regex match on topic data or metadata fields	Error message contains “timeout”, topic name matches `/sensors/*/error`
`frequency`	Event occurs more than N times within a time window	More than 5 errors in 1 minute, heartbeat rate drops below 1 Hz
`absence`	Expected data is missing for a specified duration	No heartbeat for 30 seconds, missing camera frames for 5 seconds
`composite`	Logical combination of other conditions (AND, OR)	Temperature > 80C AND motor speed > 1000 RPM

Creating Rules

Threshold Rule

The most common rule type. Monitor a numeric field on a topic and trigger when it crosses a boundary.

from avala import Client

client = Client()

rule = client.fleet.rules.create(
    name="High Latency Alert",
    description="Triggers when control loop latency exceeds 100ms for more than 1 minute",
    condition={
        "type": "threshold",
        "topic": "/diagnostics/latency",
        "field": "data.value",
        "operator": "gt",
        "value": 100,
        "window": "1m"
    },
    actions=[
        {"type": "tag", "value": "high-latency"},
        {"type": "create_event", "event_type": "warning", "label": "High latency detected"},
        {"type": "notify", "channel_id": "ch_abc123"}
    ]
)

print(f"Rule created: {rule.name} ({rule.uid})")

import Avala from "@avala-ai/sdk";

const avala = new Avala();

const rule = await avala.fleet.rules.create({
  name: "High Latency Alert",
  description: "Triggers when control loop latency exceeds 100ms for more than 1 minute",
  condition: {
    type: "threshold",
    topic: "/diagnostics/latency",
    field: "data.value",
    operator: "gt",
    value: 100,
    window: "1m",
  },
  actions: [
    { type: "tag", value: "high-latency" },
    { type: "create_event", eventType: "warning", label: "High latency detected" },
    { type: "notify", channelId: "ch_abc123" },
  ],
});

console.log(`Rule created: ${rule.name} (${rule.uid})`);

avala fleet rules create \
  --name "High Latency Alert" \
  --condition '{"type": "threshold", "topic": "/diagnostics/latency", "field": "data.value", "operator": "gt", "value": 100, "window": "1m"}' \
  --action tag:high-latency \
  --action create_event:warning:"High latency detected" \
  --action notify:ch_abc123

Condition Operators

Operator	Description	Valid For
`gt`	Greater than	Numeric fields
`gte`	Greater than or equal	Numeric fields
`lt`	Less than	Numeric fields
`lte`	Less than or equal	Numeric fields
`eq`	Equal to	Numeric, string, boolean fields
`neq`	Not equal to	Numeric, string, boolean fields
`between`	Within a range (inclusive)	Numeric fields
`outside`	Outside a range	Numeric fields

Pattern Rule

Match against string values in topic data or recording metadata using regular expressions.

rule = client.fleet.rules.create(
    name="Timeout Error Detector",
    description="Flags recordings containing timeout errors in diagnostics",
    condition={
        "type": "pattern",
        "topic": "/diagnostics/errors",
        "field": "message",
        "regex": "(?i)timeout|timed?\\s*out",
    },
    actions=[
        {"type": "tag", "value": "has-timeout-errors"},
        {"type": "flag_for_review"},
        {"type": "create_event", "event_type": "error", "label": "Timeout error detected"}
    ]
)

const rule = await avala.fleet.rules.create({
  name: "Timeout Error Detector",
  description: "Flags recordings containing timeout errors in diagnostics",
  condition: {
    type: "pattern",
    topic: "/diagnostics/errors",
    field: "message",
    regex: "(?i)timeout|timed?\\s*out",
  },
  actions: [
    { type: "tag", value: "has-timeout-errors" },
    { type: "flag_for_review" },
    { type: "create_event", eventType: "error", label: "Timeout error detected" },
  ],
});

Frequency Rule

Trigger when an event or condition occurs more (or fewer) than a specified number of times within a sliding time window.

rule = client.fleet.rules.create(
    name="Error Burst Detector",
    description="Triggers when more than 5 errors occur within any 1-minute window",
    condition={
        "type": "frequency",
        "topic": "/diagnostics/errors",
        "count_operator": "gt",
        "count": 5,
        "window": "1m"
    },
    actions=[
        {"type": "tag", "value": "error-burst"},
        {"type": "create_event", "event_type": "anomaly", "label": "Error burst detected"},
        {"type": "notify", "channel_id": "ch_abc123"}
    ]
)

const rule = await avala.fleet.rules.create({
  name: "Error Burst Detector",
  description: "Triggers when more than 5 errors occur within any 1-minute window",
  condition: {
    type: "frequency",
    topic: "/diagnostics/errors",
    countOperator: "gt",
    count: 5,
    window: "1m",
  },
  actions: [
    { type: "tag", value: "error-burst" },
    { type: "create_event", eventType: "anomaly", label: "Error burst detected" },
    { type: "notify", channelId: "ch_abc123" },
  ],
});

Absence Rule

Detect missing data — useful for heartbeat monitoring, dropped sensor feeds, and connectivity issues.

rule = client.fleet.rules.create(
    name="Missing Heartbeat",
    description="Triggers when no heartbeat message appears for 30 seconds",
    condition={
        "type": "absence",
        "topic": "/system/heartbeat",
        "timeout": "30s"
    },
    actions=[
        {"type": "create_event", "event_type": "error", "label": "Heartbeat lost"},
        {"type": "notify", "channel_id": "ch_abc123"}
    ]
)

const rule = await avala.fleet.rules.create({
  name: "Missing Heartbeat",
  description: "Triggers when no heartbeat message appears for 30 seconds",
  condition: {
    type: "absence",
    topic: "/system/heartbeat",
    timeout: "30s",
  },
  actions: [
    { type: "create_event", eventType: "error", label: "Heartbeat lost" },
    { type: "notify", channelId: "ch_abc123" },
  ],
});

Composite Rule

Combine multiple conditions with logical operators for complex detection scenarios.

rule = client.fleet.rules.create(
    name="Thermal Overload Risk",
    description="Triggers when temperature is high AND motor is under heavy load",
    condition={
        "type": "composite",
        "operator": "and",
        "conditions": [
            {
                "type": "threshold",
                "topic": "/sensors/temperature",
                "field": "temp_c",
                "operator": "gt",
                "value": 80
            },
            {
                "type": "threshold",
                "topic": "/motors/joint_3",
                "field": "current_a",
                "operator": "gt",
                "value": 5.0
            }
        ]
    },
    actions=[
        {"type": "tag", "value": "thermal-overload-risk"},
        {"type": "create_event", "event_type": "warning", "label": "Thermal overload risk"},
        {"type": "flag_for_review"},
        {"type": "notify", "channel_id": "ch_abc123"}
    ]
)

const rule = await avala.fleet.rules.create({
  name: "Thermal Overload Risk",
  description: "Triggers when temperature is high AND motor is under heavy load",
  condition: {
    type: "composite",
    operator: "and",
    conditions: [
      {
        type: "threshold",
        topic: "/sensors/temperature",
        field: "temp_c",
        operator: "gt",
        value: 80,
      },
      {
        type: "threshold",
        topic: "/motors/joint_3",
        field: "current_a",
        operator: "gt",
        value: 5.0,
      },
    ],
  },
  actions: [
    { type: "tag", value: "thermal-overload-risk" },
    { type: "create_event", eventType: "warning", label: "Thermal overload risk" },
    { type: "flag_for_review" },
    { type: "notify", channelId: "ch_abc123" },
  ],
});

Rule Actions

Each rule can have one or more actions that execute when its condition matches.

Action	Description	Parameters
`tag`	Add a tag to the recording	`value`: tag string
`create_event`	Create a timeline event marker on the recording	`event_type`, `label`, optional `severity`
`flag_for_review`	Mark the recording for human review in the dashboard	None
`notify`	Send a notification via a configured alert channel	`channel_id`
`auto_label`	Trigger an auto-labeling pipeline on the recording	`pipeline_id`

Actions execute in the order they are defined. If a notify action fails (e.g., Slack webhook returns an error), subsequent actions still execute. Failed actions are logged in the rule evaluation results.

Tag Action

Tags are searchable strings attached to recordings. Use tags to categorize recordings for downstream filtering in the recording browser or SDK queries.

{"type": "tag", "value": "high-latency"}

Create Event Action

Creates a timestamped event marker on the recording at the point where the condition matched.

{"type": "create_event", "event_type": "warning", "label": "High latency detected", "severity": "warning"}

Flag for Review Action

Marks the recording in the dashboard with a review flag. Flagged recordings appear in the “Needs Review” filter in the recording browser.

{"type": "flag_for_review"}

Notify Action

Sends a notification to a configured alert channel. The notification includes the rule name, recording ID, device name, and a link to the recording in the viewer.

{"type": "notify", "channel_id": "ch_abc123"}

Auto-Label Action

Triggers an auto-labeling pipeline on the recording. Useful for running ML inference on recordings that match specific patterns — for example, auto-labeling all recordings tagged with “near-miss” events.

{"type": "auto_label", "pipeline_id": "pipe_abc123"}

Rule Scope

By default, rules apply to all recordings across the fleet. You can narrow a rule’s scope to specific devices or device groups.

# Rule scoped to a specific device group
rule = client.fleet.rules.create(
    name="Warehouse B Temperature Monitor",
    scope={
        "group_ids": ["grp_abc123"]
    },
    condition={
        "type": "threshold",
        "topic": "/sensors/temperature",
        "field": "temp_c",
        "operator": "gt",
        "value": 45
    },
    actions=[
        {"type": "tag", "value": "high-temp"},
        {"type": "create_event", "event_type": "warning", "label": "High ambient temperature"}
    ]
)

# Rule scoped to specific devices
rule = client.fleet.rules.create(
    name="Robot Arm 01 Force Monitor",
    scope={
        "device_ids": ["dev_abc123", "dev_def456"]
    },
    condition={
        "type": "threshold",
        "topic": "/sensors/force",
        "field": "force_n",
        "operator": "gt",
        "value": 50
    },
    actions=[
        {"type": "create_event", "event_type": "anomaly", "label": "Force spike"}
    ]
)

// Rule scoped to a specific device group
const rule = await avala.fleet.rules.create({
  name: "Warehouse B Temperature Monitor",
  scope: {
    groupIds: ["grp_abc123"],
  },
  condition: {
    type: "threshold",
    topic: "/sensors/temperature",
    field: "temp_c",
    operator: "gt",
    value: 45,
  },
  actions: [
    { type: "tag", value: "high-temp" },
    { type: "create_event", eventType: "warning", label: "High ambient temperature" },
  ],
});

Rule Management

List Rules

# List all enabled rules
rules = client.fleet.rules.list(enabled=True)
for rule in rules:
    print(f"{rule.name} ({rule.uid}) -- enabled={rule.enabled}")
    print(f"  Hits: {rule.hit_count} | Last hit: {rule.last_hit_at}")

# Filter by condition type
threshold_rules = client.fleet.rules.list(condition_type="threshold")

const rules = await avala.fleet.rules.list({ enabled: true });
for (const rule of rules.items) {
  console.log(`${rule.name} (${rule.uid}) -- enabled=${rule.enabled}`);
  console.log(`  Hits: ${rule.hitCount} | Last hit: ${rule.lastHitAt}`);
}

avala fleet rules list --enabled
avala fleet rules list --type threshold

Enable and Disable Rules

Pause a rule without deleting it. Disabled rules are preserved with their configuration and hit history.

# Disable a rule
client.fleet.rules.update(rule_id="rul_abc123", enabled=False)

# Re-enable a rule
client.fleet.rules.update(rule_id="rul_abc123", enabled=True)

await avala.fleet.rules.update({ ruleId: "rul_abc123", enabled: false });
await avala.fleet.rules.update({ ruleId: "rul_abc123", enabled: true });

avala fleet rules disable rul_abc123
avala fleet rules enable rul_abc123

Delete a Rule

client.fleet.rules.delete(rule_id="rul_abc123")

await avala.fleet.rules.delete({ ruleId: "rul_abc123" });

avala fleet rules delete rul_abc123

Deleting a rule is permanent. Events and tags previously created by the rule are not removed — only future evaluation stops. If you want to temporarily stop a rule, disable it instead.

Rule Statistics

Each rule tracks evaluation statistics to help you tune conditions and reduce false positives.

Metric	Description
`evaluation_count`	Total number of recordings evaluated against this rule
`hit_count`	Number of recordings that matched the rule’s condition
`hit_rate`	Percentage of evaluations that matched (hit_count / evaluation_count)
`last_hit_at`	Timestamp of the most recent match
`avg_evaluation_ms`	Average time to evaluate the rule against a recording

rule = client.fleet.rules.get(rule_id="rul_abc123")

print(f"Rule: {rule.name}")
print(f"Evaluations: {rule.stats.evaluation_count}")
print(f"Hits: {rule.stats.hit_count} ({rule.stats.hit_rate:.1%})")
print(f"Last hit: {rule.stats.last_hit_at}")
print(f"Avg evaluation time: {rule.stats.avg_evaluation_ms:.0f}ms")

const rule = await avala.fleet.rules.get({ ruleId: "rul_abc123" });

console.log(`Rule: ${rule.name}`);
console.log(`Evaluations: ${rule.stats.evaluationCount}`);
console.log(`Hits: ${rule.stats.hitCount} (${(rule.stats.hitRate * 100).toFixed(1)}%)`);
console.log(`Last hit: ${rule.stats.lastHitAt}`);
console.log(`Avg evaluation time: ${rule.stats.avgEvaluationMs.toFixed(0)}ms`);

Rule Dashboard

The rule dashboard in Mission Control displays all rules with their hit rates, recent matches, and status. From the dashboard you can:

View rule hit rate trends over time
Inspect recent matches with links to the matched recordings
Toggle rules on and off
Duplicate rules as templates for new variations
View evaluation logs for debugging conditions that match unexpectedly (or fail to match)

If a rule has a high hit rate (above 80%), the condition may be too broad. If it has a very low hit rate (below 1%) over a meaningful sample, the condition may be too strict or targeting the wrong topic/field. Use the evaluation logs to inspect individual matches and near-misses.

Next Steps

Alerts & Notifications

Route notifications to Slack, email, and webhooks when rules trigger.

Events & Markers

Understand the timeline events that rules can create automatically.

Fleet Dashboard

Manage devices, recordings, and fleet metrics from the central dashboard.

Data Exploration

Explore recording data interactively before defining rules.

Overview

MCAP & ROS

Panels & Layout

3D Rendering

Fleet Management

Extensions

Guides

How Rules Work

Rule Types

Creating Rules

Threshold Rule

Condition Operators

Pattern Rule

Frequency Rule

Absence Rule

Composite Rule

Rule Actions

Tag Action

Create Event Action

Flag for Review Action

Notify Action

Auto-Label Action

Rule Scope

Rule Management

List Rules

Enable and Disable Rules

Delete a Rule

Rule Statistics

Rule Dashboard

Next Steps

​How Rules Work

​Rule Types

​Creating Rules

​Threshold Rule

​Condition Operators

​Pattern Rule

​Frequency Rule

​Absence Rule

​Composite Rule

​Rule Actions

​Tag Action

​Create Event Action

​Flag for Review Action

​Notify Action

​Auto-Label Action

​Rule Scope

​Rule Management

​List Rules

​Enable and Disable Rules

​Delete a Rule

​Rule Statistics

​Rule Dashboard

​Next Steps

How Rules Work

Rule Types

Creating Rules

Threshold Rule

Condition Operators

Pattern Rule

Frequency Rule

Absence Rule

Composite Rule

Rule Actions

Tag Action

Create Event Action

Flag for Review Action

Notify Action

Auto-Label Action

Rule Scope

Rule Management

List Rules

Enable and Disable Rules

Delete a Rule

Rule Statistics

Rule Dashboard

Next Steps