Enhancing logging with customized log messages

In IBM® App Connect, logs are provided in a built-in log viewer to help you monitor the behavior of your flows and diagnose errors.

You can enhance logging by defining your own custom messages for App Connect to send to the logging service. You can also define custom fields for specific content that you want to log. These features help you to control what is written to the logs so that you can display information that's important to you.

You can configure logging when you create or edit a flow by adding one or more Log nodes with various log levels, custom messages, and custom fields. You can add a Log node at any stage of the flow after the event node that acts as a trigger. The Log node is available from the Toolbox tab in the flow editor.

Tip: You can also use a Log node to test your flow. For example, you can temporarily add a Log node to your flow to record some output from a previous node. You can then verify whether that node is correctly configured to provide the expected output.

Configuring logging

To add and configure a Log node in a flow, complete the following steps.

At the stage in the flow where you want to capture relevant data from previous nodes or provide contextual information to write to the logs, click Add node (+), then from the Toolbox tab, click Log.
Figure 1. Selecting the Log node from the Toolbox

In the preceding image, a ServiceNow New incident event is defined as the trigger for the flow, followed by a Set variable node with user-defined transactionId and priority data properties and mapped values. (The transactionId property is configured to resolve to a unique auto-generated value, and the priority value is calculated from the Impact and Urgency values that are recorded for the incident.)
- View the Set variable mappings for the example.
In this example, whenever a new incident is created, the Log node writes a message to the logs to indicate that a new incident is being processed. The transaction ID and priority for the incident also need to be captured.
In the Log fields, configure the message that you want to pass to your App Connect logs.
- For Log level, specify one of the following values.
  
  Info
  
  Write an informational message to the logs at that step in the flow.
  
  Error
  
  Write information to the logs about an unexpected situation or error in the flow. Errors are typically emitted when an operation fails. Errors are depicted with a warning icon on the flow's tile on the Dashboard. You can also choose to log a custom error about something significant that might not necessarily result in an HTTP error code.
  
  Custom
  
  Specify a custom value (such as a JSONata mapping) that resolves to Info or Error. If the value remains as Custom, the log level defaults to Info.
- In Message detail, specify the message text to write in the Message column for that log entry.
  In the example, the log level is Info and a custom message indicates that the new incident is being processed.
  
  Figure 2. Initial fields in the Log node
If you want to define your own fields to include in the log entry, add these custom fields as data properties with defined values.
1. To define a data property, click Add property under Custom message fields to display the property editor. Then enter a property name and select its data type.
2. Use Add property to define more data properties.
  In the following example, two data properties contain a priority and a transaction ID for the incident.
  
  Figure 3. Example of defined properties under 'Custom message fields'
  
  Note: If you define a data property as an object or array of objects with nested properties, the parent property is displayed as a field in the log viewer. The name and value pairs for the nested properties are shown as the field value in JSON format.
  - Example of nested custom fields in the Log node and log viewer.

To show the properties as fields, click Edit mappings. You can now define values for these fields.
Figure 4. Custom properties that are shown as fields
For each field, specify a value by mapping to fields from previous nodes in the flow or by entering text. The example maps the fields to the priority and transactionId data properties in the Set variable node so that their values are written to the logs.
Figure 5.
Note:
- You can add or remove properties by clicking Edit properties to switch back to the property editor.
- If you want to update the name or data type of a defined property, ensure that the associated field is blank before you click Edit properties. (In the property editor, properties with defined values are disabled and can't be changed.)

You can complete your flow in the usual way by adding actions, more Log nodes, or other toolbox utilities that you need. When the flow is triggered, you can view the logs to check the information that is recorded.

Viewing your custom messages and fields in the logs

Open the Logs view ( Logs icon ) to see the messages that are logged for your flow. The built-in log viewer opens to show the event messages that are logged for all your running flows, including any custom messages that you defined in the Log node.

Tip: If error messages were emitted for your flow, you can also access the log viewer to view those errors and any custom messages that are specific to your flow. While the flow is running, click the warning icon Flow error icon

on the flow's tile on the Dashboard to view the related errors. You can then use the View logs option to see flow-specific messages in the log viewer.

Example of an error icon on a flow tile and corresponding messages.

The following example shows the log viewer with a filter that shows log entries for the example flow. The custom text (Processing new ServiceNow incident) is displayed in the Message column of the highlighted row.

Figure 6. Log viewer with a custom message from the Log node

Expand the log entry for the custom message to see more metadata about the event, including the custom fields that you defined and their generated values. Notice that these fields are prefixed with the text user_ to differentiate them from the standard fields (for example, user_incident_priority and user_transaction_id).