{"id":23655222,"url":"https://github.com/caplin/caplin-platform-diagnostics","last_synced_at":"2025-08-07T05:10:01.061Z","repository":{"id":47836550,"uuid":"208778081","full_name":"caplin/caplin-platform-diagnostics","owner":"caplin","description":"Collect diagnostic information on a running or crashed Caplin Platform component.","archived":false,"fork":false,"pushed_at":"2021-08-12T14:55:47.000Z","size":144,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-05-20T07:07:05.559Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caplin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-09-16T11:00:01.000Z","updated_at":"2021-08-12T14:46:26.000Z","dependencies_parsed_at":"2022-09-02T16:24:34.809Z","dependency_job_id":null,"html_url":"https://github.com/caplin/caplin-platform-diagnostics","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/caplin/caplin-platform-diagnostics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caplin%2Fcaplin-platform-diagnostics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caplin%2Fcaplin-platform-diagnostics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caplin%2Fcaplin-platform-diagnostics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caplin%2Fcaplin-platform-diagnostics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caplin","download_url":"https://codeload.github.com/caplin/caplin-platform-diagnostics/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caplin%2Fcaplin-platform-diagnostics/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269201296,"owners_count":24377460,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-07T02:00:09.698Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-28T19:51:57.406Z","updated_at":"2025-08-07T05:10:01.016Z","avatar_url":"https://github.com/caplin.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Caplin Platform Diagnostics\n\nCaplin Platform Diagnostics is a collection of Bash scripts that collect diagnostics on a running or crashed Caplin Platform component.\n\nThe scripts automate a series of common Linux diagnostic commands that Caplin Support ask customers to run when raising a support request (see [Send diagnostic information to Caplin Support](https://www.caplin.com/developer/caplin-platform/platform-architecture/get-information-about-a-failed-platform-component) on the Caplin website).\n\nCaplin Platform Diagnostics is made available under an MIT licence.\n\n**Contents**:\n\n*   [Requirements](#requirements)\n*   [Quick start](#quick-start)\n*   [Running diagnostics on a core file](#running-diagnostics-on-a-core-file)\n*   [Running diagnostics on a process](#running-diagnostics-on-a-process)\n\n## Requirements\n\nThe Caplin Platform Diagnostics scripts have the following requirements:\n\n*   [CentOS](https://www.centos.org/)/[RHEL](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux) 6 or 7\n*   GNU Debugger: `$ sudo yum install gdb`\n*   Red Hat OpenJDK 8 (full JDK, not just JRE): `$ sudo yum install java-1.8.0-openjdk-devel`\n\n## Installation\n\nCopy (or symlink) the two diagnostic scripts to a directory on your executable path. For example, `~/bin/` or `/usr/local/bin/`\n\n## Quick start\n\nTo run diagnostics on a **process**, follow the steps below:\n\n1.  Install dependencies, if not already installed:\n\n    ```\n    $ sudo yum install gdb java-1.8.0-openjdk-devel\n    ```\n\n1.  Run the script below _under the same user as the target process_ (run time 20 seconds):\n\n    ```\n    $ caplin-process-diagnostics.sh \u003cpid\u003e\n    ```\n\n    For full details and options, see [Running diagnostics on a process](#running-diagnostics-on-a-process).\n\n1.  Upload the generated tar file and any log files requested by Caplin Support to Caplin's [File Upload Facility](https://www.caplin.com/account/uploads).\n\nTo run diagnostics on a **core-file**, follow the steps below:\n\n1.  Install dependencies, if not already installed:\n\n    ```\n    $ sudo yum install gdb\n    ```\n\n1.  Run the script below:\n\n    ```\n    $ caplin-corefile-diagnostics.sh \u003ccorefile\u003e\n    ```\n\n    For full details and options, see [Running diagnostics on a core file](#running-diagnostics-on-a-core-file).\n\n1.  Upload the generated tar file and any log files requested by Caplin Support to Caplin's [File Upload Facility](https://www.caplin.com/account/uploads).\n\n## Running diagnostics on a core file\n\nThe `caplin-corefile-diagnostics.sh` script collates diagnostics for a core file dumped by a crashed Caplin Platform component.\n\nThe diagnostics collated include all the files Caplin Support require to analyse the core file: the component binary, the core file, and all shared libraries referenced in the core file. For the full list of information collated, see [Information collated](#information-collated), below.\n\nRun this script on the crashed component's host, or, if this is not possible, on an identically configured host (same operating system and Java versions).\n\nAfter running the script, log in to Caplin's secure [File Upload Facility](https://www.caplin.com/account/uploads) and upload the following files:\n\n*   Tar archive generated by the `caplin-corefile-diagnostics.sh` script\n*   Java virtual machine log and error files (if available):\n    *   HotSpot JVM error file (`hs_err_pid\u003cprocess-id\u003e.log`)\n    *   Heap dump file (`var/java_pid\u003cprocess-id\u003e.hprof`)\n    *   Garbage collection log (`var/gc.log`)\n*   Caplin log files for the period of the incident\n*   Caplin configuration files\n\n### Requirements\n\nThis script has the following requirements:\n\n*   [CentOS](https://www.centos.org/)/[RHEL](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux) 6 or 7\n*   GNU Debugger (`gdb` RPM package).\n*   Write permission to the current directory\n*   Run on the crashed component's host or, if this is not possible, on an identically configured host (same operating system and Java versions)\n\n### Usage\n\n**Syntax**: `caplin-corefile-diagnostics.sh core [binary]`\n\n*   `core`: path to the core file dumped by the crashed process.\n*   `binary`: path to the crashed process's binary. Defaults to the path of the binary recorded in the core file.\n\n**Run as**: any user\n\n**Runtime**: \u003c 1 minute\n\n**Output**: `diagnostics-\u003chostname\u003e-\u003ccore-file\u003e-\u003ctimestamp\u003e.tar.gz`\n\n### Information collated\n\nThis script collates the following information:\n\n| Diagnostic                                   | Dependencies      | User |\n|----------------------------------------------|-------------------|------|\n| `/etc/os-release`                            | -                 | -    |\n| `/etc/redhat-release`                        | -                 | -    |\n| `/etc/security/limits.conf`                  | -                 | -    |\n| `/etc/security/limits.d/*`                   | -                 | -    |\n| `ulimit -aS` output                          | -                 | -    |\n| `ulimit -aH` output                          | -                 | -    |\n| `uname -a` output                            | -                 | -    |\n| `df` output for binary's 'var' directory     | -                 | -    |\n| Caplin `dfw versions` output                 | Binary is in a [DFW](https://www.caplin.com/developer/caplin-platform/deployment-framework/) | -    |\n| Core file                                    | -                 | -    |\n| Core file backtrace                          | `gdb` RPM package | -    |\n| Core file libraries                          | `gdb` RPM package | -    |\n| Component binary                             | -                 | -    |\n\n### Example\n\nThe example below collates diagnostics for a core file, `core.4972`, dumped by a Liberator binary, `rttpd`:\n\n```console\n$ ./caplin-corefile-diagnostics.sh ~/dfw1/servers/Liberator/core.4972\n\nCaplin Core-file Diagnostics\n============================\n\nHost:            server1\nCore:            /home/caplin/dfw1/servers/Liberator/core.4972\nBinary:          /home/caplin/dfw1/servers/Liberator/bin/rttpd\nGDB installed:   1\nScript temp dir: diagnostics-server1-rttpd-core.4972-20190916104354\n\nRecording /etc/os-release\nRecording /etc/redhat-release\nRecording 'uname -a' output\nRecording 'df' output for /home/caplin/dfw1/servers/Liberator/var\nRecording 'dfw versions' output\nGetting thread backtraces from core.4972\nGetting list of libraries referenced by core.4972\nCopying libraries referenced by core.4972\n\nDONE\n\nFiles collected:\n\n  core.4972\n  core.4972.backtrace.out\n  core.4972.libs.tar\n  dfw-versions.out\n  diagnostics.log\n  libs-list.out\n  libs-list.txt\n  os-release\n  redhat-release\n  rttpd\n  uname.out\n\nArchiving files to diagnostics-server1-rttpd-core.4972-20190916104354.tar.gz\n\nPlease login to https://www.caplin.com/account/uploads\nand upload the archive to Caplin Support.\n```\n\n\n## Running diagnostics on a process\n\nThe `caplin-process-diagnostics.sh` script collates diagnostics for a process without terminating the process.\n\nScript run-time is 20s for the default set of diagnostics. Optional diagnostics take longer, and their timing can be variable. For example, the run time for the optional GDB core dump (`--gcore`) depends on the size of the target process in memory, and the host's disk I/O and CPU performance.\n\nFor the full list of information collated, see [Information collated](#information-collated-1), below.\n\nAfter running the script, log in to Caplin's secure [File Upload Facility](https://www.caplin.com/account/uploads) and upload the following files:\n\n*   Tar archive generated by the `caplin-process-diagnostics.sh` script\n*   Java virtual machine log files (if available):\n    *   Garbage collection log (`var/gc.log`)\n*   Caplin log files for the period of the incident\n*   Caplin configuration files\n\n### Requirements\n\nThe main dependency is the GNU Debugger (`gdb` package). This is required for generating stack traces and a core dump.\n\nIf any requirements are missing when you run the script, the script lists the missing dependencies and asks if you wish to continue. If you choose to continue, the script skips any diagnostics with missing dependencies.\n\n**All diagnostics**:\n\n*   [CentOS](https://www.centos.org/)/[RHEL](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux) 6 or 7\n*   Write permission to the current directory\n\n**GDB core dump and backtrace diagnostics**:\n*   `gdb` RPM package\n*   Free disk space greater than the process's virtual memory\n*   **CentOS/RHEL 7**: [SELINUX](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/selinux_users_and_administrators_guide/index) boolean  `deny_ptrace` set to off (if SELINUX enabled and enforcing).\n*   **CentOS/RHEL 7**: [Yama kernel module](https://www.kernel.org/doc/Documentation/security/Yama.txt) sysctl setting `kernel.yama.ptrace_scope` set to 0, 1, or 2.\n\n**JVM diagnostics**:\n*   `java-1.8.0-openjdk-devel` RPM package. This package installs the full JDK, which includes the `jcmd` diagnostic tool.\n\n**Optional `strace` diagnostic**:\n*   `strace` RPM package. Only required if requested by Caplin Support.\n\n### Usage\n\n**Syntax**: `caplin-process-diagnostics.sh [options] pid`\n\n*   `pid`: process identifier of the running component\n*   Options:\n    *   `--gcore`: include the optional GDB core file dump diagnostic. Only include this diagnostic when requested by Caplin Support.\n    *   `--jvm-heap`: include the optional JVM heap dump diagnostic. Halts the JVM temporarily for the duration of the diagnostic. Only include this diagnostic when requested by Caplin Support.\n    *   `--jvm-class-histogram`: include the optional JVM class histogram diagnostic. Halts the JVM temporarily for the duration of the diagnostic. Only include this diagnostic when requested by Caplin Support.\n    *   `--strace`: include the optional `strace` diagnostic. Only include this diagnostic when requested by Caplin Support.\n    *   `--help`: display help and exit\n    *   `--version`: display version and exit\n\n**Run as**:\n\n*   CentOS 6: the process's user\n*   CentOS 7:\n    *    `kernel.yama.ptrace_scope=0`: the process's user\n    *    `kernel.yama.ptrace_scope=1`: root (required for core dump, thread backtraces, and `strace`)\n    *    `kernel.yama.ptrace_scope=2`: root (required for core dump, thread backtraces, and `strace`)\n    *    `kernel.yama.ptrace_scope=3`: the process's user (core dump, thread backtraces, and `strace` prohibited for all users)\n\n**Runtime**: 20s for the default set of diagnostics\n\n**Output**: `diagnostics-\u003chostname\u003e-\u003cbinary\u003e-\u003cpid\u003e-\u003ctimestamp\u003e.tar.gz`\n\n### Information collated\n\nDefault diagnostics:\n\n| Diagnostic                            | Dependencies         | User     |\n|---------------------------------------|----------------------|----------|\n| `/etc/os-release`                     | -                    | -        |\n| `/etc/redhat-release`                 | -                    | -        |\n| `uname -a` output                     | -                    | -        |\n| `/proc/sys/kernel/core_pattern`       | -                    | -        |\n| `/proc/sys/kernel/core_uses_pid`      | -                    | -        |\n| `/proc/\u003cpid\u003e/limits`                  | -                    | -        |\n| `/etc/security/limits.conf`           | -                    | -        |\n| `/etc/security/limits.d/*`            | -                    | -        |\n| `top` output for the system (5 seconds)| -                    | -        |\n| `top` output for the process (5 seconds)| -                    | -        |\n| `df` output for the process's `\u003cworking-dir\u003e/var` directory| - | -      |\n| `free` output                         | -                    | -        |\n| `vmstat` output (5 seconds)           | -                    | -        |\n| Caplin `dfw info` output              | Process binary is in a [DFW](https://www.caplin.com/developer/caplin-platform/deployment-framework/)| -        |\n| Caplin `dfw status` output            | Process binary is in a [DFW](https://www.caplin.com/developer/caplin-platform/deployment-framework/)| -        |\n| Caplin `dfw versions` output          | Process binary is in a [DFW](https://www.caplin.com/developer/caplin-platform/deployment-framework/)| -        |\n| JVM `jcmd \u003cpid\u003e Thread.print` output  | `jcmd` JDK command       | _Note 1_ |\n| JVM `jcmd \u003cpid\u003e GC.heap_info` output  | `jcmd` JDK command       | _Note 1_ |\n| JVM `jcmd \u003cpid\u003e VM.system_properties` output | `jcmd` JDK command| _Note 1_ |\n| JVM `jcmd \u003cpid\u003e VM.flags` output      | `jcmd` JDK command       | _Note 1_ |\n| JVM `jcmd \u003cpid\u003e PerfCounter.print` output | `jcmd` JDK command   | _Note 1_ |\n| JVM `jstat -gc \u003cpid\u003e` output          | `jcmd` JDK command       | _Note 1_ |\n| JVM `jstat -gcutil \u003cpid\u003e` output      | `jcmd` JDK command       | _Note 1_ |\n| GDB thread backtrace                  | `gdb` RPM package    | _Note 2_ |\n| Process binary                        | -                    | -        |\n\nOptional diagnostics (only enable if requested by Caplin Support):\n\n| Diagnostic                            | Dependencies         | User     |\n|---------------------------------------|----------------------|----------|\n| GDB core-file dump, backtrace, and libraries | `gdb` RPM package    | _Note 2_ |\n| JVM `jcmd \u003cpid\u003e GC.heap_dump` output  | `jcmd` JDK command   | _Note 1_ |\n| JVM `jcmd \u003cpid\u003e GC.class_histogram` output  | `jcmd` JDK command| _Note 1_ |\n| `strace` output (system-call logging) | `strace` RPM package | _Note 2_ |\n\n**Note 1**: JVM diagnostics must be run as the process's user. If you run the script as root, then the script uses `sudo` to run the JVM diagnostics as the process's user.\n\n**Note 2**: GDB thread backtraces, GDB core dump, and `strace` can be run as the process's user, unless prohibited by the [Yama kernel module](https://www.kernel.org/doc/Documentation/security/Yama.txt) (introduced in CentOS/RHEL 7). The script will advise you if root privileges are required to run these diagnostics.\n\n### Performance impact\n\nThe default set of diagnostics includes only one diagnostic that directly impacts the performance of the target process:\n\n*   **GDB thread backtrace**: the target process is halted temporarily for less than 1 second for each backtrace.\n\nThe optional diagnostics have a potentially greater performance impact and should only be enabled when requested by Caplin Support:\n\n*   **GDB core dump**: the target process is halted temporarily for the time it takes the [gcore](http://man7.org/linux/man-pages/man1/gcore.1.html) command to write the process's virtual memory to a core file. The execution time is determined by the size of the process's virtual memory (`ps -o vsz= -q \u003cprocess-id\u003e`) and the host's CPU and I/O performance.\n\n*   **strace**: slows performance of the target process for the duration of the diagnostic (40 seconds).\n\n*   **JVM heap dump**: halts the JVM temporarily for the duration of the diagnostic.\n\n*   **JVM class histogram**: halts the JVM temporarily for the duration of the diagnostic.\n\n### Example\n\nThe example below collates diagnostics for a Liberator running as process 4972:\n\n```console\n$ ./caplin-process-diagnostics.sh 4972\n\nCaplin Process Diagnostics\n==========================\n\nProcess ID:      4972\nProcess binary:  /home/caplin/dfw1/kits/Liberator/Liberator-7.1.9-313149/bin/rttpd\n\nScript user:     same user as process 4972\nScript temp dir: ./diagnostics-server1-rttpd-4972-20190916102608\n\nRecording /etc/redhat-release\nRecording 'uname -a' output\nRecording /proc/sys/kernel/core_pattern\nRecording /proc/sys/kernel/core_uses_pid\nRecording /proc/4972/limits\nRecording 'top' output (5 seconds)\nRecording 'top' output for process 4972 (5 seconds)\nRecording process 4972 limits (/proc/4972/limits)\nRecording 'df' output for /home/caplin/dfw1/servers/Liberator/var\nRecording 'free' output\nRecording 'vmstat' output (5 seconds)\nRecording 'dfw info' output\nRecording 'dfw status' output\nRecording 'dfw versions' output\n1/3: Dumping GDB thread backtraces for process 4972\n  Sleeping for 1 second...\n2/3: Dumping GDB thread backtraces for process 4972\n  Sleeping for 1 second...\n3/3: Dumping GDB thread backtraces for process 4972\n1/3: Dumping JVM stack trace for process 4972\n  Sleeping for 1 second...\n2/3: Dumping JVM stack trace for process 4972\n  Sleeping for 1 second...\n3/3: Dumping JVM stack trace for process 4972\nRecording JVM heap info\nRecording JVM properties\nRecording JVM flags\nRecording JVM performance counters\nRecording JVM jstat GC output\n\nDONE\n\nFiles collected:\n  df.out\n  dfw-info.out\n  dfw-status.out\n  dfw-versions.out\n  diagnostics.log\n  free.out\n  jvm-flags\n  jvm-heapinfo\n  jvm-jstat-gc\n  jvm-jstat-gcutil\n  jvm-perfcounter\n  jvm-props\n  jvm-stacktrace-20190916102810.out\n  jvm-stacktrace-20190916102811.out\n  jvm-stacktrace-20190916102812.out\n  proc-4972-limits\n  proc-sys-kernel-core_pattern\n  proc-sys-kernel-core_uses_pid\n  redhat-release\n  rttpd-backtrace-20190916102806.out\n  rttpd-backtrace-20190916102808.out\n  rttpd-backtrace-20190916102809.out\n  top-4972.out\n  top.out\n  uname.out\n  vmstat.out\n\nArchiving files to diagnostics-server1-rttpd-4972-20190916102608.tar.gz\n\nPlease login to https://www.caplin.com/account/uploads\nand upload the archive to Caplin Support.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaplin%2Fcaplin-platform-diagnostics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaplin%2Fcaplin-platform-diagnostics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaplin%2Fcaplin-platform-diagnostics/lists"}