<p class="shortdesc">Custom monitoring provides you with the function of customizing monitoring items. The custom monitoring function of Ping AnCloud uploads the monitoring data using API. </p> <section class="section" id="repot__section_i5v_w2w_mjb"><h2 class="doc-tairway">Request parameter </h2> <table class="table frame-all" id="repot__table_q1r_kxw_mjb"><caption></caption><colgroup><col style="width:10.959885386819483%"><col style="width:8.595988538681947%"><col style="width:7.163323782234957%"><col style="width:9.455587392550143%"><col style="width:63.825214899713465%"></colgroup><thead class="thead"> <tr class="row"> <th class="entry" id="repot__table_q1r_kxw_mjb__entry__1">Parameter name</th> <th class="entry" id="repot__table_q1r_kxw_mjb__entry__2">Position</th> <th class="entry" id="repot__table_q1r_kxw_mjb__entry__3">Essentialness</th> <th class="entry" id="repot__table_q1r_kxw_mjb__entry__4">Type</th> <th class="entry" id="repot__table_q1r_kxw_mjb__entry__5">Description</th> </tr> </thead><tbody class="tbody"> <tr class="row"> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__1 "> <p class="p">PA-AG-AppId </p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__2 "> <p class="p">Header</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__3 "> <p class="p">Yes</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__4 "> <p class="p">String</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__5 "> <p class="p">AppId is the identification when you allocate API.</p> <p class="p">When you use the function for the first time, you need to click <span class="ph uicontrol">Custom Monitoring</span> in the left navigation pane of the <a class="xref" href="https://pinganyun.com/console/argus/overview" target="_blank">Argus Console</a>,then click <span class="ph uicontrol">Open Custom Monitoring</span>. After opening, system will automatically distribute the AppId needed to call interface for you.</p> <div class="note note note_note"><span class="note__title">Note:</span> <p class="p">The security certification of this API requires the certification mode of Access Key ID & Access Key Secret, so you need to provide Access Key ID and Access Key Secret for the certification.</p> </div> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__1 "> <p class="p">PA-AG-OAC-AccessKeyId</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__2 "> <p class="p">Header</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__3 "> <p class="p">Yes</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__4 "> <p class="p">String</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__5 "> <p class="p">Ping An Cloud API allocation authentication.</p> <p class="p">You can obtain <span class="ph uicontrol">Access Key ID </span> by clicking <span class="ph menucascade"><span class="ph uicontrol">Account Info</span><abbr title="and then"> > </abbr><span class="ph uicontrol">Access Key</span></span> in the upper-right corner of the official website of Ping An Cloud.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__1 "> <p class="p">PA-AG-AppId</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__2 "> <p class="p">Header</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__3 "> <p class="p">Yes</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__4 "> <p class="p">String</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__5 "> <p class="p">For more information about signing character string, see <a class="xref" href="#repot__section_wnx_lkx_mjb">Signature Algorithm</a>for .</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__1 "> <p class="p">PA-AG-Timestamp</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__2 "> <p class="p">Header</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__3 "> <p class="p">Yes</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__4 "> <p class="p">Int</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__5 "> <p class="p">Timestamp at millisecond level, with 15-minute validity term.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__1 "> <p class="p">PA-AG-GroupId </p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__2 "> <p class="p">Header</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__3 "> <p class="p">Yes</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__4 "> <p class="p">String</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__5 "> <p class="p">Grouping ID. Fixed value: 1f009720-19d7-4433-9372-642a39c1f14e.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__1 "> <p class="p">PA-AG-Content-Digest </p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__2 "> <p class="p">Header</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__3 "> <p class="p">Yes</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__4 "> <p class="p">String</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__5 "> <p class="p">Request for MD5 value of Body, uploading the MD5 value of Body for verification when the Body request is not empty.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__1 "> <p class="p">PA-AG-RequestId</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__2 "> <p class="p">Header</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__3 "> <p class="p">False</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__4 "> <p class="p">String</p> </td> <td class="entry" headers="repot__table_q1r_kxw_mjb__entry__5 "> <p class="p">The allocator can upload using the requested UUID. If the allocator doesn’t upload, the system would generate one automatically in order to help locate errors.</p> </td> </tr> </tbody></table> </section> <section class="section" id="repot__section_wnx_lkx_mjb"><h2 class="doc-tairway">Signature Algorithm</h2> <p class="p" id="repot__p_j51_1hz_zjb"><strong class="ph b">1. Create a Character String to Sign </strong></p> <p class="p" id="repot__p_m51_1hz_zjb">The constructing formula of API signing character string is as follow, of which <code class="ph codeph">\n</code> means newline escape character, and <code class="ph codeph">+</code> means concatenated operation of the character string. For more information, see the following table for the description of other parts.</p> <pre class="pre codeblock" id="repot__codeblock_l51_1hz_zjb"><code>String strToSign = HttpMethod + "\n" + URI + "\n" + Headers + "\n" + ContentDigest</code></pre> <table class="table frame-all" id="repot__table_xcm_rkx_dkb"><caption></caption><colgroup><col style="width:40.4040404040404%"><col style="width:59.5959595959596%"></colgroup><thead class="thead"> <tr class="row"> <th class="entry align-left" id="repot__table_xcm_rkx_dkb__entry__1">Name</th> <th class="entry" id="repot__table_xcm_rkx_dkb__entry__2">Description</th> </tr> </thead><tbody class="tbody"> <tr class="row"> <td class="entry align-left" headers="repot__table_xcm_rkx_dkb__entry__1 "> <p class="p">HttpMethod</p> </td> <td class="entry" headers="repot__table_xcm_rkx_dkb__entry__2 "> <p class="p">Names of HTTP request methods, such as PUT, GET, POST etc.</p> </td> </tr> <tr class="row"> <td class="entry align-left" headers="repot__table_xcm_rkx_dkb__entry__1 "> <p class="p"> URI</p> </td> <td class="entry" headers="repot__table_xcm_rkx_dkb__entry__2 "> <p class="p">Uniform Resource Identifier, filling “/api/v1/global_push” here.</p> </td> </tr> <tr class="row"> <td class="entry align-left" headers="repot__table_xcm_rkx_dkb__entry__1 "> <p class="p"> Headers</p> </td> <td class="entry" headers="repot__table_xcm_rkx_dkb__entry__2 "> <p class="p">Headers refers to the character strings of Key, Value concatenation in the headers participating in signature computing. Headers participating in signature computing include other verification-needed headers filled in <span class="ph uicontrol">PA-AG-Timestamp</span> and <span class="ph uicontrol">PA-AG-Signature-Headers</span>. Headers are case-insensitive.</p> <p class="p"><strong class="ph b">Headers Concatenation Method</strong></p> <p class="p">First, concatenate the Key of Headers participating in signature computing in the following method after sorting them according to the dictionary order. If there is an Header with empty Value, use HeaderKey.toLowercase() + ":"to participate signing. Key and the English colon ": " should be reserved, and there should be no blank character on the left or right side of Key and Value. There might be multiple Values of Header, and if so, sort them according to the dictionary order of Value to participate signature computing.</p> <pre class="pre codeblock"><code>String headers = HeaderKey1.toLowercase() + ":" + HeaderValue1.toLowercase() + "\n"\+ HeaderKey2.toLowercase() + ":" + HeaderValue2.toLowercase() + "\n"\+ ... HeaderKeyN.toLowercase() + ":" + HeaderValueN.toLowercase() + "\n"</code></pre> </td> </tr> <tr class="row"> <td class="entry align-left" headers="repot__table_xcm_rkx_dkb__entry__1 "> <p class="p">ContentDigest</p> </td> <td class="entry" headers="repot__table_xcm_rkx_dkb__entry__2 "> <p class="p">MD5 Value of Body, participate the calculation only when the requesting Body exists. The calculating method is:</p> <pre class="pre codeblock"><code>String contentDigest = Base64.encodeBase64(MD5(requestBody.getbytes("UTF-8")));</code></pre> </td> </tr> </tbody></table> <p class="p" id="repot__p_w3n_mhz_zjb"><strong class="ph b">2. Calculate Signature</strong></p> <p class="p" id="repot__p_y3n_mhz_zjb">The formula of compute signature is as follows:</p> <pre class="pre codeblock"><code>Mac hmacSha256 = Mac.getInstance("HmacSHA256"); byte[] keyBytes = secret.getBytes("UTF-8"); hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, "HmacSHA1")); String sign = new String(Base64.encodeBase64(hmacSha256.doFinal(strToSign.getBytes("UTF-8")),"UTF-8"));</code></pre> <div class="note note note_note" id="repot__note_z3n_mhz_zjb"><span class="note__title">Note:</span> <ol class="ol" id="repot__ol_lwh_24r_njb"> <li class="li">The signature algorithm is HmacSHA1</li> <li class="li">The secret is Access Key Secret, which is used for authentication allocated by Ping AnCloud API. You can obtain <span class="ph uicontrol">Access Key Secret </span><span class="ph menucascade"><span class="ph uicontrol"></span><abbr title="and then"> > </abbr><span class="ph uicontrol"></span></span> by clicking <span class="ph menucascade"><span class="ph uicontrol">Account Information</span><abbr title="and then"> > </abbr><span class="ph uicontrol">Access Key</span></span> in the upper-right corner of the official website of Ping An Cloud.</li> </ol> </div> <p class="p" id="repot__p_bjn_mhz_zjb"><strong class="ph b">3. Transform Signature</strong></p> <p class="p" id="repot__p_cjn_mhz_zjb">Put the signature calculation result into the Heaser of Request, the Key is PA-AG-Signature.</p> <ul class="ul" id="repot__ul_bzq_l4r_njb"> <li class="li"> <p class="p">Allocating address: https://apigw.yun.pingan.com/api/v1/global_push</p> </li> <li class="li"> <p class="p">Request agreement: HTTPS</p> </li> <li class="li"> <p class="p">Request method: POST</p> </li> </ul> <p class="p" id="repot__p_djn_mhz_zjb"><strong class="ph b">Request Example</strong></p> <pre class="pre codeblock" id="repot__codeblock_ejn_mhz_zjb"><code>{ "data": [{ "tags": "microservice=pay,bad_request=500" //Metric Name "value": 100, //Reported Value "step": 60, //Reporting Frequency "counterType": "GAUGE", //Collecting Method "timestamp": 1537783931 //Timestamp }] }</code></pre> <table class="table" id="repot__table_vlv_q4r_njb"><caption><span class="table--title-label">Table 1. </span><span class="title">Parameter Description of the Request Example</span></caption><colgroup><col style="width:17.76198934280639%"><col style="width:18.117229129662523%"><col style="width:17.939609236234453%"><col style="width:46.18117229129662%"></colgroup><thead class="thead"> <tr class="row"> <th class="entry" id="repot__table_vlv_q4r_njb__entry__1">Parameter name</th> <th class="entry" id="repot__table_vlv_q4r_njb__entry__2">Type</th> <th class="entry" id="repot__table_vlv_q4r_njb__entry__3">Essentialness</th> <th class="entry" id="repot__table_vlv_q4r_njb__entry__4">Description</th> </tr> </thead><tbody class="tbody"> <tr class="row"> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__1 "> <p class="p">data</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__2 "> <p class="p">array</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__3 "> <p class="p">Yes</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__4 "> <p class="p">Key-value form, batch data reporting is supported. Array form is no more than 1000, and transmission size of body is no more than 2MB.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__1 "> <p class="p">tags</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__2 "> <p class="p">string</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__3 "> <p class="p">Yes</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__4 "> <p class="p">The form of metric name must be a set of key and value separated by comma, with the maximum length of no more than 250 characters, for example “microservice=pay,bad_request=500”, which represents the micro service named as pay with the return code of 500.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__1 "> <p class="p">value</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__2 "> <p class="p">float64</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__3 "> <p class="p">Yes</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__4 "> <p class="p">Metric value</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__1 "> <p class="p">step</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__2 "> <p class="p">int</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__3 "> <p class="p">Yes</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__4 "> <p class="p">Reporting the frequency of monitoring data with the unit of second.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__1 "> <p class="p">counterType</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__2 "> <p class="p">string</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__3 "> <p class="p">Yes</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__4 "> <div class="p">You may choose COUNTER or GAUGE (pay attention to the capitalization):<ul class="ul" id="repot__ul_hmk_dpr_njb"> <li class="li">COUNTER: representing that the collected data type is timer, and the indicator would be calculated as speed, which means (current value - last time value) / time duration, when it is stored and displayed.</li> <li class="li">GAUGE: representing that it is the original value, which is the unchanged value in storage, uploaded by user.</li> </ul></div> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__1 "> <p class="p">timestamp</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__2 "> <p class="p">long</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__3 "> <p class="p">Yes</p> </td> <td class="entry" headers="repot__table_vlv_q4r_njb__entry__4 "> <p class="p">The unix timestamp when the data is reported.</p> </td> </tr> </tbody></table> <p class="p" id="repot__p_w5b_nhz_zjb"><strong class="ph b">Return Example</strong></p> <pre class="pre codeblock" id="repot__codeblock_x5b_nhz_zjb"><code>{ "data": { "invalid": 0, "total": 1 }, "code": "0", "msg": "success" }</code></pre> <table class="table" id="repot__table_zds_lpr_njb"><caption><span class="table--title-label">Table 2. </span><span class="title">Parameter Description of the Return Example</span></caption><colgroup><col style="width:33.33333333333333%"><col style="width:66.66666666666666%"></colgroup><thead class="thead"> <tr class="row"> <th class="entry" id="repot__table_zds_lpr_njb__entry__1">Parameter name</th> <th class="entry" id="repot__table_zds_lpr_njb__entry__2">Description</th> </tr> </thead><tbody class="tbody"> <tr class="row"> <td class="entry" headers="repot__table_zds_lpr_njb__entry__1 "> <p class="p">data.invalid</p> </td> <td class="entry" headers="repot__table_zds_lpr_njb__entry__2 "> <p class="p">Invalid reporting quantity</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_zds_lpr_njb__entry__1 "> <p class="p">data.total</p> </td> <td class="entry" headers="repot__table_zds_lpr_njb__entry__2 "> <p class="p">Total reporting quantity, and the successful reported quantity equals to: data.total- data.invalid.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_zds_lpr_njb__entry__1 "> <p class="p">code</p> </td> <td class="entry" headers="repot__table_zds_lpr_njb__entry__2 "> <p class="p">code=0, representing that API is successfully allocated. code=1, representing that API is unsuccessfully allocated.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_zds_lpr_njb__entry__1 "> <p class="p">msg</p> </td> <td class="entry" headers="repot__table_zds_lpr_njb__entry__2 "> <p class="p">Return information.</p> </td> </tr> </tbody></table> <p class="p" id="repot__p_sym_nhz_zjb"><strong class="ph b">Exception Example</strong></p> <pre class="pre codeblock" id="repot__codeblock_tym_nhz_zjb"><code>{ "code": "-1", "msg": "the length of upload data array is too large", "requestId":"AG-c3644612-f5c4-4881-864c-0e9f7203d1a9" } </code></pre> <table class="table" id="repot__table_uvy_spr_njb"><caption><span class="table--title-label">Table 3. </span><span class="title">Parameter Description of the Exception Example</span></caption><colgroup><col><col><col></colgroup><thead class="thead"> <tr class="row"> <th class="entry" id="repot__table_uvy_spr_njb__entry__1">Error Code</th> <th class="entry" id="repot__table_uvy_spr_njb__entry__2">Error Information</th> <th class="entry" id="repot__table_uvy_spr_njb__entry__3">Solutions</th> </tr> </thead><tbody class="tbody"> <tr class="row"> <td class="entry" headers="repot__table_uvy_spr_njb__entry__1 "> <p class="p">-1</p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__2 "> <p class="p">Overlength Reporting Data.</p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__3 "> <p class="p">Examine whether the length of reported data is over 1000.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_uvy_spr_njb__entry__1 "> <p class="p">AG-101</p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__2 "> <p class="p">Request unidentified </p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__3 "> <p class="p">Check required parameters according to common parameters.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_uvy_spr_njb__entry__1 "> <p class="p">AG-102</p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__2 "> <p class="p">Wrong request parameter </p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__3 "> <p class="p">Check parameter according to return information msg.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_uvy_spr_njb__entry__1 "> <p class="p">AG-103</p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__2 "> <p class="p">Incorrect signature </p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__3 "> <p class="p">Check whether the original signature is correctively concatenated according to return information strToSign, and chek AppID.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_uvy_spr_njb__entry__1 "> <p class="p">AG-104 </p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__2 "> <p class="p">Application not found</p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__3 "> <p class="p">Check whether the AppID exists.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_uvy_spr_njb__entry__1 "> <p class="p">AG-105 </p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__2 "> <p class="p">API not authorized </p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__3 "> <p class="p">Check whether the allocated AppId has the permission of this API.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_uvy_spr_njb__entry__1 "> <p class="p">AG-107 </p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__2 "> <p class="p">Expired request </p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__3 "> <p class="p">Check whether the PA-AG-Timestamp has expired.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_uvy_spr_njb__entry__1 "> <p class="p">AG-110</p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__2 "> <p class="p">The User account is overdue </p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__3 "> <p class="p">Recharge your Ping An Cloud account.</p> </td> </tr> <tr class="row"> <td class="entry" headers="repot__table_uvy_spr_njb__entry__1 "> <p class="p">Other Errors</p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__2 "> <p class="p">Other Error Information</p> </td> <td class="entry" headers="repot__table_uvy_spr_njb__entry__3 "> <p class="p">Please connect to administrator or submit a ticket.</p> </td> </tr> </tbody></table> </section>