Reading logs and events to debug your app

What this is

Where to look when your application is not working, and how to tell the difference between a problem you can fix and a problem for ByteDC support.

This matters because of how responsibility is split on Managed Kubernetes: ByteDC provides the cluster, and you debug your own application inside it. Logs and events are the tools you use to do that.

Before you start

You need a deployed application. See Deploying your first application.

The two things you can read

Container logs are the output from your application. Anything your code writes to standard output or standard error appears here. This is where you find your own error messages, stack traces and startup output.

Cluster events are the platform's record of what happened to your resources. Events tell you that a container started, that it stopped, that it was deleted, or that Kubernetes tried to pull an image. Stop and delete events on containers are both visible.

The distinction is the useful part. Logs tell you what your application said. Events tell you what happened to your application.

How to read your logs

Step 1. Open your cluster in the portal.

Step 2. Find your workload and open the pod you are interested in.

Step 3. Open the logs view.

Screenshot needed: container logs view in the portal.

Logs are also available in Headlamp if you prefer working there.

How to read events

Step 1. Open your cluster.

Step 2. Open the events view.

Step 3. Read from the most recent entry backwards.

Screenshot needed: cluster events list including a container stopping event.

Events are ordered by time, so the entry immediately before the problem is usually the one that explains it.

Working out what is wrong

A short decision path that covers most first deployments:

The pod never started at all. Look at events, not logs. There are no logs because your application never ran. The usual cause is that the image could not be pulled, so check the image name and tag are exactly right and that the image is public on Docker Hub.

The pod started and then stopped. Look at logs first. Your application ran and then exited, and it almost always says why on the way out. A stopping container event confirms the timing, and the logs give you the reason.

The pod is running but the application is not reachable. Logs and events are both fine here, so the problem is networking or configuration. Confirm your application is listening on the port you exposed. If you are trying to reach one of your own services from another, see Connecting two applications inside your cluster.

The pod restarts over and over. Your application starts, fails, and Kubernetes restarts it, which is Kubernetes working as designed. Read the logs from the most recent failure. A missing environment variable, an unreachable database or a bad configuration file are the common causes.

Nothing is visible at all, not even the cluster contents. This is not an application problem. Without a valid namespace binding the view is blocked and shows nothing, and an incorrect namespace behaves identically. Confirm your namespace with ByteDC.

What you should see when it works

You can open the logs for any pod and read your application's own output. You can open events and see a timeline of what the platform did to your resources. When something breaks, you can say whether it broke inside your application or before your application ever started.

When to contact ByteDC support

Contact support when the evidence points at the platform rather than your application:

• The cluster itself will not provision or stays stuck

• You cannot see your own resources and your namespace has been confirmed as correct

• Events show platform level failures unrelated to your image or your code

Bring your cluster name and the relevant events with you. That turns a slow conversation into a fast one.

Common problems

The logs are empty. Either your application writes nothing to standard output, or it never started. Check events to find out which.

I cannot open a shell in the container to investigate. There is no terminal access on the platform today. Logs and events are the supported way to debug. This shapes how you should build your application: log generously, because logs are what you will have. See Proof of concept limits and what changes in production.

The logs disappeared after a restart. Logs belong to the container instance. When a pod is replaced you are reading the new container. Capture what you need before restarting or redeploying.