Monitoring and troubleshooting

Validate your event-driven flows and API flows are ready to run

When you create, edit, or import event-driven or API flows, App Connect automatically validates each application or Toolbox node in the flow.

If validation errors are detected, a warning icon is displayed on any nodes that require your attention. (If you’re creating a flow, you might see the warning icon for a node only after you move to another node.) Validation errors are typically reported for unconnected or disconnected accounts, missing data mappings in required fields, and invalid syntax in JSONata expressions that you type into fields. For example:

To be able to start a flow, you must resolve all validation errors. For more information about validating flows, see Validating your flow is ready to run.

Use flow tiles on the dashboard to view status messages

To view the status and related messages for a running flow, look at the tile for the flow on the App Connect dashboard.

  • If there’s a green tick, the flow has run successfully; click the tick to see when the flow was last triggered.
  • If there’s a red exclamation point, there’s a problem; click the exclamation point to find out what’s gone wrong.
    Tip: You can also view errors by clicking View errors in the tile’s options menu [⋮]. Review the error messages shown in the "Error messages" panel. If you see an arrow to the left of an entry in this panel, you can expand that entry to view additional details. To see other related messages for this flow, click the Actions menu (…) for an entry and then click View logs to open the log viewer.
    Figure 1. The Error messages panel

    (Click image to view full size.)

View log messages in the log viewer (IBM Cloud instances only)

In App Connect on IBM Cloud, you can view log messages for your event-driven flows, API flows, and integration servers. Log messages are forwarded to a built-in log viewer and can also be sent to an IBM Log Analysis service instance that’s configured to receive logs from enabled services in IBM Cloud.

For example, to display the log viewer with messages for all your running flows and integration servers, on the dashboard click the Logs icon .

For more information about log messages and the log viewer, see Viewing App Connect logs in the log viewer.

By default, error and information messages are logged:

  • Error: An error message is emitted when an event, action, or some flow logic has failed.
  • Info: An information message is emitted at key points, such as when a flow is triggered, or when it completes successfully.

You can add Log nodes to your flows to issue custom log messages and custom fields for specific content that you want to log. You can also configure flows to issue extra debug messages:

  • For information about adding Log nodes to flows, see Enhancing logging with customized log messages.
  • To view debugging information for a flow, open the menu on a flow tile in the App Connect dashboard and then click Enable debug logging. Restart your flow to start debug logging for that flow, and then open the log viewer to view the log entries.

    When debug logging is enabled, you'll see a debug log entry for each node in the flow that completes successfully. The log entry includes the output data from that node (in JSON format). Each node in the flow has access to the output from all previous nodes. If the flow is configured with a Log node that is used to emit a custom message with a log level of 'debug', you’ll also see a log entry for that custom message.

View log messages in IBM Log Analysis

To view log messages for your flows and integration servers within an IBM Log Analysis instance, you’ll need to configure, and then access the instance in IBM Cloud.

IBM Log Analysis enables you to extend the logging capability of your App Connect instance. For more information, see Monitoring and managing App Connect logs in IBM Log Analysis.

Tracing integration servers

For an integration server, if you cannot get enough information about a particular problem from the entries that are available in the log, the next troubleshooting method to consider is using trace.

Trace provides more details about what is happening while code runs.

There are two main types of trace available in IBM App Connect Enterprise: user trace and service trace.

  • Typically, you run user trace for debugging your integration solutions; you can trace integration servers and their deployed message flows.
  • You should activate service trace only when you receive an error message that instructs you to, or when you are directed to do so by your IBM Support Center. When active, service trace performs more-comprehensive integration server tracing.

For more information about both types of trace, see Using trace in the App Connect Enterprise documentation.

Trace is inactive by default, and must be explicitly activated (and managed) on the integration server's tile on the App Connect dashboard:

(Click image to view full size.)

When you have recorded some trace information, you can download the trace to your computer. To download trace, first stop the trace and then select the relevant Download trace option; for example:

(Click image to view full size.)

The contents of a downloaded trace file are identical to an on-premises trace file; for example:

(Click image to view full size.)

To erase the trace data that’s collected for an integration server, select the relevant Reset trace option.

Remote debug hybrid integration solutions with the App Connect toolkit

If you have a hybrid integration solution that is running in IBM App Connect Enterprise on IBM Cloud (App Connect on IBM Cloud with a plan that provides enterprise capabilities) and IBM App Connect Enterprise on premises, you can use remote debugging to debug messages passing through the message flows in the integration solution, and perhaps change the data as messages are passing through those flows.

You need to configure the integration servers for remote debugging in both App Connect on IBM Cloud and App Connect Enterprise on premises, including to connect your integration servers on IBM Cloud to your IBM App Connect toolkit on premises by using an agent. You can then use the toolkt for debugging; for example: to connect the toolkit debugger to your integration servers, add breakpoints to message flows in the tookit, and step through a message flow just as you would as if all the flows were running within your local system.

For more information about remote debugging hybrid integration solutions, see Remote debugging hybrid integration solutions with the App Connect toolkit.

Viewing usage details for your App Connect instances

To help monitor the use flows and integration servers, you can view usage details for your instances of the App Connect service.

On the usage details pages you can see the following usage data, depending on your existing plan and use of App Connect:

  • ITEMS_PER_MONTH: The number of flow runs in the month
  • GIGABYTE_TRANSMITTED_OUTBOUND: The number of gigabytes (GB) of outbound data in the month
  • INSTANCE_HOURS_PER_MONTH: The number of Virtual Processor Core Hours for deployment of Integration Servers in the month
Figure 2. Usage details page showing data for two App Connect instances

(Click image to view full size.)

To view usage details for your App Connect instances, complete the following steps:

  1. Display the Usage page for your IBM Cloud services: https://cloud.ibm.com/billing/usage (Alternatively, on your IBM Cloud menu bar, click Manage > Billing and usage, then select Usage)
  2. Select the time frame (month) that you want to view usage data
  3. (Optional) Filter to one or more groups
  4. In the Services list, on the App Connect row click View plans
  5. To view details for all your App Connect instances, click View details on a plan row. The usage page for your plan is shown, like the example in the figure above.
  6. (Optional) To view details for one App Connect instance, click View instance details on the instance row

Use the following resources: the App Connect status page, forums, and documentation

  • Check the following page to see if there are any current known issues with App Connect, and if there are any planned maintenance windows during which App Connect will be unavailable: IBM App Connect status.
  • Check the App Connect discussion forum on IBM Community to see if an answer is already provided there.
  • Ask a question about your problem in the App Connect discussion forum on IBM Community, providing as much detail as possible to help answer your question. The discussion forum is monitored by the IBM App Connect team and by other App Connect users.
  • Follow step-by-step instructions about how to connect your applications, APIs, and web services in the How to guides and Tutorials for IBM App Connect.

Miscellaneous help

Check some miscellaneous troubleshooting help for issues that you might have encountered:

Help! The connection to an application is broken

  • When you configure App Connect to connect to an application like Gmail, a notification that you have authorized App Connect to use your account details is recorded in your account profile for that application. For example, if you provide App Connect with your Google credentials, so that App Connect can connect to your Gmail account, you can see this authorization specified in your Google account (under Sign in & security > Connected apps and sites). If you remove the authorization from your Google account, App Connect can no longer connect to your Gmail account and any flows that use Gmail as a target application will become inactive. To reconnect App Connect to an application where the authorization has been removed, go to the Applications tab on the Catalog page in App Connect. There, you can choose either to update the account, or to remove the account, and then add the account again (or add a new account).

Help! My flow has received a timeout error

If a flow takes too long to run, it will receive a timeout error:
  • For an event-driven flow, a maximum of 5 minutes is configured for a flow run to complete.
  • For an API flow, a maximum of 120 seconds is configured for a flow run to complete. Also, when you call an API operation to invoke an API flow, the request is passed to App Connect through an API gateway that has a 70 second timeout period. In exceptional circumstances, it is possible for the API flow to continue running but the API gateway to timeout and return a 504 gateway timeout response.
If you encounter a timout error, there are several things you can do to recover; for example:
  • Wait a few minutes, then try again to trigger the event-driven flow or to call the API operation.
  • If an API operation is called many times concurrently, each call starts a new instance of the API flow. You can use rate limiting (on the API's Manage tab) to reduce the chance that some running API flows are delaying others and causing gateway timeout errors. When rate limiting is enabled, API calls falling outside of the limit will be rejected and response code 429 will be returned.

Help! My flow has received a concurrent user limit error for Salesforce

If more than 15 flows try to run concurrently using the same Salesforce account, you'll see the error "You've exceeded your organization's concurrent user limit for your Salesforce account.".

If you encounter a concurrent user limit error for Salesforce, there are several things you can do to recover; for example:
  • Wait a few minutes, then try again to trigger the event-driven flow or to call the API operation.
  • If an API operation is called many times concurrently, each call starts a new instance of the API flow. You can use rate limiting (on the API's Manage tab) to reduce the chance that some running API flows are delaying others and causing concurrent user limit errors. When rate limiting is enabled, API calls falling outside of the limit will be rejected and response code 429 will be returned.