Enhancing logging with customized log messages
In IBM® App Connect on IBM Cloud®, logs are provided in a built-in log viewer to help you monitor the behavior of your flows and diagnose errors. Your App Connect logs can also be forwarded to an IBM Log Analysis with LogDNA service instance that provides the capability to aggregate, monitor, and manage event logs from multiple IBM Cloud sources in a centralized location.
You can enhance logging by defining your own custom messages that you want App Connect to send to the logging service. You can also define custom fields for specific content that you want to log. This capability offers some control over what is written to the logs, so you can display information that's important to you and locate your log entries more easily.
You can configure logging while creating or editing a flow by adding one or more Log nodes with a variety of log levels, custom messages, and custom fields.
You can 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.
To add and configure a Log node within 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 that should be written to the logs, click (+) and then from the
Toolbox tab, click Log.
In the preceding example image, a ServiceNow "New incident" event is defined as the trigger for the flow, followed by a Set variable node with user-defined
prioritydata properties and mapped values. (The
transactionIdproperty is configured to resolve to a unique auto-generated value, and the
priorityvalue is calculated from the Impact and Urgency values recorded for the incident.)
In our example, we want to configure the Log node so that whenever a new incident is created, a message is written to the logs to indicate that a new incident is being processed. We'd also like to capture the transaction ID and priority for the incident.
- In the Log fields, configure the message that you want to pass to your App Connect logs:
Log level: Specify one of the following values:
- Log an informational message at that step in the flow.
- Log information about an unexpected situation or error in the flow. Errors are generally emitted when an operation fails, and 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 being returned.
- Log detailed information for debugging purposes. Note: Debug messages are written to the logs only if debug logging is enabled on the flow. For information about how to enable debug logging, see Viewing App Connect logs in the log viewer.
- Specify a custom value (such as a JSONata mapping) that should resolve to Info, Error, or Debug. If left as Custom, the log level defaults to Info.
Message detail: Specify the message text that should be displayed in the
Message column for that log entry.
In our example, we've defined a log level of Info, together with a custom message to indicate the new incident is being processed.
- Log level: Specify one of the following values:
- If you want to define your own fields to include in the log entry, add these custom fields as
data properties with defined values:
- 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.
- Use Add property to define additional data properties.
In the following example, we've defined two data properties that will contain a priority and a transaction ID for the incident.Note: If you define a data property as an object or array of objects with nested properties, the parent property will be displayed as a field in the log viewer, and the name/value pairs for the nested properties will be shown as the field value, in JSON format.
- To expose the properties as fields, click Edit mappings. You can now define values for these fields.
- For each field, specify a value by mapping to fields from previous nodes in the flow or by
entering text. In our example, we've mapped to the
transactionIddata properties that we set up in the Set variable node because we want their values to be written to the logs.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 grayed out and cannot be changed.)
You can complete your flow in the usual way by adding actions, additional Log nodes, or other toolbox utilities that you need. When the flow is triggered, you can view the logs to check the information that's recorded.
Viewing your custom messages and fields in the logs
Open the Logs view to see the messages that are logged for your flow (click the Logs icon ). 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.
The following example shows the log viewer with a filter that shows log entries for our specific
flow. The custom text (
Processing new ServiceNow incident), which we defined
earlier, is displayed in the Message column of the highlighted row.
If you expand the log entry for the custom message by clicking the arrow to the left of the event
time, you'll see additional 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,
For more information about monitoring and managing messages in the log viewer, see Viewing App Connect logs in the log viewer.
If you've configured an IBM Log Analysis with LogDNA instance to receive service logs from App Connect, custom messages from your Log nodes will also be forwarded to this instance. You'll need to directly access your IBM Log Analysis with LogDNA instance in IBM Cloud to see the log entries in the web UI. Here's an example of what the custom message from the preceding image looks like in the IBM Log Analysis with LogDNA web UI. The view is filtered to show only the log entries for our specific flow.
For more information about how to configure an IBM Log Analysis with LogDNA instance to receive logs, launch the instance, and monitor and manage log messages in its web UI, see Monitoring and managing App Connect logs in IBM Log Analysis with LogDNA