atscalectl logs collect

The logs collect command exports logs from AtScale Kubernetes components into local files for troubleshooting and support cases. The logs are collected automatically, so operators do not need to manually gather logs from individual Kubernetes resources.

You should use this command when opening an AtScale support case, during incident investigation, or when troubleshooting unhealthy deployments.

Prerequisites

logs collect requires the following Kubernetes permissions:

• pods list
• pods/log get
• secrets list. Required only when the --release-name flag isn't specified. This is required to detect the Helm release.

Usage

atscalectl logs collect [flags]

Flags

logs collect can be used with all global flags, as well as the following command-specific flags.

Flag	Default	Description
--output-dir	./atscale-logs-<timestamp>	Directory where collected logs are written.
--components	all	Comma-separated list of components to include. Component names are discovered from Kubernetes pod labels and depend on the deployed environment.
--since		Only collect logs from the specified timeframe; for example, 1h or 30m.
--tail	-1	Number of trailing log lines per container. -1 collects all available logs.
--previous	false	Also collect logs from previously terminated containers.
--init-containers	false	Also collect logs from init containers.

Output location

By default, logs are written to ./atscale-logs-<UTC timestamp>/; for example, atscale-logs-20260727-143000/. Each execution creates a new directory, so previous collections are not overwritten.

When --output-dir is included, logs are written directly into the specified directory. This directory is created automatically if it does not exist.

File naming conventions

For single-container pods, one file is created:

atscale-logs-20260727-143000/
  atscale-engine-<pod-id>.log
  atscale-db-<pod-id>.log
  atscale-keycloak-<pod-id>.log

For pods with multiple containers, one file is created per container to avoid mixing output from different ones:

atscale-logs-20260727-143000/
  atscale-proxy-<pod-id>_git-repo-syncer.log
  atscale-proxy-<pod-id>_nginx.log

When collecting init container logs with --init-containers, init containers are written separately, as well.

Logs from previously terminated containers use the .previous suffix; for example, atscale-db-<pod-id>.previous.log.

Crash loop investigation

When investigating a crash loop, if a pod happens to be restarting when you collect the logs, the current logs may only contain startup messages for that pod. To find the actual reason for the failure, you may need to collect logs for the previous container instance.

To collect the logs for the previous container instance, include the --previous flag:

atscalectl logs collect \
  --components db \
  --previous \
  --init-containers \
  --output-dir <dir>

Note

--previous only applies to containers that have restarted. Containers without previous instances are skipped.

--init-containers is useful for pods that fail before the main application container starts; for example, those that failed with an Init:CrashLoopBackOff error.

Reducing log volume

Large deployments can generate significant log output. To reduce log volume, you can use time- or line-based filtering. You can also combine these two options, if needed.

To use time-based filtering, include the --since flag:

atscalectl logs collect \
  --since 30m

To use line-based filtering, include the --tail flag:

atscalectl logs collect \
  --tail 1000

Collection summary

After collection, the logs collect prints a summary table:

Logs written to atscale-logs-20260727-143000
COMPONENT  POD                            CONTAINER  FILE                     BYTES   NOTES
db         atscale-db-<pod-id>            postgres   atscale-db-<pod-id>.log  184320
engine     atscale-engine-<pod-id>        engine     atscale-engine.log       902144

The summary includes the following columns.

Column	Description
COMPONENT	The AtScale component name.
POD	The Kubernetes pod name.
CONTAINER	The container from which logs were collected.
FILE	The output file name.
BYTES	The file size.
NOTES	Collection warnings or errors.

Note

If a container log cannot be collected, the issue is reported in the NOTES column. The command continues collecting other logs, because partial diagnostics are usually more useful during an incident than no diagnostics.

You can also use the -o json global flag to format the command's output in JSON for automation:

atscalectl logs collect \
  -o json

Sending logs to support

When sending logs to AtScale Support, it is recommended you compress them:

atscalectl logs collect \
  --since 2h \
  --output-dir <dir>
tar czf <filename>.tar.gz <dir>

Important

Be sure to review logs before sharing. Application logs may contain query text, usernames, or other environment-specific information. Verify the contents according to your organization's disclosure policy before sending them.

Logs collect usage examples

Collect all logs

atscalectl logs collect

Collect recent logs during an incident

atscalectl logs collect \
  --since 1h

Collect logs for specific components

atscalectl logs collect \
  --components engine,proxy

Write logs to a specific directory

atscalectl logs collect \
  --output-dir <dir>

Investigate a crash loop

atscalectl logs collect \
  --components db \
  --previous \
  --init-containers

Limit log volume

atscalectl logs collect \
  --components engine \
  --tail 5000

Troubleshooting log collection

No pods matched the specified components

If you receive an error stating no pods matched the specified components:

no pods matched --components

Then the specified component name does not match available pods. Component names are discovered from Kubernetes pod labels and depend on the deployed environment.

No pods found in namespace

If you receive an error stating that no pods were found in the namespace:

no pods found in namespace

Then AtScale may be installed in a different namespace, or the detected Helm release does not match the deployment. Rerun the command and specify the --namespace or --release-name flag.

A log file is empty

If a log file is empty, it means the container produced no logs during the requested timeframe. Rerun the command and specify --since with a longer timeframe, or remove it to collect all available logs.