How to troubleshoot your deployment

When things don’t seem to be working, the first step should always be to gather as much information as possible. This document points to some ways to do so.

Contents:

View deployment status

When trying to get an overview of what is going on in the deployment, the juju status command is the best place to start. Extra arguments can be passed to the status command to zoom in on particular parts of the deployment and display more detail.

See more: juju status

When filing bugs and requesting help it’s almost always better to use the status with the --format=yaml flag as this includes additional details that do not fit in the tabular format.

Show component detail

The output from juju status provides a great summary of what’s going on. But to zoom in a bit the show commands provide an extra level of detail:

Retry with --show-logs or --debug

Most juju commands support the addition of the --show-logs and --debug argument. Retrying a failed command with these options can help you to understand which step is failing.

  • The --show-logs options will output the logs generated by the juju CLI to the command line.
  • The --debug option will provide a greater level of detail, though this can sometimes be overwhelming.

These options are especially helpful with commands that perform a complex series of tasks, such as juju bootstrap, e.g.

juju bootstrap localhost --debug

Collect the logs

Juju aggregates the logs from all machines and units on a model and makes these available through the juju debug-log command. This allows you to see everything going on and lets you delve into the details. The --replay option can be used to view the whole log file rather than just new additions.

Different types of logs are stored in different places; juju debug-log is a good place to start, but you may need to delve into the files in situ.

See more: How to manage logs, Juju logs

Get inside the units

To get inside a machine or unit, use the juju ssh command can be used From there you can view logs stored there, check the status of your workload, or the Juju agent binary.

To debug an issue with a particular charm hook, use juju debug-hooks to ssh inside a machine, with the environment and working directory set up as it is when Juju runs hooks. This allows you to manually fix the error by manually configuring the workload, or editing the charm code. Once it is fixed you can run juju resolved to inform the charm that you have fixed the issue and it can continue.

See more: Charm SDK | Debug a failing hook, juju debug-hooks, juju resolved

Get in touch

If you are still stuck on something, do not hesitate to reach out to us on our public Charmhub Matrix chat or our public Charmhub Discourse forum.

Contributors: @aflynn, @tmihoc

Last updated 3 days ago. Help improve this document in the forum.