Skip to main content

🛠 Rules

Rules are the foundation of how Chipper monitors your lab operations.

A rule defines what pattern Chipper should look for in your log data — such as a specific method running, an error occurring, or a sample being delayed. You can think of a rule as a filter that watches for something meaningful.

📌 Types of Rules​

There are two main types of rules:

1. Instance-Based Rules​

These rules count how many times a specific event occurs.
Example: “If barcode failure happens 3+ times within 10 minutes.”

2. Duration-Based Rules​

These measure how long something takes from start to finish.
Example: “Track how long the Cherrypick method takes to complete.”

🧠 Why Rules Matter​

Rules let you:

  • Detect method execution delays
  • Watch for frequent instrument errors
  • Monitor for unexpected system inactivity
  • Build alerts that trigger based on what you care about

✅ What Happens After a Rule Matches?​

Once a rule matches your log data:

  1. Chipper creates an Event
  2. If the event exceeds a threshold, an Alert is triggered
  3. Alerts can be sent via email, Slack, and shown in dashboards

You can create rules manually or choose from a set of predefined rules in the Rule Bank.

🔍 Chipper Query Language (CQL)​

Chipper uses CQL (Chipper Query Language) to define rule conditions. CQL is a SQL-style expression language that allows you to filter log data using powerful pattern matching.

What is CQL?​

CQL expressions match fields from your log line data (a JSON object). You can use comparison operators, regex patterns, and boolean logic to create precise filtering rules.

Supported Operators​

Comparison Operators​

  • = - Equals (case-insensitive for strings)
  • != - Not equals
  • < - Less than (numeric)
  • <= - Less than or equal to (numeric)
  • > - Greater than (numeric)
  • >= - Greater than or equal to (numeric)

Pattern Matching​

  • ~ - Regex match (Python-style regular expressions, case-sensitive)
  • ~= - Case-insensitive regex match

Membership​

  • IN - Check if value is in a list: field IN ('value1', 'value2')
  • NOT IN - Check if value is not in a list

Boolean Logic​

  • AND - Both conditions must be true
  • OR - Either condition must be true
  • ( ) - Parentheses for grouping expressions

CQL Examples​

Simple equality:

status = 'ERROR'

Substring matching (case-insensitive):

message ~= 'failed to connect'

Regex pattern matching:

message ~ 'Error:\s+(?P<code>\d{3})'

Membership test:

status IN ('ERROR', 'FAILURE', 'TIMEOUT')

Numeric comparison:

temperature >= 37.5

Complex boolean logic:

status = 'ERROR' AND (code >= 500 OR message ~= 'timeout')

Multiple conditions:

method = 'Cherrypick' AND (status = 'Complete' OR status = 'Success')

Negation with NOT IN:

operation NOT IN ('Channel Aspirate', 'Channel Dispense')

Field References​

Fields reference top-level keys from a log line's data object. For example, if your log data looks like:

{
	"method": "Cherrypick",
	"status": "ERROR",
	"temperature": 37.8
}

You can reference method, status, or temperature in your CQL expressions.

Literal Values​

  • Strings: Use single or double quotes: 'value' or "value"
  • Numbers: Plain numbers: 123, 3.14
  • Booleans: true, false

Important Notes​

  • String equality (=) is case-insensitive
  • Numeric comparisons attempt to coerce values to numbers
  • If a field doesn't exist in the log data, comparisons typically evaluate to false
  • Empty CQL string ('') matches all log lines
  • Use regex operators (~, ~=) for substring or pattern matching