Enabling and managing trace for a deployed integration server
To aid with problem determination and troubleshooting, you can enable and manage trace on an integration server that is deployed in the App Connect Dashboard. Enabling trace is useful if you cannot get enough information about a particular problem from the entries that are available in the log. Trace provides more details about what is happening while code runs, and can be analyzed to discover the cause of your problem.
About this task
Two types of trace are available for an integration server or integration runtime:
- User trace: Enable user trace to help you debug your integration solutions; you can trace integration servers or integration runtimes and their deployed message flows.
- Service trace: Enable service trace only when you receive an error message that instructs you to do so, or when you are directed to do so by IBM® support. When active, service trace performs more comprehensive integration server or integration runtime tracing and tracks the execution of commands.
When you start user or service trace, additional processing occurs for activities in the integration server or integration runtime that you are tracing, so there might be some effect on performance while the trace is active. You can limit this additional processing by restricting how long the trace is active for.
After you deploy an integration, you can start, stop, download, and clear (reset) user or service trace by using a set of menu options. If you want to capture trace on or before startup of an integration, you can use the server.conf.yaml file or an environment variable to start (and subsequently stop) trace. Only one trace can be enabled at a time on an integration server.
dashboard-admin
role is required to start and read trace. In a 12.0.10.0-r1 or
earlier Dashboard, the trace menu options are displayed only if you are assigned the
operator
or admin
role for accessing the Dashboard. For more
information, see Roles and permissions for the App Connect Dashboard on Red Hat OpenShift.Enabling user or service trace before deploying an integration
You can enable user or service trace on startup of an integration server by using the server.conf.yaml file. If you want to capture trace from the earliest possible time, including the period during which the server.conf.yaml file is read, you can instead set an environment variable within the integration server custom resource (CR) before you deploy the integration.
Procedure
To enable trace before you deploy an integration, complete one of the following steps:
Enabling user or service trace after deploying an integration
You enable user or service trace on a running integration server by starting the trace. You can start a trace only if no other trace is currently enabled.
Procedure
To start user or service trace, complete the following steps:
Stopping an active user or service trace
After collecting trace information for analysis, you can stop the trace.
Procedure
To stop an active user or service trace, complete the following steps:
Downloading the user or service trace log files
When you have collected some trace information, you can download the trace to your computer for analysis. You can download trace while it is running or after it is disabled. The download speed will depend on the volume of trace data and the amount of CPU that is allocated to the integration server.
Trace information is written to the trace log files in plain text format within the workdir/config/common/log directory, where workdir is the work directory (/home/aceuser/ace-server) of the integration server.
Procedure
To download the user or service trace log files, complete the following steps:
Clearing user or service trace information
You can use the reset option to erase the trace information that has been written to an integration server's trace log files. You might choose to clear the log before you start a new trace, to ensure that all the logged information is unique to the new trace.
Procedure
To clear user or service trace information, complete the following steps:
- From the Servers page of the App Connect Dashboard, locate the tile for the relevant integration server.
- Open the options menu on the tile and click the relevant Reset
trace option. You should see a notification confirming that the trace has been reset (for example,
Success: Reset user trace
).