Troubleshooting

Locating app logs and data (dx directory)

For single-node development on Docker containers, when troubleshooting, a good place to start is to inspect the dx directory, which contains all application and system logs and data. If you started the container using gx start , the dx directory will be located under $HOME/dx or at the path you provided if you specified a --path. If not, it can be located by running docker inspect -f '{{ .Mounts }}' containerid \

Reporting a bug to Grainite

If you encounter an issue you believe to be a bug in Grainite, please contact [e-mail] and include as much information as possible, including:

• The full error that was seen in the console output. This may be in the form of an error message, an exception, stack trace, warning, etc.

• An attachment containing the logs. Instructions for collecting logs are below. Please follow the steps that pertain to your environment (cluster vs. single-node machine)

  • If the logs are too large to attach, you may upload them to a cloud storage folder that is accessible to your Grainite point-of-contact or the one we have provided for you, if applicable.

• A description of the scenario where the issue was encountered, i.e. how it can be reproduced.

• Environment details:

  • Deployment type: Cluster or Single-node (development machine, VM, etc)

    • Please confirm that the minimum hardware requirements are provisioned.

  • Operating system

• Priority of the issue:

  • P0 - Showstopper. This is impacting your business or you are blocked on development.

  • P1 - Bug that needs to be fixed, but you found a reasonable workaround.

  • P2 - Would be good to fix.

Collecting logs from a Cluster deployment

To collect application and server logs from a cluster deployment to share with the Grainite team, run the following script to collect logs from a cluster deployment:

<samples_path>/support-tools/gen-support-bundle-k8s.sh -c <cluster name> [ -g <gx binary path> ] [ -o <output directory> ] [ -p <password> ] [ -n <namespace> ]

Where

• <samples_path> is the path to the samples directory on your development machine

• <cluster name> is the name of the cluster.

• <gx path> is the path to the gx CLI.

  • This is only needed if gx binary path is not present in PATH.

• <output directory> is the directory in which to copy the files.

  • If it is not provided, logs will be stored under /tmp/sub.XXXXXX.

• <password> is the pkcs12 certificate password passed to gx.

  • This is only needed if the cluster has TLS enabled.

• <namespace> is the kubernetes cluster namespace.

  • This is only needed if the namespace is not default.

• -a when specified, will collect detailed information including potentially large artifacts such as cores. Generally this is not needed unless requested by the Grainite team for deeper debugging

Collecting logs from a local Docker deployment

Run the following script to collect logs if running Grainite on a docker container:

<samples_path>/support-tools/gen-support-bundle-docker.sh [-d dx_dir_path] [ -c <container_name> ] [ -o <output directory> ]

Where:

• <samples_path> is the path to the samples directory on your development machine

• dx_dir_path is the path of dx directory.

• <container_name> is the name of the container.

  • This is only needed if the container name is not grainite.

• <output directory> is the directory in which to copy the files.

  • If it is not provided, logs will be stored under /tmp/sub.XXXXXX.

• -a when specified, will collect detailed information including potentially large artifacts such as cores. Generally this is not needed unless requested by the Grainite team for deeper debugging

Crash Reports (Linux)

This section only applies to running single-node Grainite Docker containers on Linux. It does not apply to Grainite Kubernetes clusters or single-node containers running on Mac. In these cases, no additional work is needed. The below steps are only applicable if running a single-node Grainite container on Linux.

If running a single-node Grainite docker container on Linux, the below steps will need to be perform to be able to properly generate core files for system crash reports. These files can be collected to help the Grainite team debug any system failures.

1. Skip this step and move to step 2 if you're using any version of Linux besides Ubuntu. If using Ubuntu, first we need to disable apport. To do so:

   • First, run sudo vi /etc/default/apport

   • In that file, there may be a line that says enabled=1. If so, change it to enabled=0

2. Run the following command:

sudo sysctl -w kernel.core_pattern=/home/grainite/dx/cores/core.%e.%p.%t