Trace reference
Use this reference to enable and disable trace for integration servers by creating and deleting trace objects in the Red Hat® OpenShift® web console or CLI.
- Introduction
- Prerequisites
- Red Hat OpenShift SecurityContextConstraints requirements
- Enabling trace by creating a trace object after deploying an integration
- Collecting trace from an integration server container that is crashing
- Disabling trace by deleting a trace object
- Custom resource values
- Supported platforms
Introduction
The Trace API enables you to enable and manage trace for a deployed integration server 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.
Two types of trace are available for an integration server:
- User trace: Enable user trace to help you debug your integration solutions; you can trace integration servers and their deployed message flows.
- Service trace: Enable service trace only when you receive an error message that instructs you to, or when you are directed to do so by IBM® support. When active, service trace performs more comprehensive integration server tracing and tracks the execution of commands.
When you start user or service trace, additional processing occurs for activities in the integration server 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.
When you deploy a trace custom resource (CR) to create a trace object, you must specify a running integration server on which you want to enable and run the trace. Only one trace can be enabled at a time on an integration server.
- If you want to capture trace on or before startup of an integration server, you cannot use a trace object, but must instead use the server.conf.yaml file or an environment variable to enable trace. For more information, see Enabling trace before deploying an integration from the Red Hat OpenShift web console or CLI.
- You can also enable and manage user and service trace from an App Connect Dashboard instance that hosts your deployed integration servers. For more information, see Enabling and managing trace for a deployed integration server. For information about deploying integration servers by using the App Connect Dashboard, see Deploying Designer and Toolkit integrations to integration servers.
Prerequisites
- Red Hat
OpenShift Container Platform
4.12 or 4.14 is required.
Note: For information about the custom resource (or operand) versions that are supported for each Red Hat OpenShift version, see spec.version values.
- The IBM App Connect Operator must be installed in your cluster either through an independent deployment or an installation of IBM Cloud Pak for Integration. For further details, see the following information:
- Ensure that you have cluster administrator authority or have been granted the appropriate role-based access control (RBAC).
- If you want to use the command-line interface (CLI) to log in to your cluster and run commands to create and manage your IBM App Connect instances and other resources, ensure that the required CLI tools are installed on your computer. For more information, see Installing tools for managing the cluster, containers, and other resources (on Red Hat OpenShift).
- You must have a Kubernetes pull secret
called
ibm-entitlement-key
in the namespace before creating the instance. For more information, see Obtaining and applying your IBM Entitled Registry entitlement key.
Red Hat OpenShift SecurityContextConstraints requirements
IBM App Connect runs under the default restricted
SecurityContextConstraints.
Enabling trace by creating a trace object after deploying an integration
To enable (or start) user or service trace on a deployed integration server, you can create a trace object by using the Red Hat OpenShift web console or CLI.
- After you create a trace object, you cannot update its custom resource settings. If you want to change the type of trace that is currently active for an integration server, you must delete the existing trace object and then create a new trace object of the required type.
- If a pod is restarted or a new replica is added while trace is active, trace will be started on that pod within 60 seconds because the trace reconcile loop is scheduled to run every minute. However, there is a possibility that some trace data might be lost during this interval.
Before you begin
Ensure that the Prerequisites are met.
The namespace in which you create an instance or object must be no more than 40 characters in length.
Creating a trace object from the Red Hat OpenShift web console
To create a trace object by using the Red Hat OpenShift web console, complete the following steps:
- Applicable to IBM Cloud Pak for Integration only:
- If not already logged in, log in to the IBM Cloud Pak Platform UI for your cluster.
- From the Platform UI home page, click Install operators or OpenShift Container Platform, and log in if prompted.
- Applicable to an independent deployment of IBM App Connect Operator only: From a browser window, log in to the Red Hat OpenShift Container Platform web console. Ensure that you are in the Administrator perspective .
- From the navigation, click .
- If required, select the namespace (project) in which you installed the IBM App Connect Operator.
- From the Installed Operators page, click IBM App Connect.
- From the
Operator details
page for the App Connect Operator, click the Trace tab. Any previously created trace objects are displayed in a table. - Click Create Trace.
From the Details tab on the
Operator details
page, you can also locate the Trace tile and click Create instance to specify installation settings for the trace object. - Specify the settings for a user or service trace by using either of the following methods:
- From the Form view, complete the fields to specify a preferred name for the trace object, the integration server that you want to collect trace for, and the type of trace to be collected.
- If you prefer to use the YAML view, click YAML View and then update the
contents of the YAML editor with the parameters and values that you require for this trace object.
To view the full set of parameters and values available, see Custom resource values.
The following YAML code shows an example of what the custom field definitions of your trace object should look like for a user trace.
apiVersion: appconnect.ibm.com/v1beta1 kind: Trace metadata: name: trace-user-is-fd-toolkit namespace: mynamespace spec: integrationServerName: is-fd-toolkit type: user
The following YAML code shows an example of what the custom field definitions of your trace object should look like for a service trace.
apiVersion: appconnect.ibm.com/v1beta1 kind: Trace metadata: name: trace-service-is-fd-toolkit namespace: mynamespace spec: integrationServerName: is-fd-toolkit type: service
- Click Create. An entry for the trace object is shown in the Traces table
with a
Ready
status. - Click the trace object name to view information about its definition. On the
Events tab, you should see a notification that the trace has started for the
integration server pod as shown in the following example.
You can use the breadcrumb trail to return to the (previous)
Operator details
page for Traces. The status for the trace object is shown asReady
in the Traces table.
Ready (trace
enabled)
.
What to do next
- When you have collected some trace information, you can download the trace to your computer for analysis. You can do so from your App Connect Dashboard instance as described in Downloading the user or service trace log files.
- If you want to erase the trace information that has been written to an integration server's trace log files, you can use a reset option. You can do so from your App Connect Dashboard instance as described in Clearing user or service trace information.
Creating a trace object from the Red Hat OpenShift CLI
To create a trace object from the Red Hat OpenShift CLI, complete the following steps.
- From your local computer, create a YAML file that contains the configuration for the trace
object that you want to create. Include the metadata.namespace parameter to
identify the namespace in which you want to create the trace; this should be the same namespace
where the integration server is created.
To view the full set of parameters and values available, see Custom resource values.
The following YAML code shows an example of what the custom field definitions of your trace object should look like for a user trace.
apiVersion: appconnect.ibm.com/v1beta1 kind: Trace metadata: name: trace-user-is-fd-toolkit namespace: mynamespace spec: integrationServerName: is-fd-toolkit type: user
The following YAML code shows an example of what the custom field definitions of your trace object should look like for a service trace.
apiVersion: appconnect.ibm.com/v1beta1 kind: Trace metadata: name: trace-service-is-fd-toolkit namespace: mynamespace spec: integrationServerName: is-fd-toolkit type: service
- Save this file with a .yaml extension; for example, myintserver_usertrc_cr.yaml.
- From the command line, run the following command to create the trace object in your Red Hat
OpenShift cluster. (Use the name of the .yaml file
that you created.)
oc apply -f myintserver_usertrc_cr.yaml
- Run the following command to check the status of the trace object and verify that it is ready:
oc get traces -n namespace
You should see output similar to this.
NAME AGE TRACETYPE INTEGRATIONSERVER STATUS trace-user-is-fd-toolkit 139m user is-fd-toolkit Ready
What to do next
- When you have collected some trace information, you can download the trace to your computer for analysis. You can do so from your App Connect Dashboard instance as described in Downloading the user or service trace log files.
- If you want to erase the trace information that has been written to an integration server's trace log files, you can use a reset option. You can do so from your App Connect Dashboard instance as described in Clearing user or service trace information.
Collecting trace from an integration server container that is crashing
MQSI_PREVENT_CONTAINER_SHUTDOWN
to true
.
spec:
env:
- name: MQSI_PREVENT_CONTAINER_SHUTDOWN
value: 'true'
For information about editing an integration server's CR, see Integration Server reference: Updating the custom resource settings for an instance.
Disabling trace by deleting a trace object
To disable (or stop) an active user or service trace, you can delete the trace object by using the Red Hat OpenShift web console or CLI. When you delete a trace object, the trace log files are retained in the system. For information about the location of these files, see Downloading the user or service trace log files. Also note that if you delete an integration server, any trace object which references that integration server (in spec.integrationServerName) is also automatically deleted.
Before you begin
Ensure that you have cluster administrator authority or have been granted the appropriate role-based access control (RBAC).
Deleting a trace object from the Red Hat OpenShift web console
To delete a trace object by using the Red Hat OpenShift web console, complete the following steps:
- Applicable to IBM Cloud Pak for Integration only:
- If not already logged in, log in to the IBM Cloud Pak Platform UI for your cluster.
- From the Platform UI home page, click Install operators or OpenShift Container Platform, and log in if prompted.
- Applicable to an independent deployment of IBM App Connect Operator only: From a browser window, log in to the Red Hat OpenShift Container Platform web console. Ensure that you are in the Administrator perspective .
- From the navigation, click .
- If required, select the namespace (project) in which you installed the IBM App Connect Operator.
- From the Installed Operators page, click IBM App Connect.
- From the
Operator details
page for the App Connect Operator, click the Trace tab. - Locate the trace object that you want to delete.
- Click the options icon () to open the options menu, and then click the Delete option.
- Confirm the deletion.
Deleting a trace object from the Red Hat OpenShift CLI
To delete a trace object from the Red Hat OpenShift CLI, complete the following steps.
- From the command line, log in to your Red Hat OpenShift cluster by using the oc login command.
- From the namespace where the trace object is deployed, run the following command to delete this
object, where traceName is the value of the metadata.name parameter.
oc delete trace traceName
Custom resource values
The following table lists the configurable parameters and default values for trace objects.
Parameter | Description | Default |
---|---|---|
apiVersion |
The API version that identifies which schema is used for this object. |
appconnect.ibm.com/v1beta1 |
kind |
The resource type. |
Trace |
metadata.name |
A unique short name by which the trace object can be identified.
|
|
metadata.namespace |
The namespace (project) in which the trace object and the referenced integration server are created. The namespace in which you create an instance or object must be no more than 40 characters in length. |
|
spec.integrationServerName |
The name of a deployed integration server that you want to collect trace for. |
|
spec.type |
The type of trace. Valid values are user and service. For more information about each trace type, see Introduction. |
service |
Supported platforms
Red Hat
OpenShift: Supports the
amd64
, s390x
, and ppc64le
CPU architectures. For
more information, see Supported platforms.