[APIC]Increase logging with a custom policy for IBM DataPower in the API Connect assembly

http://www.ibm.com/developerworks/library/mw-1610-phillips-trs/index.html?ca=drs-&ce=ism0070&ct=is&cmp=ibmsocial&cm=h&cr=crossbrand&ccy=us

Increase logging with a custom policy for IBM DataPower in the API Connect assembly

Create alerts for error diagnosis

Chris Phillips and Jack Dunleavy
Published on October 14, 2016

FacebookTwitterLinked InGoogle+E-mail this page

API Connect version:
This tutorial requires IBM API Connect version 5.0.2.0 or later with an IBM DataPower Gateway.

When you design and develop custom integration policies, you need to be alerted to any problems with your policies. By defining a custom logging policy to log the values of context variables, you can be quickly alerted to where policies might be malfunctioning so that you can correct any errors.

This tutorial describes a user-defined policy to assist with logging and error diagnosis in the API Connect assembly tool. In this policy, custom strings or context variables can be written directly to IBM® DataPower® logs at any point when running an API. By defining such policy, messages can be written at any priority level. And, when you combine API Connect with the capability of DataPower to selectively listen at different priorities, you get straightforward yet powerful logging and diagnosis when designing an API.

Policies in API Connect

With the API Connect assembly tool, you can add transformations and logic to the runtime behavior of your APIs. You can use the assembly to create complicated flows that feature logical constructs, such as if and switch statements. You can also create data manipulation mechanisms, such as field redaction, JSON-to-XML, and input-to-output mapping. These actions are called policies. You can connect and organize them by dragging the tiles to the assembly.

The writeToDatapowerLog policy

To address the identified challenges in logging error diagnosis when using the assembly, you can use a user-defined policy. In this article, we use and describe the writeToDatapowerLog policy. (You can download this policy from the "Downloadable resources" section at the end of this article.)

You import this policy into API Connect as a compressed (.zip) file. The compressed file contains all the files that are required for DataPower to run the policy rule at run time, in addition to a YAML file that describes the policy parameters and metadata. No extraction or manipulation of the archive is required.

To use the policy, import the compressed file into API Connect. After you import it, the policy is displayed in the assembly, as shown at the bottom of the following figure, and is ready for use.

You can now drag the policy to the assembly as many times as required. Each instance of the tile holds its own, distinct configuration. The policy uses the following two parameters:

• logLevel. This parameter indicates the priority level of the logged message. DataPower has a series of priority levels that range from info to critical. The levels are available from a drop-down list within the policy configuration.
• Message. This parameter refers to the message to be written to the DataPower logs. The Message parameter fully supports the DataPower runtime context variables.

The following figure shows an example assembly that uses two separate instances of the writeToDatapowerLog policy.

The following figures show the configuration in the API Connect assembly for both instances. The first instance (see the following figure) shows a message for a critical situation.

The second instance (see the following figure) uses context variable support to log the API name within the log error message.

The results from these instances in the API call are displayed in the DataPower logs as shown in the following figure. Both messages shown in this figure were created according to the policy configuration that we described previously. The first message at the top shows the name of the API (writetodatapowerlog-api), as expanded from the context variable reference $(api.name). The second message at the bottom is logged at a critical level as specified in the first instance.

Both messages are part of the gatewayscript-user category because the main rule logic is described by using gatewayscript in DataPower. The following section shows an expanded version of rule coding for the policy.

The gatewayscript code

The main execution of the policy is built around the following gatewayscript.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51

function writeToDatapowerLog()                 {       var apic = require('local://isp/policy/apim.custom.js');     var props = apic.getPolicyProperty(),         apiName = apic.getContext('api.name'),         m = props.message;       if (props === undefined) {         console.error('The policy properties were not retrieved for policy: writeToDatapowerLog.');         return;     }       if  (apiName === undefined || apiName === '') {         console.error('The name of the API for this call could not be determined.');     }       switch(props.logLevel) {         case 'info':             console.info('The API: \"' + apiName + '\" has logged the following message: ' + m); break;         case                 'notice':             console.notice('The API: \"' + apiName + '\" has logged the following message: ' + m); break;         case                 'warn':             console.warn('The API: \"' + apiName + '\" has logged the following message: ' + m); break;         case                 'error':             console.error('The API: \"' + apiName + '\" has logged the following message: ' + m); break;         case                 'critical':             console.critical('The API: \"' + apiName + '\" has logged the following message: ' + m); break;         case                 'alert':             console.alert('The API: \"' + apiName + '\" has logged the following message: ' + m); break;         case                 'emerg':             console.emerg('The API: \"' + apiName + '\" has logged the following message: ' + m); break;         case                 'log':             console.log('The API: \"' + apiName + '\" has logged the following message: ' + m); break;         case                 'trace':             console.trace('The API: \"' + apiName + '\" has logged the following message: ' + m); break;         default:             console.error('The logLevel chosen: ' + props.logLevel + ' was not recognised');     }     return; }   writeToDatapowerLog();

For more information, see the Implementing your policy and gatewayscript topics in the IBM Knowledge Center.

Conclusion

This tutorial explained a versatile solution to help you address the challenges of logging flexibility when using a DataPower runtime and the API Connect assembly. By using the user-defined policy as described, you can log a customized message at a specific priority level directly to the DataPower logs, with full support of the runtime context variables. This solution is powerful for creating informative and useful messages for error detection and diagnosis during development, and as a runtime monitoring device.

Downloadable resources

• PDF of this content
• writeToDatapowerLog policy (writeToDatapowerLog.zip | 682KB): This file contains the writeToDatapowerLog policy.

Related topics

• IBM API Connect developer center
• /api Explorer developer center
• IBM DataPower Gateways developer center
• The assemble view
• Including components in your assembly