Logs and diagnostics
Identify the affected component and time window before collecting output. Workload logs explain application behavior; operator logs explain reconciliation. A controller job, EDA activation and hub import also have their own application history. Use those views before collecting an entire platform’s logs.
Select the scope and container
The examples use Bash. Select the authorized context, platform namespace and actual component names from platform status. Select the operator namespace separately:
export KAP_CONTEXT='<context>'
export KAP_NAMESPACE='<platform-namespace>'
export KAP_NAME='<platform-name>'
export KAP_CONTROLLER='<controller-resource-name>'
export KAP_EDA='<eda-resource-name>'
export KAP_HUB='<hub-resource-name>'
export KAP_OPERATOR_NAMESPACE='<operator-namespace>'
Use oc instead of kubectl on OpenShift with the same explicit context and namespace. The
controller, EDA and hub names default to <platform-name>-controller, -eda and -hub, but can
be overridden. Operator names are fixed package names, not
names derived from KAP_NAME.
Find pods and their actual containers before choosing a log stream:
kubectl --context "$KAP_CONTEXT" -n "$KAP_NAMESPACE" get pods -o wide
kubectl --context "$KAP_CONTEXT" -n "$KAP_NAMESPACE" get pod '<pod-name>' \
-o jsonpath='{range .spec.containers[*]}{.name}{"\n"}{end}'
kubectl --context "$KAP_CONTEXT" -n "$KAP_NAMESPACE" logs '<pod-name>' \
-c '<container-name>' --since=15m --tail=200 --timestamps=true
For a restarted container in the same pod, add --previous to read its preceding instance.
That output may be unavailable after pod replacement. A logs deployment/... command selects a
pod; with several replicas, inspect each relevant pod explicitly rather than assuming one stream
covers every request.
Gateway and controller
The gateway Deployment has api and proxy containers. Inspect both when a gateway
request fails: the API handles gateway application work and the proxy routes service traffic.
kubectl --context "$KAP_CONTEXT" -n "$KAP_NAMESPACE" logs "deployment/$KAP_NAME-gateway" \
-c api --since=15m --tail=200 --timestamps=true
kubectl --context "$KAP_CONTEXT" -n "$KAP_NAMESPACE" logs "deployment/$KAP_NAME-gateway" \
-c proxy --since=15m --tail=200 --timestamps=true
kubectl --context "$KAP_CONTEXT" -n "$KAP_NAMESPACE" logs "deployment/$KAP_CONTROLLER-web" \
-c "$KAP_CONTROLLER-web" --since=15m --tail=200 --timestamps=true
The controller task pod includes four relevant containers. Select the stream matching the failure; Redis, control tasks, local execution/receptor and log forwarding are separate processes:
kubectl --context "$KAP_CONTEXT" -n "$KAP_NAMESPACE" logs "deployment/$KAP_CONTROLLER-task" \
-c redis --since=15m --tail=200 --timestamps=true
kubectl --context "$KAP_CONTEXT" -n "$KAP_NAMESPACE" logs "deployment/$KAP_CONTROLLER-task" \
-c "$KAP_CONTROLLER-task" --since=15m --tail=200 --timestamps=true
kubectl --context "$KAP_CONTEXT" -n "$KAP_NAMESPACE" logs "deployment/$KAP_CONTROLLER-task" \
-c "$KAP_CONTROLLER-ee" --since=15m --tail=200 --timestamps=true
kubectl --context "$KAP_CONTEXT" -n "$KAP_NAMESPACE" logs "deployment/$KAP_CONTROLLER-task" \
-c "$KAP_CONTROLLER-rsyslog" --since=15m --tail=200 --timestamps=true
The web pod also has a redis sidecar. Container group jobs and external execution nodes have
their own execution logs; the controller task pod is not a complete record of every job’s output.
Open the job in Automation Execution > Jobs for its status, output and execution details.
See Controller logfiles for process responsibilities and
Logging and Aggregation for external controller log forwarding.
That controller configuration does not automatically aggregate gateway, EDA, hub or operator logs.
EDA and hub workloads
Use bounded logs for the relevant service. These loops cover the default workload suffixes; skip disabled components and select individual containers/pods when necessary:
for workload in api default-worker activation-worker event-stream; do
kubectl --context "$KAP_CONTEXT" -n "$KAP_NAMESPACE" logs "deployment/$KAP_EDA-$workload" \
--all-containers=true --prefix=true --since=15m --tail=200 --timestamps=true
done
for workload in api content worker web redis; do
kubectl --context "$KAP_CONTEXT" -n "$KAP_NAMESPACE" logs "deployment/$KAP_HUB-$workload" \
--all-containers=true --prefix=true --since=15m --tail=200 --timestamps=true
done
For an activation, open Automation Decisions > Rulebook Activations, select the activation, open History, and select the instance from the failure time. Its Details shows the instance output. Inspect Automation Decisions > Rule Audit separately for rule events/actions, then the controller job if the action launched one. See EDA troubleshooting. An image pull failure may appear in pod events before any activation output exists.
For a collection import, open Automation Content > Collection Approvals > View import logs on the affected version, or open its namespace under Namespaces and choose Imports to reach My imports. Select the matching import/version. This is not a separate sidebar item. If client output is incomplete, inspect hub worker logs for the same task/time window. See Hub troubleshooting for import stages and error examples.
Database and Redis/Valkey
For managed services, read the PostgreSQL StatefulSet name and Redis mode from status, then inspect the actual pods and container names. Do not assume the PostgreSQL major-version suffix or that cluster-mode Redis has the standalone topology:
kubectl --context "$KAP_CONTEXT" -n "$KAP_NAMESPACE" get statefulsets,pods,pvc
kubectl --context "$KAP_CONTEXT" -n "$KAP_NAMESPACE" logs '<database-or-redis-pod>' \
-c '<container-name>' --since=15m --tail=200 --timestamps=true
External database/Redis diagnostics belong to their administrators. Do not copy connection Secrets, passwords or database contents into a diagnostic bundle. See the storage runbook before changing storage.
Operator reconciliation
Inspect the gateway operator for KoiosPlatform and shared-resource reconciliation, then the
operator of the affected child component. The package names below stay the same even when the
platform has a different name:
for component in gateway controller eda hub; do
kubectl --context "$KAP_CONTEXT" -n "$KAP_OPERATOR_NAMESPACE" \
logs "deployment/koios-$component-operator-controller-manager" \
--all-containers=true --prefix=true --since=15m --tail=200 --timestamps=true
done
An operator can manage several platforms. Correlate records with the affected namespace/resource name and the failure time; do not attribute another platform’s error to this one. If an operator pod is not running, inspect its events in the operator namespace, not just application logs:
kubectl --context "$KAP_CONTEXT" -n "$KAP_OPERATOR_NAMESPACE" get pods
kubectl --context "$KAP_CONTEXT" -n "$KAP_OPERATOR_NAMESPACE" get events --sort-by=.metadata.creationTimestamp
kubectl --context "$KAP_CONTEXT" -n "$KAP_OPERATOR_NAMESPACE" describe pod '<operator-pod>'
Prepare a diagnostic record
Record the release, timestamp/time zone, namespace, resource names, selected condition messages, HTTP status codes and a short log excerpt around the failure. Include the job/activation/import identifier where relevant. Preserve earlier errors before retrying an operation.
Logs, pod descriptions, job output and event payloads can contain credentials or business data. Inspect and redact locally before sharing. Refer to Secrets by name only; never include Secret data, administrator passwords, authorization headers or complete environment dumps. For longer-term collection, use your cluster’s logging facilities and retention policy rather than relying on logs surviving pod replacement. Follow the runbooks to correct the owning CR or application object and verify the result.