Servers

Attributes

id (read-only) Unique server ID.
created (read-only) The time the server was created in UTC seconds.
os (read-only) The OS for this server, either Windows, Linux, or Solaris.
hostname (read-only) The hostname for this server.
nickname The user-defined nickname of the server.
description The user-defined description of the server.
url (read-only) URL information about the requested item.
running (read-only) Boolean indicating whether the server is currently uploading data to AppFirst.
capacity_mem (read-only) The total available memory on the server in bytes.
capacity_cpu_num (read-only) The number of CPU cores on the system.
capacity_cpu_freq (read-only) The frequency of the CPU in MHz.
capacity_disks (read-only) Mapping of the names of the disks (mount points) to their capacity in MB.
current_version (read-only) Version of AppFirst collector that’s running on the server.
location_ip (read-only) IP address that collector is uploading from.
os_detail (read-only) The OS distribution e.g. Ubuntu, RedHat.
arch (read-only) The architecture of the server.
guid (read-only) Unique reference number used as an identifier
network_interfaces (read-only) A system’s (software and/or hardware) interface between two pieces of equipment or protocol layers in a computer network

Available APIs

/api/servers/

Lists all available servers. See above for the attributes each server has.

GET

Return the list of servers matching the query.

Arguments

  • hostname (optional) – Filter the list of servers by hostname.
  • location_ip (optional) – Filter the list of servers by location IP.
  • create_time (optional) – Filter the list of servers that started streaming after the provided create_time parameter. Pass it in as a timestamp in seconds in UTC.
  • limit (optional, default:2500, max:2500) – Sets the page size to a limit set by the user.
  • page (optional, default:0) – Retrieve the specific page of data of size limit.

Argument Examples

  • limit=10 – will get the first page of the first 10 items.
  • limit=25&page=3 – will get the 4th page of size 25 items.
curl --user {EMAIL}:{API_KEY} https://wwws.appfirst.com/api/servers/?hostname='host1'
{
    "pagination": {
        "count": 143, 
        "next": null, 
        "previous": null
    }, 
    "data": [
        {
            "id": 266501, 
            "hostname": "app1sol10", 
            "nickname": "app1sol10", 
            "os": "Solaris", 
            "created": 1422577437, 
            "running": true, 
            "capacity_cpu_freq": 1582, 
            "description": "", 
            "location_ip": "132.85.56.127", 
            "capacity_cpu_num": 2, 
            "capacity_mem": 4294967296, 
            "current_version": 103, 
            "os_detail": "Solaris 5.10", 
            "arch": "sun4v", 
            "guid": "bd34d2d0efdd7418e1f5174f8895366e", 
            "capacity_disks": {
                "rpool/ROOT/s10s_u11wos_24a": 15647, 
                "rpool/export": 9361, 
                "rpool/export/home": 10607, 
                "swap": 1883, 
                "rpool": 9361
            }, 
            "network_interfaces": [
                {
                    "ip": [
                        "0.0.0.0"
                    ], 
                    "friendly_name": "lo0", 
                    "name": "lo0"
                }, 
                {
                    "ip": [
                        "0.0.0.0"
                    ], 
                    "friendly_name": "vnet0", 
                    "name": "vnet0"
                }
            ], 
            "url": "/api/v5/servers/266501/"
        }, 
        {
            "id": 263956, 
            "hostname": "blastoise", 
            "nickname": "blastoise", 
            "os": "Solaris", 
            "created": 1413834978, 
            "running": true, 
            "capacity_cpu_freq": 3100, 
            "description": "", 
            "location_ip": "0.0.0.0", 
            "capacity_cpu_num": 2, 
            "capacity_mem": 3220176896, 
            "current_version": 99, 
            "os_detail": "Solaris 5.10", 
            "arch": "i86pc", 
            "guid": "af905eefe6d61b5eee01cb0a2fac92f6", 
            "capacity_disks": {
                "swap": 2620, 
                "/": 6597
            }, 
            "network_interfaces": [
                {
                    "ip": [
                        "0.0.0.0"
                    ], 
                    "friendly_name": "lo0", 
                    "name": "lo0"
                }, 
                {
                    "ip": [
                        "0.0.0.0"
                    ], 
                    "friendly_name": "e1000g0", 
                    "name": "e1000g0"
                }
            ], 
            "url": "/api/v5/servers/263956/"
        }, 
    ]
}

/api/servers/{server_id}/

View, manage, or delete a server.

GET

Get info about a specific server, given by the server_id in the url. It takes no additional parameters.

curl --user {EMAIL}:{API_KEY} https://wwws.appfirst.com/api/servers/4/
{
    "id": 266501, 
    "hostname": "app1sol10", 
    "nickname": "app1sol10", 
    "os": "Solaris", 
    "created": 1422577437, 
    "running": true, 
    "capacity_cpu_freq": 1582, 
    "description": "", 
    "location_ip": "0.0.0.0", 
    "capacity_cpu_num": 2, 
    "capacity_mem": 4294967296, 
    "current_version": 103, 
    "os_detail": "Solaris 5.10", 
    "arch": "sun4v", 
    "guid": "bd34d2d0efdd7418e1f5174f8895366e", 
    "capacity_disks": {
        "rpool/ROOT/s10s_u11wos_24a": 15647, 
        "rpool/export": 9361, 
        "rpool/export/home": 10607, 
        "swap": 1883, 
        "rpool": 9361
    }, 
    "network_interfaces": [
        {
            "ip": [
                "0.0.0.0"
            ], 
            "friendly_name": "lo0", 
            "name": "lo0"
        }, 
        {
            "ip": [
                "0.0.0.0"
            ], 
            "friendly_name": "vnet0", 
            "name": "vnet0"
        }
    ], 
    "url": "/api/v5/servers/266501/"
}

PUT

Update the information for a specific server. You can only update values that are NOT marked as read-only.

curl --user {EMAIL}:{API_KEY} -X PUT -d "nickname=sample_nickname" https://wwws.appfirst.com/api/servers/2/
{
    "id": 265592, 
    "hostname": "carew", 
    "nickname": "sample_nickname", 
    "os": "Linux", 
    "created": 1417548933, 
    "running": true, 
    "capacity_cpu_freq": 3100, 
    "description": "", 
    "location_ip": "0.0.0.0", 
    "capacity_cpu_num": 1, 
    "capacity_mem": 1073741824, 
    "current_version": 105, 
    "os_detail": "RedHat 2.6.18-371.9.1.el5xen", 
    "arch": "i686", 
    "guid": "b1e24f216e4290fd4bcc7b1ee6b97dfc", 
    "capacity_disks": {
        "/v5/xvda1": 98, 
        "/v5/mapper/VolGroup00-LogVol00": 17699
    }, 
    "network_interfaces": [
        {
            "ip": [
                "0.0.0.0"
            ], 
            "friendly_name": "lo", 
            "name": "lo"
        }, 
        {
            "ip": [
                "0.0.0.0"
            ], 
            "friendly_name": "eth0", 
            "name": "eth0"
        }, 
        {
            "ip": [
                "0.0.0.0"
            ], 
            "friendly_name": "virbr0", 
            "name": "virbr0"
        }
    ], 
    "url": "/api/v5/servers/265592/"
}

DELETE

Delete the server specified in the URL. If the collector is still streaming, this will cause it to stop. It takes no additional parameters.

curl --user {EMAIL}:{API_KEY} -X DELETE https://wwws.appfirst.com/api/servers/4/

/api/servers/{server_id}/data/

Retrieves data for the given server. Each piece of server data has the following attributes:

time The minute this data is for.
cpu The CPU value of this server in percent.
cpu_cores A mapping of each CPU core to its usage in percent.
memory The memory usage of this server in bytes.
disk A mapping of hard disk drive names (mount points) to their current free space in megabytes.
disk_percent The total hard disk usage in percent.
disk_percent_part A mapping of hard disk drive names (mount points) to their current usage in percent.
disk_busy A mapping of each physical disk name to its busy percentage.
page_faults The number of page faults of the server.
process_num The number of processes running on this server.
socket_read The total inbound network traffic.
socket_read_part Inbound network traffic for each interface.
socket_write The total outbound network traffic.
socket_write_part Outbound network traffic for each interface.
thread_num The number of threads running on the server.

GET

Gets data for the given server. It gets up to “num” points starting from “end” and going back “start.”

Arguments

  • num (optional, default:1) – Retrieve up to this many number of points. Note that there can be gaps in the data if the server this process is on has an outage.
  • end (optional, default:most recent point) – Retrieve data from this timestamp backwards. If not given, it gets the most recent data.
  • start (optional) – Don’t retrieve any points before this date, if given. From V3, If both start and num are given, end will be assigned to start + time_step_in_epoch (default to be 60) * num.
  • time_step (optional, default:Minute) – Time step for the points, can be: Minute, Hour, Day.

Argument Examples

  • num=3 – will get the three most recent minutes of data.
  • num=1440&start=<12:00am today> – will get the all of today’s data (which will probably be less than 1440 points).
  • num=3&end=1288584000 – will get the three minutes of data just before Nov. 11, 2010 UTC (which is 1288584000). If all the data exists, this will be 1288584000, 1288583940, and 1288583880. If the middle minute of data didn’t exist it would return 1288584000 and 1288583880.
  • num=30&end=1288584000&start=1288583940 – will get 2 minutes of data (if they exist) from 1288584000 and 1288583940.
  • num=3&time_step=Hour – will get the three most recent hours of data.
curl --user {EMAIL}:{API_KEY} https://wwws.appfirst.com/api/servers/1/data/?num=2
{
    "pagination": {
        "count": 1, 
        "previous": null, 
        "next": null
    }, 
    "data": [
        {
            "diskp_part_rpool/export": -6.3099999999999996, 
            "thread_num": 338, 
            "swrite_sock": 14706, 
            "diskp_part_rpool/export/home": 6.1799999999999997, 
            "socket_num": 5, 
            "cpu_cores": {
                "Processor0": 0.78000000000000003, 
                "Processor1": 1.0900000000000001
            }, 
            "s_time": 0.0, 
            "disk_busy": {
                "vdc0": 0.0
            }, 
            "disk": {
                "rpool/ROOT/s10s_u11wos_24a": 9952, 
                "rpool/export": 9952, 
                "rpool/export/home": 9952, 
                "swap": 1980, 
                "rpool": 9952
            }, 
            "id": 266501, 
            "page_faults": 0, 
            "diskp_part_rpool": -6.3099999999999996, 
            "disk_percent": 17.460000000000001, 
            "diskbusy_part_vdc0": 0.0, 
            "srw_max": 62961.0, 
            "socket_write": 18117, 
            "socket_write_part": {
                "vnet0": 18117.0, 
                "lo0": 0.0
            }, 
            "socket_read": 44844, 
            "srw_part": {
                "vnet0": 62961.0, 
                "lo0": 0.0
            }, 
            "memory": 3537534976, 
            "disk_busy_max": 0.0, 
            "file_read": 164797, 
            "srw_part_vnet0": 62961.0, 
            "srw_part_lo0": 0.0, 
            "registry_num": 0, 
            "diskp_part_swap": -5.1500000000000004, 
            "diskp_max": 36.399999999999999, 
            "file_num": 8, 
            "sread_sock": 26100, 
            "diskp_part_rpool/ROOT/s10s_u11wos_24a": 36.399999999999999, 
            "file_write": 23073, 
            "process_num": 40, 
            "socket_read_part": {
                "vnet0": 44844.0, 
                "lo0": 0.0
            }, 
            "time": 1424102400, 
            "disk_percent_part": {
                "rpool/ROOT/s10s_u11wos_24a": 36.399999999999999, 
                "rpool/export": -6.3099999999999996, 
                "rpool/export/home": 6.1799999999999997, 
                "swap": -5.1500000000000004, 
                "rpool": -6.3099999999999996
            }, 
            "response_num": 0, 
            "cpu": 0.93999999999999995
        }
    ]
}

/api/servers/{server_id}/processes/

Returns the list of processes on a server. See the Processes API documentation for more information about process objects.

GET

Returns the list of processes on a given server. If no arguments are given, it returns the currently running processes. Otherwise it returns any processes that were running between the start and end date given. If you give a start date, you must also give an end date.

  • start (optional) – Start date of range (in secs since epoch) to get processes for.
  • end (optional) – End date of range (in secs since epoch) to get processes for.
#example 1
curl --user {EMAIL}:{API_KEY} https://wwws.appfirst.com/api/servers/1/processes/
{
    "pagination": {
        "count": 31, 
        "previous": null, 
        "next": null
    }, 
    "data": [
        {
            "server_id": 265592, 
            "uid": "265592_1802_13066762974000000", 
            "args": "/usr/sbin/smartd -q never", 
            "pid": "1802", 
            "create_time": "13066762974000000", 
            "name": "smartd"
        }, 
        {
            "server_id": 265592, 
            "uid": "265592_1623_13066762969000000", 
            "args": "sendmail: Queue runner@01:00:00 for /var/spool/clientmqueu", 
            "pid": "1623", 
            "create_time": "13066762969000000", 
            "name": "sendmail.sendmail"
        }, 
    ]
}
#example 2
curl --user {EMAIL}:{API_KEY} https://wwws.appfirst.com/api/servers/1/processes/?start=1295971000&end=1295971300
{
    "pagination": {
        "count": 13, 
        "previous": null, 
        "next": null
    }, 
    "data": [
        {
            "server_id": 11193, 
            "uid": "11193_11316_13066736730000000", 
            "args": "/sbin/udevd --daemon", 
            "pid": "11316", 
            "create_time": "13066736730000000", 
            "name": "udevd"
        }, 
        {
            "server_id": 11193, 
            "uid": "11193_12318_13066736736000000", 
            "args": "/sbin/agetty 38400 tty1 linux", 
            "pid": "12318", 
            "create_time": "13066736736000000", 
            "name": "agetty"
        }, 
    ]
}

/api/servers/{server_id}/processes/data/

Returns the list of a processes’ summary data on a particular server. Each piece of process summary data may have the following attributes (if some data isn’t given it means the values don’t exist for this process for the time step specified):

cpu The CPU value in percent.
memory The memory usage in bytes.
page_faults The number of page faults.
thread_num The number of threads.
socket_write Outbound network traffic in bytes.
socket_read Inbound network traffic in bytes.
socket_num The number of network connections.
file_read Data written to files in bytes.
file_write Data read from files in bytes.
file_num The number of files accessed.
registry_num The number of registries accessed.
critical_log The number of critical incident reports logged.
response_num The number of socket responses sent (you can have multiple responses on a single network/socket connection).

GET

Gets process summary data for the given server. It gets up to “num” points starting from “end” and going back “start.”

Arguments

  • num (optional, default:1) – Retrieve up to this many number of points. Note that there can be gaps in the data if the server this process is on has an outage.
  • end (optional, default:most recent point) – Retrieve data from this timestamp backwards. If not given, it gets the most recent data.
  • start (optional) – Don’t retrieve any points before this date, if given.
  • time_step (optional, default:Minute) – Time step for the points, can be: Minute, Hour, Day.
curl --user {EMAIL}:{API_KEY} https://wwws.appfirst.com/api/v5/servers/1/processes/data/
{
    "pagination": {
        "count": 1, 
        "previous": null, 
        "next": null
    }, 
    "data": [
        {
            "thread_num": 3, 
            "uid": "266501_19555_13067635460000000", 
            "socket_num": 4, 
            "page_faults": 0, 
            "socket_write": 12884, 
            "socket_read": 23200, 
            "memory": 15622144, 
            "file_read": 162792, 
            "args": "output/solaris/collector", 
            "registry_num": 0, 
            "name": "collector", 
            "file_write": 21720, 
            "flags": 0, 
            "time": 1424102520, 
            "file_num": 8, 
            "response_num": 0, 
            "cpu": 0.37
        }
    ]
}

/api/servers/{server_id}/polled_data_config/

Manage the Polled Data config on a server.

GET

Return the Polled Data config on a server.

curl --user {EMAIL}:{API_KEY} https://wwws.appfirst.com/api/servers/1/polled_data_config/
{
    "server_id": 266501, 
    "file_path": "/usr/share/appfirst/plugins/etc/nrpe_appfirst.cfg", 
    "file_type": "Nagios", 
    "file_contents": "", 
    "frequency": 300, 
    "url": "/api/v5/servers/266501/"
}

PUT

Update the Polled Data config on a server.

Arguments

  • file_path (required) – The absolute path of Polled Data Config on the file system. Can’t be empty.
  • file_contents (required) – The content of the Polled Data configuration file.
  • frequency (optional) – The frequency (in seconds) that Nagios scripts / Windows Perf counters will run, must be a multiple of both the Collect Period and 60. Default: 300.
curl --user {EMAIL}:{API_KEY} -X PUT -d "file_contents=Sample+Content&file_path=%2Fusr%2Flocal%2Fnagios%2Fetc%2Fnrpe.cfg" https://wwws.appfirst.com/api/servers/1/polled_data_config/
{
    "server_id": 266501, 
    "file_path": "/usr/share/appfirst/plugins/etc/nrpe_appfirst.cfg", 
    "file_type": "Nagios", 
    "file_contents": "", 
    "frequency": 300, 
    "url": "/api/v5/servers/266501/"
}

/api/servers/{server_id}/tags/

Retrieves the server tag information for a particular server.

GET

Gets the list of all the server tag ID’s for the given server.

curl --user {EMAIL}:{API_KEY} https://wwws.appfirst.com/api/servers/1/tags/
{
    "id": 266501, 
    "hostname": "app1sol10", 
    "server_tags": [
            5, 
            17,
        ],
    "url": "/api/v5/servers/266501/"
}

PUT

Updates the server tags that this server belongs to. This will overwrite any older server tags that this server belongs to.

curl --user {EMAIL}:{API_KEY} https://wwws.appfirst.com/api/servers/1/tags/?server_tags=[1,2,3] -X PUT
{
    "id": 266501, 
    "hostname": "app1sol10", 
    "server_tags": [
            1, 
            2,
            3,
        ],
    "url": "/api/v5/servers/266501/"
}

GET

Trigger auto application detection on this server. The result is a list application name that detected on this server. This API can be triggerred on a sub tenant by providingt the tenant parameter.

Arguments

  • tenant (optional, int) – Only use this parameter if auto detection is going to be triggered on a child tenant.