5.7.1 Plug-in processing execution
- Description
-
Executes any functional operation for a plug-in.
- Execution permissions
-
See Appendix E.1 Operating permissions required for system monitoring using the Intelligent Integrated Management Base in the JP1/Integrated Management 3 - Manager Overview and System Design Guide.
If you specify _performanceDataGet for the method parameter when JP1/PFM is linked, the Admin or Operator permissions must be granted to the execution user for the resource group of the JP1/PFM agent.
- API version
-
v1
- Format
-
- Request line
POST /application/component/apiVersion/actions httpVersions
- Request message body
{ "method": function-name, "sid": target-IM-management-node-SID, "args": operation-specification }
- Response message body
result-of-the-operation
- Parameters
-
- method
-
Specify the name of the plug-in function to execute. A function name starting with double underscores (__) is not allowed.
The following function is provided by default:
Function name
Plug-in
Operation
_performanceDataGet
JP1/PFM plug-in
Getting performance information
- sid
-
Specify the IM management node to be operated with the plug-in, in the SID format of configuration information. Only the IM management node at the end of the system configuration tree can be specified.
For details on the SID, see 7.1 SID.
- args
-
Specify the values to pass to the args.methodArgs argument of the plug-in function to execute. If there is no information to be passed, specify an empty object ({}).
The size of specified values must be less than 10 MB including other parameters.
The following table describes what value is passed to args.methodArgs when the method parameter is set to _performanceDataGet:
No.
Member name
Data type
Optional
Description
1
recordId
string
No
Specify the record ID to be retrieved. Only uppercase characters can be used.
The prefix of the record ID, PI_, PD_, or PL_ can be omitted.
For example, if the prefix is PI_, you can specify LOGD instead of PI_LOGD.
Note that if another record that has a different prefix but has the same record ID excluding the prefix exists, it is assumed that both records are specified.
2
fieldIds
string[]
Yes
Specify the fields you get as an array. Only uppercase characters can be used.
If you want to get performance data of specific fields, specify the field IDs# in array format.
- #
-
The format is record-ID_PFM-Manager-name. For CPU% of the PD_PDI record, the field ID is PD_PDI_PCT_PROCESSOR_TIME. If this member is omitted, all the fields in the specified record are output. If an empty value is specified (that is, fieldIds:[ ]), it is assumed that this member is omitted.
Note that the data below (key field needed to identify the record) is output even if the field ID is omitted. For details on the key fields, see the manual of each agent.
- Historical report (single agent)
- "Date and Time" field
- ODBC key field
3
startTime
string
No
Specify the start date and time of reporting. Use the ISO8601 extended format (YYYY-MM-DDThh:mm:ssZ). The letter Z at the end of the time indicates the UTC timezone. In the timezone other than UTC, use the format of +hh:mm or -hh:mm.
4
endTime
string
No
Specify the end date and time of reporting.
Use the ISO8601 extended format (YYYY-MM-DDThh:mm:ssZ) for the date and time of the UTC timezone. The letter Z at the end of the time indicates the UTC timezone. In the timezone other than UTC, use the format of +hh:mm or -hh:mm.
5
interval
string
No
Specify the interval of reporting. Use the format below. It is case insensitive.
-
MIN: In minutes
-
HOUR: In hours
-
WEEK: Weekly
-
DAY: Daily
-
MONTH: Monthly
-
YEAR: Yearly
The interval is ignored when specified for a PD record.
6
filter
object[]
Yes
Specify this member if you want to filter the performance data you get by its field value. Filtering is possible for more than one field.
If you specify multiple filter conditions, the system retrieves the performance data that meets all the conditions (AND condition).
If an empty value is specified (that is, filter:[ ]), it is assumed that this member is omitted.
7
limit
number
Yes
Specify the maximum number of records to be retrieved. The possible values are from 1 to 4320.
If this member is omitted, it is assumed that the specified value is 4320. Specifying a value other than permitted values generates an error, causing the operation to stop.
The following table describes the format of the object you specify for filter:
No.
Member name
Data type
Optional
Description
1
fieldId
string
No
Specify the filter ID of the field to be filtered. Only uppercase characters can be used.
2
operator
string
Yes
Specify the filter condition for performance data you get. Select one of the following values:
-
=: The value of the field is equal to value.
-
<>: The value of the field is not equal to value.
-
<: The value of the field is less than value.
-
<=: The value of the field is less than or equal to value.
-
>: The value of the field is greater than value.
-
>=: The value of the field is greater than or equal to value.
If this member is omitted, it is assumed that = is specified.
3
value
string
No
Specify the value according to the field format described in the manuals for JP1/PFM - Agent or JP1/PFM - RM. Note the following description for the ranges:
- - Character
-
The specified value is applied as it is. However, * is handled as a wildcard character.
- - Integer
-
An integer must be within the acceptable range of the data type for the field, which is from -2,147,483,648 to 2,147,483,647.
However, the check range of the ulong (unsigned long) data type can be extended by specifying the condExpValueUlongExtension parameter in config.xml for JP1/PFM - Web Console.
For details on the config.xml parameter, see the JP1/Performance Management Reference.
- - Decimal number
-
Specify a value within the acceptable range of the data type for the field.
If the format of the target field is float or double, and the field value has four decimal places or more, the value is rounded off to the third decimal place.
If the format of the target field is utime and the field value has seven decimal places or more, the value is rounded off to the sixth decimal place.
For details on the format of the field, see the description of each field in the manuals for JP1/PFM - Agent or JP1/PFM - RM.
- - Date
-
Specify the date and time in ISO8601 extended format (YYYY-MM-DDThh:mm:ssZ). The letter Z at the end of the time indicates the UTC timezone. In the timezone other than UTC, use the format of +hh:mm or -hh:mm. (The time always uses the HH:mm:ss format.)
Note that an error occurs if any of control characters, (, ), [, ], <, >, =, and " is contained in the value. The acceptable number of bytes is a maximum of 2,048 bytes.
- Status codes
-
The following table describes the status codes that are returned as a response to the request:
Status code
Message
Description
200
None
Plug-in execution succeeded.
400
KAJY22003-E
The request has a parameter with an invalid format.
403
KAJY22004-E
There is no permission to access the specified IM management node.
500
KAJY22005-E
An error occurred during the plug-in processing.
For details on the messages, see the JP1/Integrated Management 3 - Manager Messages.
- Return values
-
No.
Member name
Data type
Description
1
--
object
The object in which the execution result of the plug-in processing is stored. The return value of the plug-in function is assigned to the object.
The following table describes the return value when the method parameter is set to _performanceDataGet:
No.
Member name
Data type
Description
1
component
string
Component name
This is always set to HITACHI/JP1/PFM/CONFINFO.
2
productId
string
Product ID of the agent whose performance data is to be retrieved
3
dataModelVersion
string
Data model version of the agent whose performance data is to be retrieved
4
rc
number
Return code
-
0: Data was retrieved successfully.
-
1: Data was retrieved successfully but some records were not retrieved due to limit.
-
2: There is no data in the specified period.
5
fields
object[]
Array of field information objects
6
data
string[][]
Two dimensional array of performance data, in [row data][column data] format.
The output order of the column data guarantees the output order of the field information.
The data and time data is returned as the data and time in the UTC timezone in ISO8601 extended format (YYYY-MM-DDThh:mm:ssZ). Any timezone other than UTC is not supported. In addition, if dataType of the output data is one of FOLAT, DOUBLE, or SECTIMEDOUBLE and its value is less than 10 to the negative third power or greater than or equal to 10 to the seventh power, the value is output in floating point format (such as 1.01E10).
The following table describes the format of the field information object:
No.
Member name
Data type
Description
1
id
string
Field ID
2
displayName
string
Display name of the field
3
dataType
string
Data type of the field:
-
STR: String
-
SHORT: 16-bit integer
-
INT: 32-bit integer
-
LONG: 64-bit integer
-
FLOAT: 32-bit single-precision floating-point number
-
DOUBLE: 64-bit double-precision floating-point number
-
SECTIMELONG: Long value that indicates the time (in seconds) since a particular point in time#1
-
SECTIMEDOUBLE: Double value that indicates the time (in seconds) since a particular point in time#1
-
MILLTIME: Long value that indicates the time (in milliseconds) since a particular point in time#1
-
DATE: Data that represents only the year, month, and day (yyyy-MM-DDThh:mm:ssZ)
-
DATETIME: Data that represents the year, month, day, and time (hour, minute, and second) (yyyy-MM-DDThh:mm:ssZ)
-
TIME: Data that represents only the time (yyyy-MM-DDThh:mm:ssZ, only the time is output as the information.)
4
keyType
string
Key attribute of the field needed for identifying data (record)#2
-
DATE
It must be specified in one field of all fields, and indicates that the field is a key to identifying the time.
-
INST
It is specified in zero or more fields of all fields, and indicates that the field is a key specific to data (record).
-
NONE
It indicates that the field is not a key.
- #1
-
The point in time serving as a reference depends on the fields. See each field (field in utime format) of JP1/PFM - Agent or JP1/PFM - RM.
- #2
-
The following table lists the combination of key attributes required to identify the data (record):
Report type
Record type
Combination of attributes required for data identification
Historical report
(Single agent)
Single row record
-
DATE
Multi-row record
-
DATE
-
INST
-
- Examples
-
The example below uses the API in the following scenario:
-
The functionality to use: JP1/PFM plug-in for getting performance information
-
JP1/PFM manager host name: mgrhost1
-
JP1/PFM agent host name: agenthost1
-
Target IM management node: JP1/Performance Management - Agent Option for Platform (For Windows)
-
The monitoring item to be retrieved: CPU usage
-
Output start time: April 1, 2017 00:00:00 JST
-
Output end time: April 1, 2017 01:00:00 JST
- Request:
POST /im/api/v1/actions HTTP/1.1 Authorization:Bearer xxxx Accept-Language: ja Content-Type: application/json Accept: application/json { "method": "_performanceDataGet", "sid": "_JP1PFM-M_MGRHOST1/_JP1PFM-AHOST_AGENTHOST1/_HOST_AGENTHOST1/_JP1PFM-A_TA1agenthost1", "args": { "recordId": "PI", "fieldIds": ["PI_PCT_TOTAL_PROCESSOR_TIME"], "startTime": "2017-04-01T00:00:00+09:00", "endTime": "2017-04-01T01:00:00+09:00", "interval":"HOUR" } }
- Response:
{ "component": "/HITACHI/JP1/PFM/CONFINFO", "productId": "T", "dataModelVersion": "8.4", "rc": 0, "fields": [ { "id": "PI_DATETIME", "displayName": "Date and Time", "dataType": "DATETIME", "keyType": "DATE" }, { "id": "PI_PCT_TOTAL_PROCESSOR_TIME", "displayName": "CPU %", "dataType": "FLOAT", "keyType": "NONE" } ], "data": [ [ "2017-03-31T15:00:00Z", "14.04" ], [ "2017-03-31T16:00:00Z","13.55" ] ] }
-