Back to Zing Documentation Home
About the zing-core-bundler
Script
ZVM Core Bundling
If automatic core bundling is not enabled, you can manually bundle the core files with the shared libraries that were in use by the ZVM instance running the Java application when it failed.
If you are running a system based on Red Hat Enterprise Linux 5.2 or CentOS Linux 5.2, the automatic core bundler is not on, so core files need to be bundled manually. For this purpose the script zing-core-bundler
is provided. This script, as part of the ZST installation, is located in the /usr/sbin
subdirectory of the ZST installation.
The zing-core-bundler
bundles the required files needed to debug a Zing Virtual Machine core. It assembles, collects, and bundles the core file along with the shared objects, data, and executable files in-use to an encrypted gzipped tarball (.tgz.gpg
) archive.
To manually bundle the core file with shared libraries:
-
On RHEL, SLES, and Ubuntu systems, ensure the development tools package group is installed.
$ yum groupinstall 'Development Tools'
Note:
Selected development tools are required to bundle RHEL 5 core files. If they are not installed, the shared libraries, which were used at the time of the crash and are essential to processing the core file, are not included.
-
Locate the core file.
Core files are bundled and stored in the current working directory of the process that crashed.
Note: Typically, you create a core bundle on the system where the core file was created, for example hostA. If you run the
zing-core-bundler
command with a copy of the core file on a different system, for example hostB, then include the-bundle-on-current-host
option. -
On Ubuntu systems, ensure that the strings command is available. If it is not, install the package,
binutils.
# apt-get install binutils
-
If you use the jsvc tool to start your application, to generate Zing core files:
# kill -SIGABRT <PID>
-
Ensure
/usr/sbin
is in your Zing executable path. For example:To your appropriate
profile
file, add:export PATH=/usr/sbin:$PATH
-
Run the
zing-core-bundler
command. At the ZVM host command line,where ZST is installed:To create a bundle with only related shared libraries that does not include the .jar files.
/usr/sbin/zing-core-bundler -core core<pid>
For example:
$ /usr/sbin/zing-core-bundler -core core.1234 -getall -hsfile hs_err_pid1234.log
A compressed and encrypted tar file ending in .tgz.gpg is returned.
In this example, the package contains the core file, the
.jar
files, and because the-getall
option is specified, it also contains the related shared libraries which were used in the ZVM instance running the Java application.-
The
-getall
option ensures the bundle contains all application related data including the.jar
files. -
The
-hsfile
option creates an additional file that provides additional information useful for support to identify issues.
Notes:
-
Encryption error
If there is a file with the same name as the core bundle, the core bundle will not be encrypted and the following message is displayed in the core bundling response.
INFO: Encrypting core bundle libs.1234.tgz ... gpg: libs.1234.tgz: encryption failed: File exists ERROR: Encryption failed. WARNING: Core bundle is not encrypted INFO: Core bundle at libs.1234.tgz
-
Bundler host error
Typically, you create the bundle on the same system where the core file was created. If you are not creating the bundle on the originating core file system, and you did not specify the required option, the following message is displayed in the core bundling response.
ERROR: The bundler must run on host <hostname> ERROR: Use the argument '-bundle-on-current-host' to bundle on this host
To create the bundle on a different system:
-
Copy the core file from the originating core file system (hostA) to hostB.
-
On hostB, include the
-bundle-on-current-host
option when you run thezing-core-bundler
command.
-
The zing-core-bundler
syntax and options are listed below.
zing-core-bundler [-core COREFILE][-getexe] [-getall] [-exepath executable file path] [-hsfile hs_err_pid<pid>.log file] [-decrypt file] [-passwordfile password file path] [-bundle-on-current-host
Option | Description |
---|---|
-core
|
Specify the core file to be bundled. |
-bundle-on-current-host
|
Create bundle on current host. This allows bundling a core file that was generated on another host. |
-exepath
|
Specify the path of the binary that was used to invoke Zing Virtual Machine. |
-decrypt
|
Specify file to decrypt |
-getall |
Include all possible files associated with the crash. This includes shared objects, data, and executable files. |
-getexe
|
Include non-java executable with the bundle. This is bundled if it is available on the host at the time of bundling. |
-hsfile
|
Explicitly specify the path of the hs_err file. |
-passwordfile
|
Specify decryption password file. |
-help
|
Print options help. |
-output-dir | -o
|
Bundle will be produced at the location specified. |
- Locate the bundled
libs.<corepid>.tgz.gpg
file.
The libs.<corepid>.tgz.gpg
file is created in the current directory.
For example, If you execute the command from /home/test
. The bundled libs.<corepid>.tgz.gpg
file is created in /home/test
.
Ensure you have write permissions in the executing directory. In this example, /home/test
.
- Send the generated bundle to Azul for failure analysis.
Decrypting Core Files
Core bundles created through zing-core-pattern
, whether they are automatically or manually created and bundled, are encrypted. Files contained in the core bundle are not encrypted individually. The core bundle filename format is: libs.<corepid>.tgz.gpg
, where <corepid>
is a unique ID specific to the process that encountered an error and crashed.
Note: |
Core files are not encrypted if |
To decrypt the Zing core bundle:
- Locate the core bundle file.
- Run the command:
$ /usr/sbin/zing-core-bundler –decrypt libs.<corepid>.tgz.gpg
For example:
$ /usr/sbin/zing-core-bundler -decrypt libs.12830.tgz.gpg INFO: Decrypting file libs.12830.tgz.gpg gpg: CAST5 encrypted session key gpg: encrypted with 1 passphrase gpg: encrypted with RSA key, ID 2934892D SUCCESS: Decrypted file libs.12830.tgz
Core Bundling with Docker Containers
You can select one of the following options to collect core dumps from the Docker container:
Option 1
Install zing-core-pattern
to dump and bundle cores while using docker:
# system-config-zing-core-pattern enable
Bundles will be kept under /var/crash/<docker_container_id>
on the host.
Option 2
Use zing-core-bundler
script to bundle the core dumped by a docker container process:
# zing-core-bundler -c <core> --dockercontainerid <docker_container_id>
Note: | The container should be running while using the above script. |
© Azul Systems, Inc. 2020 All rights reserved. |
![]() ![]() ![]() |
|