You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs). info

Sosreport is a system-level diagnostic and data collection tool, based on the open source
software [SoS](https://sos.readthedocs.io).
You can use the Sosreport tool to collect information to help you debug problems
in nodes where an Apigee
component is running. The tool collects and stores information locally on the node's file system.

The Sosreport tool collects configuration details, system information, and
diagnostic information
from your system, and stores the data in an archive.
For Apigee components, Sosreport collects the following:

- The running kernel version
- Loaded modules
- System and service configuration files

Sosreport also runs external programs to collect further
information, including:

- Apigee logs from all components.
- Runtime diagnostics
- Cassandra diagnostics collected using nodetool commands.

The Sosreport tool contains two main commands:

- `sosreport`: The primary command for collecting data and creating reports.
- `apigee-sosreport`: An auxiliary tool used to install `sosreport` and manage `sosreport` plugins specific to Apigee components.

## Installation

The following table details the availability and installation method for Sosreport tool in Edge for Private Cloud supported versions.

| OPDK version | Fresh install | In-place upgrade |
|---|---|---|
| 4.50.00.11 - 4.52.01.00 | Manual install required | Manual install required |
| 4.52.01.01+ | Default installed | Manual upgrade required |
| Amazon Linux 2023+ | Not supported | Not supported |

The Sosreport tool comes installed by default on all nodes when performing a fresh installation of Edge for Private Cloud 4.52.01.01 and later.

If you perform an in-place upgrade to Edge for Private Cloud 4.52.01.01 or later, run the following command on each node to update the Sosreport tool:

```
/opt/apigee/apigee-service/bin/apigee-service apigee-sosreport update
```

You can run the following command to verify the installation and version of the Sosreport tool and its plugins:

```
apigee-service apigee-sosreport version
```

To list all the plugins supporting the Sosreport tool, use the following command:

```
sudo sosreport --list-plugins
```

To list only Apigee-specific plugins, run the following command:

```
sudo sosreport --list-plugins | grep apigee
```

For Edge for Private Cloud versions 4.50.00.11 through 4.52.01.00, the Sosreport tool is available but might require manual setup depending on your environment.

### If the SoS version of `sosreport` is already installed

If the original
[SoS](https://sos.readthedocs.io) version of `sosreport`
is already installed on your system,
do *not* set up Apigee's version, as the installation paths may conflict.
Instead, copy the Apigee-specific plugins from the directory
`/opt/apigee/apigee-sosreport/source/plugin` to the appropriate Python
`site-packages` directory using a command like the ones shown below.
For example, to copy `apigee-mgmt.py`:

- If you're using Python 2, enter:

  ```
  sudo cp apigee-mgmt.py /usr/lib/python2.7/site-packages/sos/plugins/
  ```
- If you're using Python 3, enter:

  ```
  sudo cp apigee-mgmt.py /usr/local/lib/python3.6/site-packages/sos/plugins/
  ```

To verify that the plugins have been installed, enter

```
sudo sosreport --list-plugins
```

If you have questions, contact Apigee support.

The following section explains how to install \`sosreport\` for versions 4.50.00.11 through 4.52.01.00.

### Installing Apigee's version of `sosreport`

If the [SoS version of `sosreport`](https://docs.apigee.com/api-platform/troubleshoot/sosreport#sosreport-already-installed) is not
already installed on your system, you can install Apigee's version by entering
the following commands on all nodes where Edge for Private Cloud is installed:

    /opt/apigee/apigee-service/bin/apigee-service apigee-sosreport install
    /opt/apigee/apigee-service/bin/apigee-service apigee-sosreport setup

To test that `sosreport` is installed, confirm that the plugins related to
Apigee are located in the following directory:

```
/usr/lib/pythonx.x/site-packages/sos/plugins
```

where `pythonx.x` is your installed version of Python.

Alternatively, you can run one of the following commands:

- To verify Apigee-specific plugins only:

  ```
  apigee-service apigee-sosreport diagnose -l
  ```

  This returns the following list of Apigee-specific plugins.

  ```
  sosreport (version 3.9)

  The following plugins are currently enabled:

  apigee-mgmt          This is the apigee plugin for edge-management-server
  apigee-mp            This is the apigee plugin for edge-message-processor
  apigee-rrt           This is the apigee plugin for edge-router
  apigee-sample        Main diagnostics gathering class
  ```
- To verify all plugins:

  ```
  apigee-service apigee-sosreport diagnose -s -l
  ```

  This returns the following list of plugins available with sosreport:

  ```
  sosreport (version 3.9)

  The following plugins are currently enabled:

   acpid                ACPI daemon information
   alternatives         System alternatives
   anacron              Anacron job scheduling service
   apigee-cassandra     This is the base class for sosreport plugins. Plugins should subclass
      this and set the class variables where applicable. ←truncated→
   apigee-mgmt          This is the base class for sosreport plugins. Plugins should subclass
      this and set the class variables where applicable. ←truncated→
   apigee-mp            Main diagnostics gathering class
   apigee-rrt           This is the base class for sosreport plugins. Plugins should subclass
      this and set the class variables where applicable. ←truncated→

  ………………………………………………….
  ………………………………………………….
  ………………………………………………….
  ←truncated→
  ```

## Creating a report

**Edge for Private Cloud versions 4.52.01.01 and later**

The Sosreport tool can detect existing components on your node and generate a report of all the logs required by support teams for analysis.

To generate a report, use the following command:

```
apigee-service apigee-sosreport diagnose
```

You can add the following flags if required:

- -f \| --file \| --config : Path to the configuration file used while performing the setup.

  ```
  Example: apigee-service apigee-sosreport diagnose -f /path/to/configuration.file
  ```
- -o \| --output : To redirect the generated sosreport to a specific directory or path

  ```
  Example: apigee-service apigee-sosreport diagnose -o /path/to/output_directory/
  ```

**Edge for Private Cloud versions 4.50.00.11 through 4.52.01.00**

To create a report using the Sosreport tool, run the `sosreport` command
with the required plugin option (see [Apigee plugins](https://docs.apigee.com/api-platform/troubleshoot/sosreport#apigee-plugins)). The
default directory where the report is stored is either `tmp` or `/var/tmp`.
You can change the directory where the report is stored by passing a different directory
to the `tmp-dir` option. For example, to create a report on
the Management Server and save it a directory named `my_report-dir`,
enter one of the following:

- Using Apigee's version of `sosreport`:

  ```
  sudo sosreport --config-file /opt/apigee/apigee-sosreport/conf/sos.conf -o apigee-mgmt  --batch --tmp-dir=my_report-dir
  ```
- Using the SoS version of sosreport:

  ```
  sudo sosreport -o apigee-mgmt  --batch --tmp-dir=my_report-dir
  ```

The report is stored in a `.tar.xz` file in the directory you specify using the
`tmp-dir` option.
The location of the `.tar.xz` file is shown on STDOUT, as well as the checksum. For example:

```
Your sosreport has been generated and saved in:
 /var/sosreport-prc-test-0-9613-2021-07-12-orwxufx.tar.xz
The checksum is: 5a8b97c6020346a688254c8b04ef86ec
For more available options for sosreport, read the man file:
sudo man sosreport
```

The report is stored in a `.tar.xz` file in the directory you specify using the
`tmp-dir` option.
The location of the `.tar.xz file` is shown on `STDOUT`, as well as the
checksum. For example:

For more available options for `sosreport`, read the `man` file:

```
sudo man sosreport
```

## Apigee plugins

The following sections describe Apigee plugins to the Sosreport tool for
the following components:

- [Management Server](https://docs.apigee.com/api-platform/troubleshoot/sosreport#management-server)
- [Message Processor](https://docs.apigee.com/api-platform/troubleshoot/sosreport#message-processor)
- [Router](https://docs.apigee.com/api-platform/troubleshoot/sosreport#router)
- [Cassandra](https://docs.apigee.com/api-platform/troubleshoot/sosreport#cassandra)

### Management Server

The `apigee-mgmt` plugin collects the following information from the
Management Server:

- server hostname (default)
- cpuinfo (default)
- meminfo (default)
- Java virtual machine (JVM) settings, such as memory, `Djdk.tls.allowUnsafeServerCertChange`, and so on (default)
- Current Management logs (default)
- Ten sequential top and jstacks output (default)
- Entire Management log folder (optional)
- config-files (optional)

#### Examples:

To collect all default items, enter one of the following:

- Using Apigee's version of `sosreport`:

  ```
  sudo sosreport --config-file /opt/apigee/apigee-sosreport/conf/sos.conf  -o apigee-mgmt --batch my_report-dir
  ```
- Using the SoS version of `sosreport`:

  ```
  sudo sosreport -o apigee-mgmt --batch my_report-dir
  ```

To collect all default items and also the optional item(s) specified in the command, for
example, configuration files and all logs, enter one of the following:

- Using Apigee's version of `sosreport`:

  ```
  sudo sosreport --config-file /opt/apigee/apigee-sosreport/conf/sos.conf  -o apigee-mgmt --batch -k apigee-mgmt.config-files -k apigee-mgmt.all-logs
  ```
- Using the SoS version of `sosreport`:

  ```
  sudo sosreport -o apigee-mgmt --batch -k apigee-mgmt.config-files -k apigee-mgmt.all-logs
  ```

To collect everything, enter one of the following:

- Using Apigee's version of `sosreport`:

  ```
  sudo sosreport --config-file /opt/apigee/apigee-sosreport/conf/sos.conf  -o apigee-mgmt --batch -k apigee-mgmt.config-files -k apigee-mgmt.all-logs
  ```

  Alternatively, you can enter:

  ```
  sudo sosreport --config-file /opt/apigee/apigee-sosreport/conf/sos.conf  -o apigee-mgmt --batch -a
  ```
- Using the SoS version of `sosreport`:

  ```
  sudo sosreport -o apigee-mgmt --batch -k apigee-mgmt.config-files -k apigee-mgmt.all-logs
  ```

  Alternatively, can enter:

  ```
  sudo sosreport -o apigee-mgmt --batch -a
  ```

### Message Processor

The `apigee-mp` plugin collects the following information from the
Management Processor (MP):

- Server hostname (default)
- cpuinfo (default)
- meminfo (default)
- buildinfo/release info (default)
- apigee-all status (default)
- server details (default)
- JVM level settings, for example, memory, `Djdk.tls.allowUnsafeServerCertChange`, etc. (default)
- Current MP logs (default)
- Ten sequential top, jstacks and NIO Metrics output (default)
- Entire MP log folder (optional)
- Classification tree (optional)
- Heap dump (optional)
- config-files (optional)
- Runtime trace (optional and only when `org:env:api:rev detail` is provided). Note: Plugin waits for 25 seconds to collect the runtime requests.

#### Examples:

To collect all default items, enter one of the following:

- Using Apigee's version of `sosreport`:

  ```
  sudo sosreport --config-file /opt/apigee/apigee-sosreport/conf/sos.conf  -o apigee-mp --batch
  ```
- Using the SoS version of `sosreport`:

  ```
  sudo sosreport -o apigee-mp --batch
  ```

You can also specify additional optional items to collect, in addition to all default items.
For example, to specify the heap dump, using the flag
`-k apigee-mp.heap`, enter one of the following:

- Using Apigee's version of `sosreport`:

  ```
  sudo sosreport --config-file /opt/apigee/apigee-sosreport/conf/sos.conf  -o apigee-mp --batch -k apigee-mp.heap
  ```
- Using the SoS version of `sosreport`:

  ```
  sudo sosreport -o apigee-mp --batch -k apigee-mp.heap
  ```

Similarly, you can specify the following optional items:

```
-k apigee-mp.deployments
-k apigee-mp.heap
-k apigee-mp.all-logs
-k apigee-mp.config-files
-k apigee-mp.trace=gsc-cps:test:httpbin:3
```

You can specify multiple options in a single command. For example:

- Using Apigee's version of `sosreport`:

  ```
  sudo sosreport --config-file /opt/apigee/apigee-sosreport/conf/sos.conf  -o apigee-mp --batch -k apigee-mp.deployments -k apigee-mp.all-logs
  ```
- Using the SoS version of `sosreport`:

  ```
  sudo sosreport -o apigee-mp --batch -k apigee-mp.deployments -k apigee-mp.all-logs
  ```

To collect everything except trace, enter one of the following:

- Using Apigee's version of `sosreport`:

  ```
  sudo sosreport --config-file /opt/apigee/apigee-sosreport/conf/sos.conf  -o apigee-mp --batch -a
  ```
- Using the SoS version of `sosreport`:

  ```
  sudo sosreport -o apigee-mp --batch -a
  ```

### Router

The `apigee-rrt` plugin collects the following information from the
Router:

- Server hostname (default)
- cpuinfo (default)
- meminfo (default)
- buildinfo/release info (default)
- apigee-all status (default)
- server details (default)
- ps output. This will give JVM level settings, for example, memory, Djdk.tls.allowUnsafeServerCertChange, and so on (default).
- Current Router logs (default)
- List of vhost file names including bad file names (default)
- Entire Router log folder (optional)
- config-files (optional)

#### Examples:

To collect all default items, enter one of the following:

- Using Apigee's version of `sosreport`:

  ```
  sudo sosreport --config-file /opt/apigee/apigee-sosreport/conf/sos.conf  -o apigee-rrt --batch
  ```
- Using the SoS version of `sosreport`:

  ```
  sudo sosreport -o apigee-rrt --batch
  ```

You can also specify additional optional items to collect, in addition to all default items.
For example, to specify the entire log folder, using the flag
`-k apigee-rrt.all-logs`, enter one of the following:

- Using Apigee's version of `sosreport`:

  ```
  sudo sosreport --config-file /opt/apigee/apigee-sosreport/conf/sos.conf  -o apigee-rrt --batch -k apigee-rrt.all-logs
  ```
- Using the SoS version of `sosreport`:

  ```
  sudo sosreport -o apigee-rrt --batch -k apigee-rrt.all-logs
  ```

Similarly, you can specify the following optional items:

```
-k apigee-rrt.all-logs
-k apigee-rrt.config-files
```

To collect everything:

- Using Apigee's version of `sosreport`:

  ```
  sudo sosreport --config-file /opt/apigee/apigee-sosreport/conf/sos.conf  -o apigee-rrt --batch -a
  ```
- Using the SoS version of `sosreport`:

  ```
  sudo sosreport -o apigee-rrt --batch -a
  ```

### Cassandra

The `apigee-cassandra` plugin collects the following information from
Cassandra nodes:

- Machine statistics:

  ```
  "hostname -i"
  "cat /proc/cpuinfo"
  "cat /proc/meminfo"
  "ulimit -a"
  "ps auxw"
  "df -kh"
  "du -sh"
  "netstat -ntlpu"
  "free -h"
  "ifconfig -h"
  "ps -ef"
  ```
- Apigee component's status and version apigee-all version \&\& apigee-all status
- apigee-cassandra logs: All files under `/opt/apigee/var/log/apigee-cassandra/`
- Commit log count
- Output of command Top
- Thread dump
- Configuration files: `cassandra-topology.properties`, `cassandra.yaml`, `cassandra-env.sh`
- Nodetool Output for the following parameters: version, status, ring, info, gossipinfo, compactionstats -H, tpstats, netstats, cfstats, proxyhistograms

#### Example:

To collect all default items, enter one of the following:

- Using Apigee's version of `sosreport`:

  ```
  sudo sosreport --config-file /opt/apigee/apigee-sosreport/conf/sos.conf  -o apigee-cassandra
  ```
- Using the SoS version of `sosreport`:

  ```
  sudo sosreport -o apigee-cassandra
  ```