API for JVM Inventory

Table of Contents

Request Report Generation
Retrieve the Report
Delete a Report
- Example Request
- Example Response

Need help?

Schedule a consultation with an Azul performance expert.

The JVM Inventory API allows you to create and download reports to get insights into your connected JVM runtimes.

Reports are generated asynchronously. By using the endpoint, a task to generate a report is created. In response, you get a unique report identifier. With this identifier, you can retrieve the report.

Request Report Generation

You can request the generation of a report with a POST call to https://YOUR_ENDPOINT.azul.com/public/report/jvmInventory and a set of parameters.

Request Parameters

Argument Default Description

filter

array[string]

Array of filters for one or more of the following:

hostName
vmId
tags
state

from

string

Relative or absolute time for the start of the report. See API Date Filter Format.

string

Relative or absolute time for the end of the report. See API Date Filter Format.

groupBy

array[string]

List of fields by which the components (name + version) are grouped. The order of the fields directly affects the result of the grouping. The values of the groupBy fields are presented in the data items of the response. In addition, the count field corresponding to the number of VMs included in each group is returned.

Format: <field_name>.

Note	The count field can be used to sort data, for example, using `count=ASC`.

Note	To group by time period, use the keywords `year`, `month`, `week`, or `day`. When using `week`, the week number of the year is used (`Calendar.WEEK_OF_YEAR`).

sortBy

array[string]

A set of fields and the desired sort order for their values.

Format: <field_name>=<sort_order>.

Sort order values:

ASC - ascending
DESC - descending

Example Request

 curl -X 'POST' \
  'https://YOUR_ENDPOINT.azul.com/report/jvmInventory' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: l91uNwWPDt5z2oa13wmQAPDfGv5Ti4T7bEQZKoXg' \
  -d '{
  "filter": [
    "hostName = 'localhost'",
    "vmId != 'a79b38cd-787b-4203-ba6d-9197c0e3fe19'",
    "tags.owner CONTAINS 'elena'",
    "state = 'SUCCEEDED'"
  ],
  "groupBy": [
    "state",
    "agentVersion"
  ],
  "sortBy": [
    "lastHeardTime=DESC",
    "tags.owner=DESC"
  ],
  "from": "3d",
  "to": "3d",
  "reportName": "My report #1"
}'

Example Response

In response, you get a reportId that can be used with the GET endpoint to retrieve the report.

 {
  "reportId": "1cc40ee6-87a7-4147-b02d-7d26ce0387d0",
  "state": "PROCESSING",
  "userId": "[email protected]",
  "params": {
    ...
  },
  "requestTime": "2023-02-15T00:00:00.000Z"
}

Retrieve the Report

You can retrieve a report with a GET call to /public/report/jvmInventory/YOUR_REPORT_ID.

The response must be checked to define if the data is available, based on the following possible return data:

state: State of the request, one of the following options:
- PROCESSING
- SUCCEEDED
- FAILED
- PARTIALLY_FAILED
- TIMED_OUT
stateMessages: More info related to the state.
errors: Errors while creating the report (if applicable).

Large reports are split into pages (up to 5.5MB per page). You can find the total number of pages in the response and use this value to retrieve all the report pages.

Note	Regardless of whether a report is generated successfully or not, when the generation is finished, at least one page of the report is available for retrieval.

Example Request

 curl -X 'GET' \
  'https://YOUR_ENDPOINT.azul.com/public/report/jvmInventory/YOUR_REPORT_ID' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json'

Report Fields

Each JVM runs in its own environment which can be described by AppEnv, system variables, tags, state, startTime, etc. The request parameters allow you to see your fleet from different perspectives, such as what OS is used, what version of Java, etc.

Argument	Definition	Description
AppEnv	not null, can be UNDEFINED if not specified	Custom AppEnv tag value, used to specify the customer domain, see CRS Configuration Options.
vmId	not null, immutable	VM ID, represented by a UUID.
state	not null, mutable	State of a specific VM.
startTime	not null, immutable	Date and time of the launch of a specific VM, see API Date Filter Format.
lastHeardTime	not null, mutable	Last date and time a JVM has sent a heartbeat, see API Date Filter Format.
agentVersion	not null, immutable	Version of the IC agent used on the JVM side.
agentRevision	not null, immutable	Revision of the IC agent used on the JVM side.
java.runtime.version	not null, immutable	System Property provided by a JVM.
java.specification.version	not null, immutable	System Property provided by a JVM.
java.vendor	not null, immutable	System Property provided by a JVM.
java.version	not null, immutable	System Property provided by a JVM.
java.vm.name	not null, immutable	System Property provided by a JVM.
java.vm.vendor	not null, immutable	System Property provided by a JVM.
java.vm.version	not null, immutable	System Property provided by a JVM.
os.arch	not null, immutable	System Property provided by a JVM.
os.name	not null, immutable	System Property provided by a JVM.
os.version	not null, immutable	System Property provided by a JVM.
tags	can be empty, immutable	List of tags associated with a specific JVM, see CRS Configuration Options.

Argument

Definition

Description

AppEnv

not null, can be UNDEFINED if not specified

Custom AppEnv tag value, used to specify the customer domain, see CRS Configuration Options.

vmId

not null, immutable

VM ID, represented by a UUID.

state

not null, mutable

State of a specific VM.

startTime

not null, immutable

Date and time of the launch of a specific VM, see API Date Filter Format.

lastHeardTime

not null, mutable

Last date and time a JVM has sent a heartbeat, see API Date Filter Format.

agentVersion

not null, immutable

Version of the IC agent used on the JVM side.

agentRevision

not null, immutable

Revision of the IC agent used on the JVM side.

java.runtime.version

not null, immutable