API Documentation | Broker

Brokers are remote software agents that collect the data from the systems that Circonus is monitoring and feed it back, across an encrypted connection, back to the Circonus system.

Circonus provides several shared public brokers which all SaaS customers can access that can collect information across the public internet. Customers can also install enterprise brokers themselves to collect data from within their datacenters.

Fields

_cid string
The primary key
"/broker/1"
A string containing a broker cid
_details array
Details on every broker that is grouped together
[{"external_host":"example.circonus.net","external_port":8080,"skew":"0.00257706642150879","ipaddress":"75.102.43.87","modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics=>m1","googleanalytics=>m2","googleanalytics=>m3","googleanalytics=>m4","googleanalytics=>m5","googleanalytics=>m6","googleanalytics=>m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"version":1370978917,"minimum_version_required":1367937537,"status":null,"cn":"us1.noit.circonus.net","port":null},"\u2026",{"skew":"0.00357604026794434","ipaddress":"75.102.43.88","external_port":443,"external_host":"example2.circonus.net","minimum_version_required":1367937537,"modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics=>m1","googleanalytics=>m2","googleanalytics=>m3","googleanalytics=>m4","googleanalytics=>m5","googleanalytics=>m6","googleanalytics=>m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"version":1370978917,"cn":"us1b.noit.circonus.net","status":null,"port":null}]
An array
object (zero or more times)
A single broker
An object
cn string
The common name for the broker
A string containing the 'Common Name' part of the broker's SSL certficate
external_host string
The publicly resolvable name the broker can be contacted on.
A string containing a dotted quad formatted IP address or a DNS name
external_port number
The public facing port the broker responds to the Circonus HTTPS REST wire protocol on
An integer 0-65535 (or null, meaning 'default port')
ipaddress string
The IP address address the broker can be contacted on.
A string containing a dotted quad formatted IP address
minimum_version_required number
The minimum version of the broker software that is still compatible with circonus. If the broker's version is less than this, then it is unsupported
A number containing an integer greater than or equal to zero
modules array
What modules (types of checks) this broker supports
An array
string (zero or more times)
The name of the check.
A string containing a check name, as listed in the broker documentation
port number
The port the broker responds to the Circonus HTTPS REST wire protocol on
An integer 0-65535 (or null, meaning 'default port')
skew number
The clock drift between this broker and the Circonus server
A floating point number of seconds
status string
The status of this particular broker
A string containing either 'active', 'unprovisioned', 'pending', 'provisioned' or 'retired'
version number
The version of the broker software the broker is running.
A number containing an integer greater than or equal to zero
_latitude number
The latitude of the broker
"39.043"
A floating point number indicating GPS location
_longitude number
The longitude of the broker
"-77.487"
A floating point number indicating GPS location
_name string
The name of the broker
"Ashburn, VA, US"
A string containing freeform text
_tags array
The tags associated with this broker
["datacenter:primary","foo:bar"]
An array of tags. The tags in the array are automatically sorted, deduplicated and transformed into their lowercase canonical form.
string (zero or more times)
An associated tag
A tag is just a string, with or without a colon, such as 'foo', 'bar', 'datacenter:london', or 'os:linux'. The part of the string before the colon is considered the category the tag is in; Tag strings without a colon will place the string in the 'uncategorized' category. Circonus will lowercase the contents of the string before storing it.
_type string
If this is a public or private broker.
"circonus"
A string containing either 'circonus' (a cloud based broker run by Circonus) or 'enterprise' (an in-house enterprise broker)

Example

Fetching Brokers

Fetching details for a broker is as simple as performing a GET on the broker cid:

GET /broker/1
{"_details":[{"port":null,"external_host":"example.circonus.net","external_port":8181,"ipaddress":"75.102.43.87","skew":"0.000356912612915039","modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"minimum_version_required":1367937537,"version":1370978917,"cn":"us1.noit.circonus.net","status":null},"\u2026",{"external_port":8181,"external_host":"example2.circonus.net","ipaddress":"75.102.43.88","skew":"0.00413227081298828","modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"version":1370978917,"minimum_version_required":1367937537,"cn":"us1b.noit.circonus.net","status":null,"port":null}],"_latitude":"39.043","_type":"circonus","_tags":[],"_cid":"/broker/1","_longitude":"-77.487","_name":"Ashburn, VA, US"}

You'll notice a few important things:

Listing and Filtering Brokers

You can list all the brokers by performing a GET against the endpoint URL itself:

GET /broker
[{"_details":[{"port":null,"cn":"de1.noit.circonus.net","status":"active","ipaddress":"88.198.67.69","skew":"0.15076208114624","external_host":"example.circonus.net","external_port":8181,"modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"minimum_version_required":1367937537,"version":1368216432}],"_longitude":"4.917","_name":"Munich, DE","_type":"circonus","_latitude":"52.35","_tags":[],"_cid":"/broker/4"},{"_details":[{"status":"active","cn":"nl1.noit.circonus.net","modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"minimum_version_required":1367937537,"version":1367937537,"skew":"0.125682353973389","ipaddress":"77.81.242.35","external_port":8181,"external_host":"example.circonus.net","port":null}],"_latitude":"49.1","_type":"circonus","_tags":[],"_cid":"/broker/3","_name":"Amsterdam, NL","_longitude":"10.75"},"\u2026",{"_longitude":"-77.487","_name":"HTTPTrap","_latitude":"39.043","_type":"circonus","_tags":[],"_cid":"/broker/35","_details":[{"status":"active","cn":"trap.noit.circonus.net","minimum_version_required":1367937537,"modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"version":1378265316,"skew":"0.00502610206604004","ipaddress":"192.168.13.81","external_host":"example.circonus.net","external_port":8181,"port":null}]},{"_details":[{"port":null,"ipaddress":"67.207.202.135","skew":"0.113749980926514","external_host":"example.circonus.net","external_port":8181,"minimum_version_required":1367937537,"modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"version":1368216432,"status":"active","cn":"us2.noit.circonus.net"}],"_cid":"/broker/2","_tags":[],"_latitude":"37.339386","_type":"circonus","_longitude":"-120.394956","_name":"San Jose, CA, US"},{"_longitude":"-77.487","_name":"Ashburn, VA, US","_tags":[],"_cid":"/broker/1","_type":"circonus","_latitude":"39.043","_details":[{"cn":"us1.noit.circonus.net","status":"active","modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"version":1370978917,"minimum_version_required":1367937537,"ipaddress":"75.102.43.87","skew":"0.00215816497802734","external_port":8181,"external_host":"example.circonus.net","port":null},{"port":null,"ipaddress":"75.102.43.88","skew":"0.00372862815856934","external_host":"example.circonus.net","external_port":8181,"modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"version":1370978917,"minimum_version_required":1367937537,"status":"active","cn":"us1b.noit.circonus.net"}]},{"_details":[{"port":null,"skew":"0.266650438308716","ipaddress":"121.50.43.59","external_port":8181,"external_host":"example.circonus.net","modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"minimum_version_required":1367937537,"version":1368216432,"cn":"jp1.noit.circonus.net","status":"active"}],"_longitude":"138.166667","_name":"Nagano, JP","_latitude":"36.066667","_type":"circonus","_cid":"/broker/6","_tags":[]},{"_latitude":"51.507222","_type":"circonus","_tags":[],"_cid":"/broker/32","_name":"London, UK","_longitude":"-0.1275","_details":[{"status":"active","cn":"uk1-1.noit.circonus.net","modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"version":1368216432,"minimum_version_required":1367937537,"skew":"0.117046356201172","ipaddress":"109.123.114.82","external_port":8181,"external_host":"example.circonus.net","port":null}]}]

You can apply filters in the usual way, for example to just list circonus brokers:

GET /brokers?f__type=circonus
["\u2026",{"_details":[{"cn":"de1.noit.circonus.net","status":"active","external_host":"example.circonus.net","external_port":8181,"ipaddress":"88.198.67.69","skew":"0.15076208114624","modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"minimum_version_required":1367937537,"version":1368216432,"port":null}],"_cid":"/broker/4","_tags":[],"_type":"circonus","_latitude":"52.35","_name":"Munich, DE","_longitude":"4.917"},{"_details":[{"status":"active","cn":"nl1.noit.circonus.net","external_port":8181,"external_host":"example.circonus.net","skew":"0.125682353973389","ipaddress":"77.81.242.35","version":1367937537,"modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"minimum_version_required":1367937537,"port":null}],"_tags":[],"_cid":"/broker/3","_type":"circonus","_latitude":"49.1","_longitude":"10.75","_name":"Amsterdam, NL"},"\u2026",{"_name":"HTTPTrap","_longitude":"-77.487","_latitude":"39.043","_type":"circonus","_cid":"/broker/35","_tags":[],"_details":[{"port":null,"modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"version":1378265316,"minimum_version_required":1367937537,"external_host":"example.circonus.net","external_port":8181,"ipaddress":"192.168.13.81","skew":"0.00502610206604004","cn":"trap.noit.circonus.net","status":"active"}]},{"_type":"circonus","_latitude":"37.339386","_tags":[],"_cid":"/broker/2","_name":"San Jose, CA, US","_longitude":"-120.394956","_details":[{"modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"version":1368216432,"minimum_version_required":1367937537,"skew":"0.113749980926514","ipaddress":"67.207.202.135","external_host":"example.circonus.net","external_port":8181,"cn":"us2.noit.circonus.net","status":"active","port":null}]},{"_details":[{"port":null,"modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"minimum_version_required":1367937537,"version":1370978917,"skew":"0.00215816497802734","ipaddress":"75.102.43.87","external_host":"example.circonus.net","external_port":8181,"status":"active","cn":"us1.noit.circonus.net"},{"port":null,"status":"active","cn":"us1b.noit.circonus.net","external_port":8181,"external_host":"example.circonus.net","skew":"0.00372862815856934","ipaddress":"75.102.43.88","minimum_version_required":1367937537,"version":1370978917,"modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"]}],"_cid":"/broker/1","_tags":[],"_type":"circonus","_latitude":"39.043","_longitude":"-77.487","_name":"Ashburn, VA, US"},{"_details":[{"port":null,"external_host":"example.circonus.net","external_port":8181,"ipaddress":"121.50.43.59","skew":"0.266650438308716","minimum_version_required":1367937537,"modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"version":1368216432,"cn":"jp1.noit.circonus.net","status":"active"}],"_tags":[],"_cid":"/broker/6","_latitude":"36.066667","_type":"circonus","_longitude":"138.166667","_name":"Nagano, JP"},{"_details":[{"port":null,"cn":"uk1-1.noit.circonus.net","status":"active","skew":"0.117046356201172","ipaddress":"109.123.114.82","external_port":8181,"external_host":"example.circonus.net","version":1368216432,"modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"minimum_version_required":1367937537}],"_cid":"/broker/32","_tags":[],"_latitude":"51.507222","_type":"circonus","_longitude":"-0.1275","_name":"London, UK"}]

Similarly you can just show a named broker:

GET /broker?f__name=London,%20UK
[{"_details":[{"port":null,"ipaddress":"109.123.114.82","skew":"0.117046356201172","external_host":"example.circonus.net","external_port":8181,"modules":["cim","circonuswindowsagent","collectd","dcm","\u2026","dhcp","dns","googleanalytics:m1","googleanalytics:m2","googleanalytics:m3","googleanalytics:m4","googleanalytics:m5","googleanalytics:m6","googleanalytics:m7","haproxy","http","httptrap","imap","jmx","json","ldap","memcached","munin","mysql","newrelic_rpm","nginx","nrpe","ntp","oracle","ping_icmp","pop3","postgres","prometheus","graphite_tls","redis","resmon","selfcheck","smtp","snmp","sqlserver","ssh2","statsd","tcp","varnish"],"minimum_version_required":1367937537,"version":1368216432,"status":"active","cn":"uk1-1.noit.circonus.net"}],"_longitude":"-0.1275","_name":"London, UK","_type":"circonus","_latitude":"51.507222","_tags":[],"_cid":"/broker/32"}]

Modifying Brokers

You can't modify (or for that matter create or delete brokers) with the API. Please use the web interface for this functionality