Using Intelligence Cloud CLI

Table of Contents

Generic Parameters
Retrieving Reports
Retrieve Report by ID
Generate Report
Delete Report by ID

Need help?

Schedule a consultation with an Azul performance expert.

The Intelligence Cloud CLI tool provides different functions, each with their own parameters.

Generic Parameters

All tools provided by the CLI support these generic parameters:

Parameter

Description

--apiUrl=<string>

URL of the public API of your Intelligence Cloud instance.
This CLI parameter has the highest priority and overrides the configuration file and environment variables (if specified).

--apiKey=<string>

Key for your Intelligence Cloud instance API.
This CLI parameter has the highest priority and overrides the configuration file and environment variables (if specified).

-v, --version

Show the version of the CLI tool.

-h, --help

Show full help message and exit.

Note	The API URL and key can also be set with environment variables, see Configuring the CLI.

Retrieving Reports

Lists reports of a specified type, including their metadata, but no report content.
The output is printed to the screen by default.
You can save the output to a file by using redirection: ic <options> > output.json.
If invalid parameters are provided or other error occure, the API error message is printed.

Usage

 ic report <type> list \
    [-u=<userId>] \
    [-n=<name>] \
    [-s=<state>] \
    [--from=<from>] \
    [--to=<to>]

Parameters

Parameter

Description

Example

<type>

Report type (required): codeInventory, component, jvm, or avd.

jvm

-u, --userId=<userId>

Filter by user ID.

-u [email protected]

-n, --name=<name>

Filter by full or partial report name.

-n "My Report"

-s, --state=<state>

Filter by report state.
Allowed values: PROCESSING, SUCCEEDED, FAILED, TIMED_OUT.

-s SUCCEEDED

-f, --from=<from>

Filter by request time start in absolute (yyyy-MM-dd’T’HH:mm:ss.SSS or epoch time in ms) or relative format (Xd or Xm for number of days or months).
Default: 7d.

--from 7d

-t, --to=<to>

Filter by request time end in absolute (yyyy-MM-dd’T’HH:mm:ss.SSS or epoch time in ms) or relative format (Xd or Xm for number of days or months).
Default: 0d

--to 0d

Example

 // Input
ic report codeInventory list \
    --userId test@azul.com \
    --name "my report" \
    --state SUCCEEDED \
    --from 7d \
    --to 0d

// Output
[
  {
    "reportName": "Report name",
    "reportId": "1cc40ee6-87a7-4147-b02d-7d26ce0387d0",
    "state": "SUCCEEDED",
    "userId": "[email protected]",
    "params": {
      "filter": [
        "sourceName CONTAINS 'myapp.jar'",
        "className CONTAINS 'com/company/firstclass'",
        "methodName CONTAINS 'mymethod'",
        "AppEnv CONTAINS 'forwarder'"
      ],
      "use": "USED",
      "from": "3d",
      "to": "3d",
      "resolvedFrom": "2023-07-13T16:42:37.268",
      "resolvedTo": "2023-07-13T16:42:37.268"
    },
    "stateMessages": null,
    "requestTime": "2023-07-13T16:42:37.268",
    "startTime": "2023-07-13T16:42:37.268",
    "finishTime": "2023-07-13T16:42:47.231",
    "data": null,
    "totalCount": 35352,
    "totalPages": 10,
    "afterToken": "2"
  }
]

Retrieve Report by ID

Retrieves a report by ID, including metadata and content.
Saves to <reportType>-<reportId>.json or the provided filename.
Pagination is handled automatically.
The maximum output file size is 500MB (this is configurable via the settings file).
If the file size exceeds the maximum allowed value, the report download stops (only a partial report is downloaded) and an error code is returned with this message:
```
 Report size exceeded maximum allowed file size, only 40% of report has been downloaded.
Increase the maxOutputFileSize settings value to download the entire report.
```
The generated file will be called <reportType>-<reportId>-incomplete-40pct.json.
Only reports in a final state are retrievable.
If the report is in the processing state, report <reportId> is processing is returned unless --wait is used.
Use --print to output the result to console. If output file and print are used together, output is saved into a file and also printed to the console.

Usage

 ic report <type> get [-i=<id>] [-p] [-w]

Parameters

Parameter

Description

Example

<type>

Report type (required): codeInventory, component, jvm, or avd.

jvm

-i, --id=<id>

Report ID (required).

-i 1cc40ee6-87a7-4147-b02d-7d26ce0387d0

-o, --output=<string>

Path to the output file. If the report exceeds the maximum allowed size, a partial file with …-incomplete-<percentage>pct.json is generated. Default `<reportType>-<reportId>.json.

-o my-report.json

-p, --print

Output the report content to the console. If used together with an output file, the report will be both saved to the file and printed.

-w, --wait

If the report is in processing state, waits for its completion.

Example

 // Input
ic report codeInventory get --id 1cc40ee6-87a7-4147-b02d-7d26ce0387d0 --print

// Output
{
  "reportName": "Report name",
  "reportId": "1cc40ee6-87a7-4147-b02d-7d26ce0387d0",
  "state": "PROCESSING",
  "userId": "[email protected]",
  "params": {
    "filter": [
      "sourceName CONTAINS 'myapp.jar'",
      "className CONTAINS 'com/company/firstclass'",
      "methodName CONTAINS 'mymethod'",
      "AppEnv CONTAINS 'forwarder'"
    ],
    "use": "USED",
    "from": "3d",
    "to": "3d",
    "resolvedFrom": "2023-07-13T16:42:37.268",
    "resolvedTo": "2023-07-13T16:42:37.268"
  },
  "stateMessages": [
    "1st message",
    "2nd message"
  ],
  "requestTime": "2023-07-13T16:42:37.268",
  "startTime": "2023-07-13T16:42:37.268",
  "finishTime": "2023-07-13T16:42:47.231",
  "data": [
    {
      "sourceName": "myapp.jar",
      "className": "com/company/firstclass",
      "methodName": "getHost(java/lang/String)",
      "firstSeen": "2023-07-13T16:12:51.181",
      "lastSeen": "2023-07-14T11:10:01.112",
      "AppEnv": "abc",
      "tags": [
        "app:credit-service,",
        "owner:finance-team"
      ],
      "used": true
    }
  ]
}

Generate Report

Schedules report generation and waits for its completion.
Polls every 30 seconds for up to 20 minutes (this is configurable via the settings file).
The output is identical to retrieving a report by ID. The only difference is if the report is processing, the tool will wait.
If saving to file, the CLI outputs only the report ID.
If report generation times out on the server or the polling timeouts, the message report <reportId> state: TIME_OUT is shown and no files are created.
If report generation fails (e.g., invalid input), an API error message is displayed along with the report id.

Usage

 ic report <type> generate \
    [-dhpV] \
    [--noWait] \
    [--apiKey=<apiKey>] \
    [--apiUrl=<apiUrl>] \
    [-f=<from>] \
    [--filter=<filter>] \
    [--groupBy=<groupBy>] \
    [-i=<inputFile>] \
    [-n=<name>] \
    [-o=<outputFile>] \
    [--sortBy=<sortBy>] \
    [-t=<to>] \
    [-u=<use>] \
    [-p]

Parameters

<type>

Report type (required): codeInventory, component, jvm, or avd.

jvm

-d, --details

Include extra details (JVM reports only).

-f, --from=<from>

Start of time range in absolute (yyyy-MM-dd’T’HH:mm:ss.SSS or epoch time in ms) or relative format (Xd or Xm for number of days or months).
Default: 7d.

--from 7d

-t, --to=<to>

End of time range in absolute (yyyy-MM-dd’T’HH:mm:ss.SSS or epoch time in ms) or relative format (Xd or Xm for number of days or months).
Default: 0d

--to 0d

-n, --name=<name>

Custom report name.

-n "My JVM Report"

--noWait

Return immediately after scheduling; prints report ID only.

--filter=<filter>

Filter conditions separated by ;, validated by report type.

--filter "methodName CONTAINS 'main'; tags.owner CONTAINS azul"

--sortBy=<fields>

Sort fields separated by ;. Not supported for codeInventory reports.

--sortBy "componentName=ASC; componentVersion=DESC"

--groupBy=<fields>

Grouping fields (JVM reports only).

--groupBy "state; agentVersion"

-p, --print

Print the report to console instead of saving to file.

-u, --use=<string>

Usage filter (codeInventory only). Allows specifing USED, UNUSED, or ALL.
Default: USED.

-u ALL

-o, --output=<string>

Output file path.

-o my-report.json

-i, --input=<string>

Input JSON file that specifies Report parameters based on our API documentation. Allows specifying from, to, report name, filter, sort by, group by, and use.

-i reports/code-inventory.json

Example

 // Input
ic report codeInventory generate \
  --from 7d \
  --to 0d \
  --name "my report" \
  --filter "sourceName CONTAINS 'myapp.jar'; className CONTAINS 'com/company/firstclass'" \
  --sortBy "sourceName=ASC" \
  --noWait

// Output
1cc40ee6-87a7-4147-b02d-7d26ce0387d0

Delete Report by ID

Deletes a report by ID if it exists.
Silent if the report doesn’t exist (no error).

Usage

 ic report <type> delete [-i=<id>]

Parameters

<type>

Report type (required): codeInventory, component, jvm, or avd.

jvm

-i, --id=<id>

Report ID (required).
Identifier of the report to be deleted.

--id 1cc40ee6-87a7-4147-b02d-7d26ce0387d0

Example

 // Input
ic report codeInventory delete --id 1cc40ee6-87a7-4147-b02d-7d26ce0387d0

// Output
// none