Synchronize agent measurement series

What you need

A current server-profile agent and synchronization enabled for your monitor. An owner or editor must explicitly allow agent configuration writes on a key assigned only to this Server monitor.

How to do it

1. Set collection_sync and server_profile to true and device_id to the bound server monitor UUID in your private agent configuration. Use the Measurement series tab to select server parameters or locally approved checks and preview changes before saving.
2. Run metribeacon agent metrics list --json. For example, change collection using metribeacon agent metrics update --source-id catalog/system/cpu_usage --interval 60. Commands add, enable, disable and remove use the same protected configuration.
3. Check the agent status in Measurement series. With a healthy connection, executable source and free quota, configuration changes reach both sides within five seconds; a reading follows when the check finishes.

Good to know

The last server-accepted change wins for each changed field. Names and descriptions never create another history. Removing an agent series stops collection and retains history; its alarms require explicit reactivation. Unchanged states keep their separate refresh interval of at least 270 seconds.

Declare custom program outputs in your administrator-protected collector policy with a stable custom/ source_id, component_id, parameter_key, kind and unit. Approved programs return JSON values and optional counter_epochs. Only declared fields are sent; commands and arguments stay local. Maximum runtime: 60 seconds; output: 64 KiB. A one-off metric send uses an external/ identity and does not schedule a recurring check.

Have an administrator approve your executable and its SHA-256 in the existing collector policy. Replace the executable path and hash in this example and retain source_id when renaming. The program writes only the following JSON to standard output. Store secrets locally, outside this declaration.

{
  "version": 1,
  "targets": [
    {
      "component": {
        "id": "program:queue",
        "kind": "program",
        "label": "Queue",
        "local_ref": "queue"
      },
      "program": {
        "executable": "/usr/local/libexec/my-queue-check",
        "arguments": [],
        "sha256": "REPLACE_WITH_THE_EXECUTABLE_SHA256",
        "timeout_seconds": 5,
        "outputs": [
          {
            "source_id": "custom/queue-depth",
            "component_id": "program:queue",
            "parameter_key": "queue_depth",
            "kind": "gauge",
            "unit": "items",
            "name": "Queue depth",
            "description": "",
            "interval_seconds": 30,
            "available": true
          }
        ]
      }
    }
  ]
}

{"values":{"queue_depth":42},"counter_epochs":{}}

If something goes wrong

During an outage the last confirmed configuration keeps running. Local changes wait in a private queue of at most 256 operations. Inspect collection/collection.settings.json below your configured spool directory; only name, description, enabled and interval_seconds are editable. Do not change identities, confirmed snapshots or pending operation IDs. Missing definitions, permissions and invalid output appear as explicit statuses.