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, i.e. 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 password will only be encrypted when using HTTPS as the protocol. Since the API does not make any modifications, any configured user regardless of the access mode can export data with the REST API.

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:

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 Parameter	Description
  group	A specific group the VMs should be listed from. If unspecified, all VMs are returned.
  connected	If 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 Parameter	Description
  interval	A 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.
  pretty	If set to true, JSON and XML output will be pretty printed
  csvSeparator	If text/plain is requested, you can specify a custom separator char
  winLineBreak	If 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 Parameter	Description
  interval	A 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.
  mergePolicies	If set to true, policies will be merged for the data types callTree and hotSpots.
  removeOrigins	If set to false, origins will be shown for data type callTree.
  pretty	If set to true, JSON and XML output will be pretty printed
  csvSeparator	If text/plain is requested, you can specify a custom separator char
  winLineBreak	If 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 Parameter	Description
  interval	A 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.
  mergePolicies	If set to true, policies will be merged.
  pretty	If set to true, JSON and XML output will be pretty printed
  csvSeparator	If text/plain is requested, you can specify a custom separator char
  winLineBreak	If 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 Parameter	Description
  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.
  group	You can specify a group name. If left out, all VMs will be used.
  pretty	If set to true, JSON and XML output will be pretty printed
  csvSeparator	If text/plain is requested, you can specify a custom separator char
  winLineBreak	If 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 Parameter	Description
  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.
  pretty	If set to true, JSON and XML output will be pretty printed
  csvSeparator	If text/plain is requested, you can specify a custom separator char
  winLineBreak	If 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.