Skip to content

REST Interface (Reporting Side)

Jump to bottom
Josh Hursey edited this page Nov 20, 2015 · 7 revisions

Reporting Side REST Interface

This page describes the REST interface that faces those MTT tools that need to access the testing database. Primarily, this means the MTT Reporter.

The server is running on a development machine at the following URL:

The interface is broken into three categories of queries:

  • /fields - A listing of the fields available for searching/sorting
  • /summary - Perform a search and report aggregated "summary" data
  • /detail - Perform a search and report "detailed" data
  • /info - Get various amounts of information for a specific phase/item.

Current limitations:

  • Does not support performance data

/fields

Title: Show all search parameter fields and their descriptions.

URL: /fields

Method: GET

URL Params: None

Data Params: None

Example JSON Output:

{
    "detail": {
        "bandwidth_avg": "Bandwidth avg.",
        "bandwidth_max": "Bandwidth max.",
        "bandwidth_min": "Bandwidth min.",
        "configure_arguments": "Configure arguments",
        "description": "Description",
        "environment": "Environment",
        "full_command": "Command",
        "latency_avg": "Latency avg.",
        "latency_max": "Latency max.",
        "latency_min": "Latency min.",
        "launcher": "Launcher",
        "merge_stdout_stderr": "Merge stdout stderr",
        "message_size": "Message size",
        "message_size_range": "Message sizes",
        "mtt_client_version": "MTT version",
        "mtt_version_major": "MTT version major",
        "mtt_version_minor": "MTT version minor",
        "network": "Network",
        "parameters": "Runtime Parameters",
        "resource_mgr": "Resource Manager",
        "result_message": "Result message",
        "result_stderr": "Stderr",
        "result_stdout": "Stdout",
        "start_timestamp": "Date range",
        "submit_timestamp": "Date range",
        "test_result": "Test result",
        "username": "Username",
        "value": "Value"
    },
    "summary": {
        "all_phases": "All phases",
        "bitness": "Bitness",
        "compiler_name": "Compiler",
        "compiler_version": "Compiler version",
        "compute_cluster": "Cluster",
        "duration": "Duration",
        "endian": "Endian",
        "exit_signal": "Signal",
        "exit_value": "Exit value",
        "hostname": "Hostname",
        "http_username": "Org",
        "local_username": "Local username",
        "mpi_get": "MPI get",
        "mpi_install": "MPI install",
        "mpi_install_fail": "MPI install Fail",
        "mpi_install_pass": "MPI install Pass",
        "mpi_name": "MPI name",
        "mpi_version": "MPI version",
        "np": "np",
        "os_name": "OS",
        "os_version": "OS version",
        "platform_hardware": "Hardware",
        "platform_name": "Platform name",
        "platform_type": "Platform type",
        "test_build": "Test build",
        "test_build_fail": "Test build Fail",
        "test_build_pass": "Test build Pass",
        "test_name": "Test",
        "test_run": "Test run",
        "test_run_fail": "Test run Fail",
        "test_run_pass": "Test run Pass",
        "test_run_perf": "Test run Perf",
        "test_run_skip": "Test run Skip",
        "test_run_timed": "Test run Timed",
        "test_suite_name": "Test Suite",
        "trial": "Trial",
        "vpath_mode": "Vpath mode"
    },
    "unsorted": {
        "_build_f": "fail",
        "_build_p": "pass",
        "_mpi_f": "fail",
        "_mpi_p": "pass",
        "_run_f": "fail",
        "_run_l": "latency_bandwidth",
        "_run_p": "pass",
        "_run_s": "skipped",
        "_run_t": "timed_out",
        "bandwidth_avg": "Average Bandwidth",
        "bandwidth_max": "Maximum Bandwidth",
        "bandwidth_min": "Minimum Bandwidth",
        "fail": "Fail",
        "latency_avg": "Average Latency",
        "latency_bandwidth": "Perf",
        "latency_max": "Maximum Latency",
        "latency_min": "Minimum Latency",
        "pass": "Pass",
        "results": "Results",
        "skip": "Skip",
        "skipped": "Skip",
        "submit": "Submit",
        "timed": "Timed",
        "timed_out": "Timed"
    }
}

/summary

Title: Search the database and return aggregated data

URL: /summary

Method: POST

URL Params: None

Data Params:

  • phases: (Required) The phases that you wish to have data for. Accepted values:

    • all All three phases
    • install MPI Install phase only
    • test_build Test Build phase only
    • test_run Test Run phase only

  • columns: (Required) The columns of data that you wish to be returned (includes pass, fail, etc for the given phase). Column names must be one of the values returned by /fields. This is an ordered array of fields that you would like returned.

  • search: (Required) The search parameters as key/value pairs. The keys must be values returned by /fields. The values must be appropriate for that particular key.

    • Timestamp: end_timestamp and start_timestamp required to be in the YYYY-MM-DD HH-MM-SS format.
    • Below are a few additional search parameters to help drill down on aggregated groups of data. If set to 1 then the results will only show rows where this field is non-zero.
      • mpi_install_pass
      • mpi_install_fail
      • test_build_pass
      • test_build_fail
      • test_run_pass
      • test_run_fail
      • test_run_skip
      • test_run_timed

  • options: (Optional)

    • count_only If set to 1 then the query will return a single field containing the count of the number of results that would have been returned. This is useful if you expect a large number of results and want to setup a pagination mechanism.
    • limit If set to a positive value greater than 0 (say L) then it will send at most L results back.
    • offset If set to a positive value (say N) then it will offset N results in the dataset before sending back the data. The limit and offset are useful if paging through a large amount of data.

Data Params Example:

{
    "phases": [
        "test_run"
    ],
    "columns": [
        "http_username",
        "platform_name",
        "platform_hardware",
        "os_name",
        "mpi_name",
        "mpi_version",
        "bitness",
        "compiler_name",
        "compiler_version",
        "test_suite_name"
    ],
    "search": {
        "compiler_name": "gnu",
        "end_timestamp": "2014-10-15 22:00:00",
        "start_timestamp": "2014-10-15 02:00:00"
    }
}

Example JSON Output:

  • status If success then 0 is returned here. If an error occurred then a negative value is returned.
  • status_msg If success then Success, if an error then an appropriate error message is provided.
  • timing The amount of time the server took to process the request from when the request was received to when the data was ready to transmit.
  • fields An ordered list of the fields of data being returned. Will include those fields listed in the columns search parameter plus any additional pass/fail/skip/... fields necessary for that phase.
  • values A 2D array of rows of data.
{
    "status": 0,
    "status_msg": "Success",
    "timing": "0:00:01.693510",
    "fields": [
        "http_username",
        "platform_name",
        "platform_hardware",
        "os_name",
        "mpi_name",
        "mpi_version",
        "bitness",
        "compiler_name",
        "compiler_version",
        "test_suite_name",
        "test_run_pass",
        "test_run_fail",
        "test_run_skip",
        "test_run_timed"
    ],
    "values": [
        [
            "cisco",
            "cisco-community",
            "x86_64",
            "Linux",
            "ompi-nightly-v1.6",
            "1.6.6rc1r31736",
            "64",
            "gnu",
            "4.9.1",
            "ibm",
            0,
            0,
            0,
            32
        ],
        [
            "cisco",
            "cisco-community",
            "x86_64",
            "Linux",
            "ompi-nightly-v1.6",
            "1.6.6rc1r31736",
            "64",
            "gnu",
            "4.9.1",
            "intel",
            701,
            0,
            0,
            9
        ]
    ]
}

Example of a failed search:

{
    "status": -4,
    "status_msg": "Validate Error: Invalid 'column' parameter 'compil'.",
    "timing": "0:00:00.174681",
    "fields": null,
    "values": null
}

/detail

Title: Search the database and return all of the data found (not aggregated)

URL: /detail

Method: POST

URL Params: None

Data Params:

See /summary for the data parameters. They are the same for this view of the data.

  • phases: (Required) The phases that you wish to have data for. Accepted values:
    • install MPI Install phase only
    • test_build Test Build phase only
    • test_run Test Run phase only

Example JSON Output:

See /summary for the data parameters. They are the same for this view of the data.

{
    "status": 0,
    "status_msg": "Success",
    "timing": "0:00:00.010641",
    "fields": [
        "http_username",
        "platform_name",
        "platform_hardware",
        "os_name",
        "mpi_name",
        "mpi_version",
        "compiler_name",
        "configure_arguments"
    ],
    "values": [
        [
            "cisco",
            "cisco-community",
            "x86_64",
            "Linux",
            "ompi-nightly-v1.8",
            "v1.8.3-37-g9208601",
            "gnu",
            "\"CFLAGS=-g -pipe\" --enable-picky --enable-debug --enable-mpirun-prefix-by-default --disable-dlopen"
        ],
        [
            "cisco",
            "cisco-community",
            "x86_64",
            "Linux",
            "ompi-nightly-v1.8",
            "v1.8.3-37-g9208601",
            "gnu",
            "\"CFLAGS=-g -pipe\" --enable-picky --enable-debug --enable-mpirun-prefix-by-default --with-threads --disable-dlopen"
        ],
        [
            "cisco",
            "cisco-community mtt-usnic-248",
            "x86_64",
            "Linux",
            "ompi-nightly-trunk",
            "dev-95-g3d77aba",
            "gnu",
            "\"CFLAGS=-g -pipe -m32\" CXXFLAGS=-m32 FFLAGS=-m32 FCFLAGS=-m32 --with-wrapper-cflags=-m32 --with-wrapper-cxxflags=-m32  --with-wrapper-fcflags=-m32  --enable-mpirun-prefix-by-default --disable-dlopen --enable-mpi-cxx"
        ]
    ]
}

/info

Title: Get various amounts of information for a specific phase/item.

General information interface currently supports the following:

/info/testsuite

Title: Get a listing of the test names in a test suite

URL: /info/testsuite

Method: POST

URL Params: None

Data Params:

  • search: (Required) The search parameters as key/value pairs. The keys must be values returned by /fields. The values must be appropriate for that particular key.
    • Timestamp: end_timestamp and start_timestamp required to be in the YYYY-MM-DD HH-MM-SS format. If no timestamp is specified then a 1 year window is selected.
    • test_suite_name is a required field.

Data Params Example:

{
    "search": {
        "end_timestamp": "2015-01-11 01:00:00",
        "start_timestamp": "2015-01-01 01:00:00",
        "test_suite_name": "trivial"
    }
}

Example JSON Output:

The values are the list of unique test_name value for the specified test_suite_name.

{
    "fields": [
        "test_name"
    ],
    "status": 0,
    "status_msg": "Success",
    "timing": "0:00:00.411695",
    "test_suite_name": "trivial",
    "values": [
        "cxx_ring",
        "ring_usempi",
        "c_ring",
        "hello_usempi",
        "ring_mpifh",
        "ring_usempif08",
        "hello_mpifh",
        "cxx_hello",
        "hello_usempif08",
        "c_hello"
    ]
}

/info/runtime

Title: Get the average duration (runtime) of a specific phase.

URL: /info/runtime

Method: POST

URL Params: None

Data Params:

  • phases: (Required) The phases that you wish to have data for. Accepted values:
    • install MPI Install phase only
    • test_build Test Build phase only
    • test_run Test Run phase only
  • search: (Required) The search parameters as key/value pairs. The keys must be values returned by /fields. The values must be appropriate for that particular key.
    • Timestamp: end_timestamp and start_timestamp required to be in the YYYY-MM-DD HH-MM-SS format. If no timestamp is specified then a 1 year window is selected.
    • If the phase is install then you must specify one or both of mpi_name and/or mpi_version fields
    • If the phase is test_build then you must specify the test_suite_name field
    • If the phase is test_run then you must specify the test_name field

Data Params Example:

MPI Install phase example:

{
    "phases": [
        "install"
    ],
    "search": {
        "end_timestamp": "2015-01-11 01:00:00",
        "mpi_name": "ompi-nightly-master",
        "mpi_version": "dev-641-gc857cc9",
        "start_timestamp": "2015-01-01 01:00:00"
    }
}

Test Build phase example

{
    "phases": [
        "test_build"
    ],
    "search": {
        "end_timestamp": "2015-01-11 01:00:00",
        "start_timestamp": "2015-01-01 01:00:00",
        "test_suite_name": "trivial"
    }
}

Test Run phase example

{
    "phases": [
        "test_run"
    ],
    "search": {
        "end_timestamp": "2015-01-11 01:00:00",
        "start_timestamp": "2015-01-01 01:00:00",
        "test_name": "c_hello"
    }
}

Example JSON Output:

The values are the minimum/average/maximum duration of the test in that give time period.

MPI Install phase example output:

{
    "fields": [
        "min_duration",
        "avg_duration",
        "max_duration"
    ],
    "search": {
        "mpi_name": "ompi-nightly-master",
        "mpi_version": "dev-641-gc857cc9"
    },
    "status": 0,
    "status_msg": "Success",
    "timing": "0:00:00.013815",
    "values": [
        "0:10:33",
        "0:18:26",
        "0:26:19"
    ]
}

Test build phase example output:

{
    "fields": [
        "min_duration",
        "avg_duration",
        "max_duration"
    ],
    "search": {
        "test_suite_name": "trivial"
    },
    "status": 0,
    "status_msg": "Success",
    "timing": "0:00:00.012598",
    "values": [
        "0:00:00",
        "0:00:02",
        "0:00:11"
    ]
}

Test Run phase example output:

{
    "fields": [
        "min_duration",
        "avg_duration",
        "max_duration"
    ],
    "status": 0,
    "status_msg": "Success",
    "search": {
        "test_name": "c_hello"
    },
    "timing": "0:00:00.113664",
    "values": [
        "0:00:00",
        "0:00:01",
        "0:00:26"
    ]
}
Clone this wiki locally