Gather logs for your capability

To help IBM Support troubleshoot any issues with your IBM Event Automation installation, run the log gathering script as follows to capture the logs. The logs are stored in a folder in the current working directory.

Prerequisites

To run the log gathering script, ensure you have the following installed on your system:

• If using OpenShift, the OpenShift Container Platform CLI (oc) version 4.10 or later.
• If using other Kubernetes platforms, the Kubernetes command-line tool (kubectl) version 1.24 or later.
• The latest 1.1.1 version of openssl command-line tool.

Important: The gather scripts are written in bash. To run the scripts on Windows, ensure that you are running the scripts from a bash prompt. For example, git bash is a suitable shell environment and is available as part of the Git for Windows distribution.

Online environments

To gather logs from an online environment:

1. Clone the Git repository ibm-event-automation as follows:

   git clone https://github.com/IBM/ibm-event-automation
   

2. Log in to your cluster as a cluster administrator by setting your kubectl context or by using the oc CLI (oc login) on OpenShift Container Platform.
3. Change directory to the /support folder of the cloned repository.

4. Run the ./ibm-events-must-gather script to capture the relevant logs:

   ./ibm-events-must-gather -n <instance-namespace> [--es-namespace <eventstreams-instance-namespace>  --eem-namespace <event-endpoint-management-instance-namespace> --ep-namespace <event-processing-instance-namespace> --flink-namespace <flink-instance-namespace>] -m <gather-modules> -i <image-address>
   

   • For example, to gather logs for Event Streams, run the following command:

      ./ibm-events-must-gather -n samplenamespace -m eventstreams 
     

   • For example, to gather logs for Event Endpoint Management, run the following command:

      ./ibm-events-must-gather -n samplenamespace -m eem
     

   • For example, to gather logs for Event Processing, run the following command:

      ./ibm-events-must-gather -n samplenamespace -m eventprocessing
     

   • For example, to gather logs for IBM Operator for Apache Flink, run the following command:

     ./ibm-events-must-gather -n samplenamespace -m flink
     

   Where:

   • <gather-modules> is a comma separated list of modules, where valid values are eventstreams, kafka, eem, eventprocessing, flink, schema, failure, overview and system.
   • <image-address> is the address of the image to use for gathering logs. If <image-address> is not specified, then the default image (icr.io/cpopen/ibm-events-must-gather) is set. You can set a different image if instructed by IBM Support.

   • <instance-namespace> is the namespace where your capability instance is installed, and where the script gathers log data from.

     If specifying more than one of eventstreams, eem, eventprocessing, and flink modules, individual namespace flags must be used:

     • --es-namespace specifies the namespace containing the Event Streams instance to gather data from.
     • --eem-namespace specifies the namespace containing the Event Endpoint Management instance to gather data from.
     • --ep-namespace specifies the namespace containing the Event Processing instance to gather data from.
     • --flink-namespace specifies the namespace containing the IBM Operator for Apache Flink instance to gather data from.

The logs gathered are stored in an archive file called ibm-events-must-gather-<timestamp>.tar.gz, which is added to the current working directory.

Offline (air-gapped) environments

To gather diagnostic logs in an offline (also referred to as air-gapped or disconnected) environment:

1. Pull the Event Streams must-gather image as follows:

   docker pull icr.io/cpopen/ibm-events-must-gather
   

2. Tag the image:

   docker image -t icr.io/cpopen/ibm-events-must-gather <private-registry-image-address>:<tag>
   

3. Push the tagged image to the internal registry of your offline environments:

   docker push <private-registry-image-address:tag>
   

   Note: Automatic updates to the must-gather image are not supported in an offline environment. Repeat the previous steps frequently to ensure you are gathering logs with the most recent image.

4. Clone the Git repository ibm-event-automation as follows:

   git clone https://github.com/IBM/ibm-event-automation
   

5. Log in to your cluster as a cluster administrator by setting your kubectl context or by using the oc CLI (oc login) on OpenShift Container Platform.

6. Change directory to the /support folder of the cloned repository.

7. Run the ./ibm-events-must-gather script to capture the relevant logs:

   ./ibm-events-must-gather -n <instance-namespace> [--es-namespace <eventstreams-instance-namespace>  --eem-namespace <event-endpoint-management-instance-namespace> --ep-namespace <event-processing-instance-namespace>] -m <gather-modules> -i <image-address>
   

   • For example, to gather logs for Event Streams, run the following command:

      ./ibm-events-must-gather -n samplenamespace -m eventstreams 
     

   • For example, to gather logs for Event Endpoint Management, run the following command:

      ./ibm-events-must-gather -n samplenamespace -m eem
     

   • For example, to gather logs for Event Processing, run the following command:

      ./ibm-events-must-gather -n samplenamespace -m eventprocessing
     

   • For example, to gather logs for IBM Operator for Apache Flink, run the following command:

     ./ibm-events-must-gather -n samplenamespace -m flink
     

   Where:

   • <gather-modules> is a comma separated list of modules, where valid values are eventstreams, kafka, eem, eventprocessing, schema, failure, overview and system.
   • <image-address> is the cluster accessible location where you have pushed the must-gather image (see step 3).
   • <instance-namespace> is the namespace where your capability instance is installed, and where the script gathers log data from.

   Note: If you are running in an offline environment and need to specify your internal registry as the image location, run the command as follows:

   ./ibm-events-must-gather -n samplenamespace -m eventstreams -i <image-address> --mustgather-namespace <mustgather-namespace> --image-pull-secret <image-pull-secret-name>
   

   Where:

   • <image-address> is the address of the image to use for gathering logs. If you are running on the OpenShift Container Platform and have defined a repository in ImageContentSourcePolicies, you do not need to provide <image-address>.
   • <mustgather-namespace> is the namespace where you want to run the script for gathering logs.

   • <image-pull-secret-name> is the name of the secret that enables the must-gather image to be pulled from your internal registry. If you are running on the OpenShift Container Platform and have specified credentials for pulling images in the global pull-secret in the openshift-config namespace, --image-pull-secret <image-pull-secret-name> is not required because the credentials for pulling the image are already available in the global pull-secret.

     If specifying more than one of eventstreams, eem, eventprocessing, and flink modules, individual namespace flags must be used:

     • --es-namespace specifies the namespace containing the Event Streams instance to gather data from.
     • --eem-namespace specifies the namespace containing the Event Endpoint Management instance to gather data from.
     • --ep-namespace specifies the namespace containing the Event Processing instance to gather data from.
     • --flink-namespace specifies the namespace containing the IBM Operator for Apache Flink instance to gather data from.

The logs gathered are stored in an archive file called ibm-events-must-gather-<timestamp>.tar.gz, which is added to the current working directory.

Gather modules

See the following table for information about the modules that are supported by the gather script and the components it can run on:

Additional information

If your issues relate to running flows in Event Processing, it is also helpful to provide IBM Support with a copy of the relevant flows. You can do this by exporting the flows to SQL and including the SQL files with the logs that you return.