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:

The Kubernetes command-line tool (kubectl) version 1.24 or later.
Version 1.1.1 or later of the openssl command-line tool.
The sed (or gsed for macOS users) 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:

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

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

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.
Change directory to the /support folder of the cloned repository.
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:

Pull the Event Streams must-gather image as follows:

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

Tag the image:

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

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.

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

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

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.
Change directory to the /support folder of the cloned repository.
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:

Module	Description	For use with components
`eventstreams`	Gathers logs relating to instances of Event Streams and the Event Streams operator.	Event Streams
`kafka`	Gathers internal information about the Kafka environment.	Event Streams
`schema`	Gathers internal information about the Schema Registry.	Event Streams
`eem`	Gathers logs relating to instances of Event Endpoint Management and the Event Endpoint Management operator.	Event Endpoint Management
`eventprocessing`	Gathers logs relating to instances of Event Processing and the Event Processing operator.	Event Processing
`flink`	Gathers logs relating to your IBM Operator for Apache Flink and the Flink instances it manages.	IBM Operator for Apache Flink
`failure`	Gathers logs relating to unhealthy Kubernetes objects on the cluster.	All
`overview`	Gathers general information about the cluster environment.	All
`system`	Gathers information about the system, resource usage, and the network.	All

Additional information

If you are experiencing issues with running flows when using the Event Processing UI, ensure that you clicked Run Flow before gathering the relevant logs. If the flow is not running in the Event Processing UI, then the relevant container logs might not be available as Flink dynamically scales to zero. It is also helpful to provide IBM Support with a copy of the relevant flow as SQL. You can do this by exporting the flows to SQL and including the SQL files with the logs that you return.