perfino Help

REST Export API

Introduction

In the perfino UI, the data views have an export button that allows you to extract the displayed data in a machine-readable format for further processing.

Depending on the type of data, the supported formats are JSON, XML and CSV.

To automate external data analysis, as well as to hook up perfino to other monitoring systems, this manual export is impractical. In that case, you can use the REST export API instead.

By default, the REST API service is not made available. You can enable it by setting the "restApi" property in perfino.properties to a non-zero value. The protocol on the configured port is the same as that of the web server, meaning either HTTPS or HTTP.

Once enabled you can make HTTP(S) calls to the configured port to retrieve recorded data. Just like in the web UI, you can request data for single VMs, or ask for cumulated data for a particular VM group.

Using the API

Access to the API is protected with basic HTTP authentication. This means that the API key will only be encrypted when using HTTPS as the protocol. Since the API does not make any modifications, any configured user with an API key can export data with the REST API regardless of the access mode.

You can create an API key by clicking on "API key" menu item in the user drop-down at the top of the perfino UI. You will only see the generated API key once. If you confirm the dialog, the new API key will become active and any previous API key will become invalid.

The returned format depends on the "Accept" header of the HTTP request. The following mime types are supported:

  • text/plain

    The output will be plain text. If multiple columns are available, CSV data is written. For hierarchical data, only the top-level will be exported. The separator is a comma by default, but you can change this with the csvSeparator URL query parameter. The winLineBreak URL query parameter changes the default line feed from LF to CR+LF.

  • application/json

    The output will be in JSON format. Use application/json;charset=UTF-8 to ensure that the output is in UTF-8 encoding regardless of other accept headers.

  • application/xml

    The output will be in XML format.

A call to the REST API consists of one or more URL segments, followed by a list of query parameters. For example, if the configured API port is 8500, a call to 

https://localhost:8500/groups

lists all groups that are configured in perfino. The URL 

https://localhost:8500/transactions/callTree?group=Demo%2FWeb&interval=10min

retrieves the call tree data for the VM group "Demo/Web" for the last 10 minutes. Note the URL-encoded forward slash in the group name.

All start and end times can be specified in milliseconds between the current time and midnight, January 1, 1970 UTC or in one of the following formats:

FormatExampleDescription
yyyy-MM-dd'T'HH:mm:ss.SSS
yyyy-MM-dd'T'HH:mm:ss
yyyy-MM-dd 		2016-03-02T22:40:00.000
2016-03-02T22:40:00
2016-03-02 		Date and time in the local time of the server. All shortened versions will be equal to providing zeros.
yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
yyyy-MM-dd'T'HH:mm:ss'Z'
yyyy-MM-dd'Z' 		2016-03-02T22:40:00.000Z
2016-03-02T22:40:00Z
2016-03-02Z 		Date and time in UTC. All shortened versions will be equal to providing zeros.

API documentation

The following URLs are available:

  • /groups

    Returns a list of all VM groups. The group hierarchy separator is a forward slash. All nodes in the tree table of the recording options are returned in a breadth-first manner. In XML and JSON, the "pool" attribute shows if the group is a VM pool or not.

  • /vms

    Returns a list of VMs. The names include the hierarchical group path as returned by the /groups URL. Individual pool VMs are not returned.
    Query ParameterDescription
    groupA specific group the VMs should be listed from. If unspecified, all VMs are returned.
    connectedIf set to true, only currently connected VMs are returned.

  • /telemetries

    Returns a list of all available telemetry types, to be used in the URL below.

  • /telemetries/{telemetryType}

    Returns the specified telemetry data. The values of {telemetryType} must be one of the values that is returned by the /telemetries URL above.
    Query ParameterDescription
    intervalA telemetry interval. Possible values are 10min, 3h, 3d, 30d
    startTime
    endTime    		You can specify a start or an end time in addition to the interval. For time formats, please see above. If left out, the current time will be used as the end time.
    vm
    group    		You can specify a vm name or a group name. If left out, all VMs will be used.
    prettyIf set to true, JSON and XML output will be pretty printed
    csvSeparatorIf text/plain is requested, you can specify a custom separator char
    winLineBreakIf set to true and if text/plain is requested, CR+LF line breaks will be written instead of LF line breaks.

  • /transactions/{dataType}

    Returns the specified transaction data. Possible values of {dataType} are callTree, hotSpots, overdue and endUser.
    Query ParameterDescription
    intervalA transaction interval. Possible values are 1min, 10min, 1h, 1d
    startTime
    endTime    		You can specify a start or an end time in addition to the interval. For time formats, please see above. If left out, the current time will be used as the end time.
    vm
    group    		You can specify a vm name or a group name. If left out, all VMs will be used.
    mergePoliciesIf set to true, policies will be merged for the data types callTree and hotSpots.
    removeOriginsIf set to false, origins will be shown for data type callTree.
    prettyIf set to true, JSON and XML output will be pretty printed
    csvSeparatorIf text/plain is requested, you can specify a custom separator char
    winLineBreakIf set to true and if text/plain is requested, CR+LF line breaks will be written instead of LF line breaks.

  • /probeHotSpots

    Returns a list of all available probe types to be used in the URL below.

  • /probeHotSpots/{probeType}

    Returns the specified probe hotspot data. The values of {probeType} must be one of the values that is returned by the /probeHotSpots URL above.
    Query ParameterDescription
    intervalA transaction interval. Possible values are 1min, 10min, 1h, 1d
    startTime
    endTime    		You can specify a start or an end time in addition to the interval. For time formats, please see above. If left out, the current time will be used as the end time.
    vm
    group    		You can specify a vm name or a group name. If left out, all VMs will be used.
    mergePoliciesIf set to true, policies will be merged.
    prettyIf set to true, JSON and XML output will be pretty printed
    csvSeparatorIf text/plain is requested, you can specify a custom separator char
    winLineBreakIf set to true and if text/plain is requested, CR+LF line breaks will be written instead of LF line breaks.

  • /alerts

    Returns the specified list of alerts.
    Query ParameterDescription
    startTime
    endTime    		You can specify a start and an end time. If one is left out, one day will be exported. If both are left out the current time will be used as the end time.
    groupYou can specify a group name. If left out, all VMs will be used.
    prettyIf set to true, JSON and XML output will be pretty printed
    csvSeparatorIf text/plain is requested, you can specify a custom separator char
    winLineBreakIf set to true and if text/plain is requested, CR+LF line breaks will be written instead of LF line breaks.

  • /violations

    Returns the specified threshold violation data.
    Query ParameterDescription
    startTime
    endTime    		You can specify a start and an end time. If one is left out, one day will be exported. If both are left out the current time will be used as the end time.
    vm
    group    		You can specify a vm name or a group name. If left out, all VMs will be used.
    prettyIf set to true, JSON and XML output will be pretty printed
    csvSeparatorIf text/plain is requested, you can specify a custom separator char
    winLineBreakIf set to true and if text/plain is requested, CR+LF line breaks will be written instead of LF line breaks.

  • /triggerBackup

    Triggers a backup of the database. The backup files are written to the backup directory inside the perfino data directory. You need to authenticate with an admin user in order to be able to use this URL.

    The return value of this call is the absolute directory path of the backup directory.

    To restore such a backup, stop the perfino server, replace the contents of the "db" directory with the contents of the "backup" directory and start the perfino server again.

    If the REST API is impractical to use, or if you have not activated it for your perfino installation, you can also create a file named trigger_backup in the perfino data directory. After the backup has been completed successfully, the file will be deleted and the backup will be performed.