Test Results

List test results

Get a list of test results.

GET /api/v1/results/{id}/tests/{?page,limit,filter,sort,format}

URL Parameters

Name Description
page integer (optional) See Paging
limit integer (optional) See Paging
detailed boolean (optional) See Summary / Detailed Representations
filter string (optional) See Filtering
sort string (optional) See Sorting
format string (optional) Choices: json, csv Default: json

Response 200 OK

{
    "timestamp": "2016-04-15T12:53:39.335198176-04:00",
    "data": [
        {
            "id": "20150817160428",
            "seq": "1",
            "loop": "1",
            "active": false,
            "result": "pass",
            "alerts": 0,
            "retries": 0,
            "started": "2015-08-17T16:04:28-04:00",
            "duration": 142,
            "flagged": false,
            "name": "start",
            "description": "CDRouter Startup",
            "skip_name": "",
            "skip_reason": "",
            "log": "start.txt",
            "keylog": "keylog.txt",
            "note": ""
        },
        {
            "id": "20150817160428",
            "seq": "2",
            "loop": "1",
            "active": true,
            "result": "pass",
            "alerts": 0,
            "retries": 0,
            "started": "2015-08-17T16:06:50-04:00",
            "duration": 0,
            "flagged": false,
            "name": "cdrouter_basic_1",
            "description": "Router responds to ARP Request on LAN interface",
            "skip_name": "",
            "skip_reason": "",
            "log": "cdrouter_basic_1.txt",
            "keylog": "keylog.txt",
            "note": ""
        },
        {
            "id": "20150817160428",
            "seq": "3",
            "loop": "1",
            "active": true,
            "result": "skipped",
            "alerts": 0,
            "retries": 0,
            "started": "2015-08-17T16:06:50-04:00",
            "duration": 0,
            "flagged": false,
            "name": "cdrouter_dhcp_1",
            "description": "DHCP client renews lease when current lease expires",
            "skip_name": "",
            "skip_reason": "Test case was skipped due to configuration issues",
            "log": "",
            "keylog": "keylog.txt",
            "note": ""
        }
    ],
    "links": {
        "current": 1,
        "first": 1,
        "last": 4,
        "limit": 3,
        "next": 2,
        "total": 12
    }
}

Response 200 OK with ?format=csv

Content-Type: text/csv
Content-Disposition: inline; filename="{id}.csv"

id,seq,loop,result,retries,started,duration,flagged,name,description,skip_name,skip_reason,log,note
20150817160428,1,1,pass,0,2015-08-17 16:04:28 -0400 EDT,142,false,start,CDRouter Startup,,,start.txt,
20150817160428,2,1,pass,0,2015-08-17 16:06:50 -0400 EDT,0,false,cdrouter_basic_1,Router responds to ARP Request on LAN interface,,,cdrouter_basic_1.txt,
20150817160428,3,1,skipped,0,2015-08-17 16:06:50 -0400 EDT,0,false,cdrouter_dhcp_1,DHCP client renews lease when current lease expires,,Test case was skipped due to configuration issues,,

Get a test result

Get a test result.

GET /api/v1/results/{id}/tests/{seq}

Response 200 OK

{
    "timestamp": "2016-04-15T12:56:59.525566301-04:00",
    "data": {
        "id": "20150817160428",
        "seq": "2",
        "loop": "1",
        "active": true,
        "result": "pass",
        "alerts": 0,
        "retries": 0,
        "started": "2015-08-17T16:06:50-04:00",
        "duration": 0,
        "flagged": false,
        "name": "cdrouter_basic_1",
        "description": "Router responds to ARP Request on LAN interface",
        "skip_name": "",
        "skip_reason": "",
        "log": "cdrouter_basic_1.txt",
        "keylog": "keylog.txt",
        "note": ""
    }
}

Response 404 Not Found

{
    "error": "no such test"
}

Edit a test result

Edit a test result.

PATCH /api/v1/results/{id}/tests/{seq}

Example

PATCH /api/v1/results/20150817160428/tests/2

{
    "flagged": true,
    "note": "something weird here"
}

Response 200 OK

{
    "timestamp": "2016-04-15T12:56:59.525566301-04:00",
    "data": {
        "id": "20150817160428",
        "seq": "2",
        "loop": "1",
        "active": true,
        "result": "pass",
        "alerts": 0,
        "retries": 0,
        "started": "2015-08-17T16:06:50-04:00",
        "duration": 0,
        "flagged": true,
        "name": "cdrouter_basic_1",
        "description": "Router responds to ARP Request on LAN interface",
        "skip_name": "",
        "skip_reason": "",
        "log": "cdrouter_basic_1.txt",
        "keylog": "keylog.txt",
        "note": "something weird here"
    }
}

Get a test result’s log

Get a test result’s log.

GET /api/v1/results/{id}/tests/{seq}/log

URL Parameters

Name Description
offset integer (optional) zero-based line number to start from
limit integer (optional) Lines to return per request
filter string (optional) See Filtering or use the following predefined filters Choices: results, logs, packets, alerts
packets boolean (optional) Omit packets if false
warnings boolean (optional) Omit warnings if false
timestamp_format string (optional) Prefix timestamp field with YYYY-MM-DD if long and log file was generated by CDRouter 10.1 or later Choices: short, long Default: Value of log_timestamp_format in /usr/cdrouter-data/etc/config.yml
format string (optional) Choices: json, html Default: json

Example

Get all unsuccessful DNS packet logs from WAN interfaces destined for 202.254.1.2:

GET /api/v1/results/20150817160428/tests/2/log?filter=packets&filter=interface~^wan&filter=dst=202.254.1.2&filter=proto=DNS&filter=info~*error

Response 200 OK

{
    "timestamp": "2016-09-19T12:21:54.724671698-04:00",
    "data": {
        "offset": 0,
        "limit": 0,
        "lines": [
            {
                "raw": "2016-09-16 10:47:02.114 O>>>(wan-17): 8.8.8.8                                 202.254.1.2                             DNS       Response Name Error",
                "line": 163,
                "prefix": "O>>>",
                "name": "wan",
                "timestamp": "2016-09-16 10:47:02.114",
                "message": "8.8.8.8                                 202.254.1.2                             DNS       Response Name Error",
                "interface": "wan",
                "packet": "17",
                "src": "8.8.8.8",
                "dst": "202.254.1.2",
                "proto": "DNS",
                "info": "Response Name Error"
            },
            {
                "raw": "2016-09-16 10:47:02.119 O>>>(wan-19): 8.8.8.8                                 202.254.1.2                             DNS       Response Name Error",
                "line": 172,
                "prefix": "O>>>",
                "name": "wan",
                "timestamp": "2016-09-16 10:47:02.119",
                "message": "8.8.8.8                                 202.254.1.2                             DNS       Response Name Error",
                "interface": "wan",
                "packet": "19",
                "src": "8.8.8.8",
                "dst": "202.254.1.2",
                "proto": "DNS",
                "info": "Response Name Error"
            },
            {
                "raw": "2016-09-16 10:47:02.617 O>>>(wan-25): 8.8.8.8                                 202.254.1.2                             DNS       Response Name Error",
                "line": 187,
                "prefix": "O>>>",
                "name": "wan",
                "timestamp": "2016-09-16 10:47:02.617",
                "message": "8.8.8.8                                 202.254.1.2                             DNS       Response Name Error",
                "interface": "wan",
                "packet": "25",
                "src": "8.8.8.8",
                "dst": "202.254.1.2",
                "proto": "DNS",
                "info": "Response Name Error"
            }
        ]
    }
}

Get a test result’s log as plaintext

Get a test result’s log as plaintext.

GET /api/v1/results/{id}/tests/{seq}/log?format=text

Response 200 OK

Content-Type: text/plain
Content-Disposition: inline; filename="{log}.txt"

List test metrics

This endpoint was introduced in CDRouter 13.13 and is not available in previous releases of CDRouter.

List test metrics.

Metrics are used by the CDRouter Web UI to generate performance graphs. See the “Performance Graphs” section of the CDRouter Performance User Guide for a list of tests that provide metrics.

GET /api/v1/results/{id}/tests/{seq}/metrics/{?page,limit,detailed,filter,sort}

URL Parameters

Name Description
page integer (optional) See Paging
limit integer (optional) See Paging
detailed boolean (optional) See Summary / Detailed Representations
filter string (optional) See Filtering
sort string (optional) See Sorting

Response 200 OK

{
  "timestamp": "2023-03-10T12:59:00.472558363-05:00",
  "data": [
    {
      "id": "20230310111705",
      "seq": "2",
      "created": "2023-03-10T11:18:15.203028-05:00",
      "updated": "2023-03-10T11:18:15.203028-05:00",
      "test_name": "perf_multi_1",
      "metric": "bandwidth",
      "filename": "perf_multi_1_bandwidth_graph.csv"
    },
    {
      "id": "20230310111705",
      "seq": "2",
      "created": "2023-03-10T11:17:43.160432-05:00",
      "updated": "2023-03-10T11:17:43.160432-05:00",
      "test_name": "perf_multi_1",
      "metric": "client_bandwidth",
      "filename": "perf_multi_1_client_bandwidth_details_graph.1.csv"
    }
  ],
  "links": {
    "current": 1,
    "first": 1,
    "last": 1,
    "limit": 25,
    "total": 2
  }
}

Get a test metric

This endpoint was introduced in CDRouter 13.13 and is not available in previous releases of CDRouter.

Get a test metric. Available metrics are "bandwidth", "latency", "client_bandwidth" and "client_latency".

Metrics are used by the CDRouter Web UI to generate performance graphs. See the “Performance Graphs” section of the CDRouter Performance User Guide for a list of tests that provide metrics that can be accessed through this API endpoint.

GET /api/v1/results/{id}/tests/{seq}/metrics/{metric}/

Example

Get bandwidth test metric.

GET /api/v1/results/20230310111705/tests/2/metrics/bandwidth/

Response 200 OK

{
  "timestamp": "2023-03-10T13:00:49.027516754-05:00",
  "data": [
    {
      "log_file": "perf_multi_1.txt",
      "timestamp": "2023-03-10T11:18:15.19-05:00",
      "metric": "bandwidth",
      "bandwidth": 9416.015,
      "bandwidth_units": "Mbits/sec",
      "result": "pass",
      "client_interface": "lan.*",
      "server_interface": "wan",
      "streams": 10,
      "protocol": "TCP",
      "direction": "download",
      "loss_percentage": 0,
      "loss_percentage_units": "Percentage"
    },
    {
      "log_file": "perf_multi_1.2.txt",
      "timestamp": "2023-03-10T11:22:18.263-05:00",
      "metric": "bandwidth",
      "bandwidth": 9415.996,
      "bandwidth_units": "Mbits/sec",
      "result": "pass",
      "client_interface": "lan.*",
      "server_interface": "wan",
      "streams": 10,
      "protocol": "TCP",
      "direction": "download",
      "loss_percentage": 0,
      "loss_percentage_units": "Percentage"
    },
    {
      "log_file": "perf_multi_1.3.txt",
      "timestamp": "2023-03-10T11:26:21.655-05:00",
      "metric": "bandwidth",
      "bandwidth": 9415.994,
      "bandwidth_units": "Mbits/sec",
      "result": "pass",
      "client_interface": "lan.*",
      "server_interface": "wan",
      "streams": 10,
      "protocol": "TCP",
      "direction": "download",
      "loss_percentage": 0,
      "loss_percentage_units": "Percentage"
    }
  ]
}

Get client_bandwidth test metric.

GET /api/v1/results/20230310111705/tests/2/metrics/client_bandwidth/

Response 200 OK

{
  "timestamp": "2023-03-10T13:02:01.827745676-05:00",
  "data": [
    {
      "timestamp": "2023-03-10T11:17:43.157-05:00",
      "num_rates": 10,
      "rates": [
        941.608,
        941.608,
        942.071,
        941.134,
        941.608,
        941.608,
        941.608,
        941.608,
        941.608,
        941.539
      ]
    },
    {
      "timestamp": "2023-03-10T11:17:44.157-05:00",
      "num_rates": 10,
      "rates": [
        941.788,
        941.533,
        941.266,
        941.742,
        941.695,
        941.788,
        941.266,
        941.649,
        941.788,
        941.788
      ]
    },
    {
      "timestamp": "2023-03-10T11:17:45.157-05:00",
      "num_rates": 10,
      "rates": [
        941.423,
        941.678,
        941.806,
        941.945,
        941.516,
        941.423,
        941.945,
        941.562,
        941.423,
        941.423
      ]
    }
  ]
}

Get latency test metric.

GET /api/v1/results/20230310115215/tests/2/metrics/latency/

Response 200 OK

{
  "timestamp": "2023-03-10T13:03:56.829440891-05:00",
  "data": [
    {
      "log_file": "perf_9.txt",
      "timestamp": "2023-03-10T11:55:19.564-05:00",
      "metric": "latency",
      "total_latency": 83,
      "total_latency_units": "usec",
      "result": "pass",
      "interface": "lan",
      "download_latency": 54,
      "download_latency_units": "usec",
      "upload_latency": 29,
      "upload_latency_units": "usec"
    }
  ]
}

Get a test metric as CSV

This endpoint was introduced in CDRouter 13.13 and is not available in previous releases of CDRouter.

Get a test metric as CSV.

Metrics are used by the CDRouter Web UI to generate performance graphs. See the “Performance Graphs” section of the CDRouter Performance User Guide for a list of tests that provide metrics that can be accessed through this API endpoint.

GET /api/v1/results/{id}/tests/{seq}/metrics/{metric}/?format=csv

URL Parameters

Name Description
format string (required) Must be csv.

Example

Get metric bandwidth in CSV format.

GET /api/v1/results/20160219125014/tests/2/metrics/bandwidth/?format=csv

Response 200 OK

Content-Type: text/csv
Content-Disposition: inline; filename="perf_multi_1_bandwidth_graph.csv"

perf_multi_1.txt,1677619528272,bandwidth,9416.018,Mbits/sec,PASS,lan.*,wan,10,TCP,download,0,Percentage,0,0
perf_multi_1.2.txt,1677619771178,bandwidth,9415.984,Mbits/sec,PASS,lan.*,wan,10,TCP,download,0,Percentage,0,0
perf_multi_1.3.txt,1677620014136,bandwidth,9415.923,Mbits/sec,PASS,lan.*,wan,10,TCP,download,0,Percentage,0,0

Get metric client_bandwidth in CSV format.

GET /api/v1/results/20160219125014/tests/2/metrics/client_bandwidth/?format=csv

Response 200 OK

Content-Type: text/csv
Content-Disposition: inline; filename="perf_multi_1_client_bandwidth_details_graph.1.csv"

1677619496240,10,941.826,941.444,941.444,941.444,941.444,941.444,941.803,941.444,941.814,941.444
1677619497239,10,941.534,941.870,941.534,941.534,941.534,941.592,941.534,941.534,941.684,941.534
1677619498240,10,941.420,941.605,941.941,941.420,941.941,941.883,941.420,941.420,941.420,941.941