DASHBOARD FORMAT · VERSION 1

Publish a server dashboard

Send server values and display instructions in one JSON report. CronPulse displays metrics, status labels, tables, images, and notices.

Connect a reporter

A reporter is a program that collects server data and sends it to CronPulse.

Open Servers.
Create or select a server.
Select Set up status reporting.
Open Reporter connection details.
Copy the private reporting URL.
Save your JSON report as snapshot.json.
Send the file to the private URL.

curl --fail --silent --show-error \
  -H 'Content-Type: application/json' \
  --data-binary @snapshot.json \
  'YOUR_PRIVATE_REPORTING_URL'

You can start with the file-sync example. Replace its example readings with your server values.

Send a JSON object with a state object every five minutes. Schedule the reporter on the source server.

The URL links the report to its server monitor. Keep the URL private.

The monitor sends heartbeat warnings if reports arrive late. Its configured interval sets that deadline.

Describe the view

Put the server values and a dashboard definition inside state. The definition contains the display instructions.

Include the definition in every report. Each check-in saves the full object in history.

{
  "state": {
    "dashboard": {
      "version": 1,
      "title": "Service overview",
      "sections": [{
        "type": "metrics",
        "title": "Capacity",
        "items": [{
          "label": "Free storage",
          "path": "/space",
          "format": "bytes"
        }]
      }]
    },
    "space": 1073741824
  }
}

Set version to 1. Set sections to a list of sections.

You can set a dashboard title. Each section can also have a title and a plain-text description.

CronPulse displays labels and descriptions as text. Definitions cannot run HTML, scripts, templates, or expressions.

Section type	Required values
`metrics`	Displays metric cards. Set `items` to a list of field definitions.
`fields`	Displays labels and values. Set `items` to a list of field definitions.
`table`	Set `path` to a JSON Pointer for the row array. Set `columns` to a list of field definitions. Each column path starts at its row.
`images`	Set `path` to a JSON Pointer for the image array. Set `image_path` to a JSON Pointer for the image ID in each record. Use JSON Pointers for `caption_path` and `captured_at_path` too.
`notice`	Set `text` to the notice. You can also set `tone` to choose its status color.

Each field requires a label and a path. A field can also have format and rules.

If you omit format, CronPulse uses text.

You do not need to register server names or change the Rails application to publish this format.

Paths and values

A path is a JSON Pointer string. It identifies a value inside the report.

/storage/free selects the free value inside storage.
/items/0/name selects name from the first item in an array.
Use ~1 for a slash within a key name.
Use ~0 for a tilde within a key name.
An empty path selects the current root object.
Array positions start at 0. Do not add leading zeros.

Section paths and metric paths start at state. Table column paths start at each table row.

Image ID, caption, and capture-time paths start at each image record.

A missing path, null, an object, or an array displays as Unavailable in a field for one value.

Zero and false are valid values. Use null when a measurement is unknown.

Do not substitute zero or 100% for an unknown measurement.

Format	Display
`text`	Text, a boolean, or a number.
`number`, `count`	A number with separators. CronPulse keeps all digits in an integer.
`bytes`, `bytes_per_second`	A value of zero or more in binary units. 1024 bytes equals 1 KiB.
`duration_seconds`, `duration_ms`	A duration of zero or more. CronPulse displays days, hours, minutes, and seconds as needed.
`percent`	A number from 0 to 100, with a progress bar.
`timestamp`	An ISO timestamp with a timezone. CronPulse displays the time in UTC.
`status`	A status label. Display rules can set its text and color.

A text value such as "42" is not a number for numeric formats. Send 42 to report a number.

The full JSON view keeps the original values. Point to a formatted reading to see its original value.

Publish private images

Upload each image before you send the report that refers to it.

Send a PNG to POST /monitors/:id/:access_key/images.
Use the server monitor's ID and key.
Send the file in multipart field image.
Read the returned image id.
Put that ID in a normal server report.

See the image API instructions for the upload command and response.

The upload response contains id, uploaded_at, expires_at, width, and height.

An upload does not record a check-in or change the heartbeat deadline.

Image limits:

PNG format only.
Maximum file size: 4 MiB.
Maximum dimensions: 4096 × 4096 pixels.
Maximum active images per monitor: 2000.
Maximum combined active-image size per monitor: 1 GiB.
Expiry time: 24 hours after upload.

Use this object as the contents of state. Replace RETURNED_IMAGE_UUID with the ID from the upload response.

{
  "dashboard": {
    "version": 1,
    "sections": [{
      "type": "images",
      "title": "Desktops",
      "path": "/desktops",
      "image_path": "/image_id",
      "caption_path": "/name",
      "captured_at_path": "/captured_at"
    }]
  },
  "desktops": [{
    "name": "Worker desktop",
    "image_id": "RETURNED_IMAGE_UUID",
    "captured_at": "2026-10-24T15:30:00Z"
  }]
}

Each image must belong to the same server monitor. External URLs, file paths, and HTML cannot act as image sources.

The owner must sign in to view thumbnails or full images. Each upload creates a new ID.

Old reports keep their original IDs. If an image expires or is missing, CronPulse displays an unavailable-image message.

Record the capture time

captured_at_path is optional. Set it to a JSON Pointer for the source capture time. For example, /captured_at selects that field in each image record.

Include a timezone in that timestamp. CronPulse displays the time in UTC.

The upload time is separate. CronPulse sets it when it receives the image.

If capture fails, use null for the image ID. Add a notice or status field to explain the failure.

If you use an older capture, keep its original capture time. Do not label an old image as a new capture.

Each image section displays up to 20 records. The full JSON view keeps all records in the report.

Declare status rules

A display rule selects a status color and can set a label. CronPulse checks the rules in their listed order.

The first matching rule controls the display. If no rule matches, the display uses a neutral color.

Set tone to healthy, warning, critical, or neutral.

{
  "label": "Copy process",
  "path": "/running",
  "format": "status",
  "rules": [
    {"op":"eq", "value":true, "tone":"healthy", "label":"Running"},
    {"op":"eq", "value":false, "tone":"critical", "label":"Stopped"}
  ]
}

Use these comparison operators:

eq: equals.
ne: does not equal.
lt: is less than.
lte: is less than or equal to.
gt: is greater than.
gte: is greater than or equal to.

Equality uses the JSON value type. False differs from 0, and text "0" differs from number 0.

Numbers 1 and 1.0 compare as equal. Use finite numbers for ordered comparisons. Infinity and NaN are not valid values.

Missing values, null, objects, and arrays do not match display rules. On other field formats, a matching rule adds a label beside the formatted value.

Display rules control appearance. They do not send emails.

A fresh report can contain a stopped worker or a critical value. A recent check-in does not prove every task is healthy.

Configure email conditions

Save email rules separately from the dashboard definition.

Open Servers.
Select a server.
Select Add condition alert.
Enter an Alert name.
Select a Metric.
Select a Condition.
Select the Value type.
If the condition needs a value, enter the Comparison value.
Set Consecutive bad reports to a number from 1 to 12.
Select Enable alerts for this condition.
Select Create condition alert.

Use the form's Other reported field controls to enter a custom JSON Pointer.

For example, compare a lag value with 60 seconds. For a connection flag, compare its value with false.

Use the units in the reported field. Use seconds for a field that contains seconds.

Only the verified owner can save email rules. Reported JSON and display rules cannot enable or change them.

CronPulse checks conditions when reports arrive. You can require multiple matching reports in a row.

CronPulse sends one alert while a condition stays active. You can also enable a recovery email.

For normal comparisons, missing/null values and wrong data types cannot close an open alert. Use an unavailable condition to monitor missing/null values.

Heartbeat warnings remain separate. They identify late reports.

Limits and fallback

The JSON-encoded state can be up to 64 KiB for a server monitor. This limit includes the dashboard definition.

Job monitors have a separate 16 KiB limit.

Sections per dashboard: 20.
Items per metrics or fields section: 24.
Columns per table: 16.
Display rules per field: 12.
Characters per label or title: 200.
Characters per description or notice: 2000.
Characters per path: 500.
Visible rows per table: 100.
Visible records per image section: 20.

The full JSON view keeps the additional table rows and image records.

If a definition is missing, invalid, or unsupported, CronPulse still saves otherwise valid state and records the heartbeat.

The page explains the display problem. You can still inspect the full JSON.

If state is invalid or too large, CronPulse rejects the check-in. It does not change the heartbeat or history.

Send the full state and definition with every report. A new report replaces the previous state.

Open your servers