Logs & Monitoring

Stream live container logs, inspect builds, check pod status, and diagnose issues with AI-powered troubleshooting.

Pod logs

Stream live container output from your running pods. By default, logs follow in real time (like tail -f) and show the last 100 lines.

Basic usage

# Stream logs from your service (run from project directory)
tawa logs

# Stream production logs (default is sandbox)
tawa logs --prod

# Stream UAT logs
tawa logs --uat

Options

Flag	Description	Default
`--prod`	Show logs from the production environment	sandbox
`--uat`	Show logs from the UAT environment	sandbox
`--tail <n>`	Number of historical lines to show	100
`--no-follow`	Print logs and exit (don't stream)	follow=true
`--service <name>`	Target a different service (not the current directory)	auto-detected
`--namespace <ns>`	Override the Kubernetes namespace	`<service>-<env>`

Multi-pod output

If your service has multiple replicas, the CLI color-codes each pod (similar to PM2). A legend at the top shows which color maps to which pod:

my-api logs (prod)
Namespace: my-api-prod
Pods: 2

────────────────────────────────────
  ● 7f8a-x2k9  (Running)
  ● 3b1c-m4p7  (Running)
────────────────────────────────────

[7f8a-x2k9] INFO  Server started on port 3000
[3b1c-m4p7] INFO  Server started on port 3000
[7f8a-x2k9] INFO  GET /api/health 200 2ms

Structured logs

If your application outputs JSON logs (e.g., via pino), the CLI automatically parses them and formats the level and message. Non-JSON lines are displayed as-is.

Build logs

When a deploy is in progress (or has completed), you can inspect the build output — Docker image creation, Helm deploy steps, and errors.

# View logs for a specific build
tawa logs --build <build-id>

# Stream build logs in real-time (polls every 2s)
tawa logs --build <build-id> --follow

The build ID is printed when you run tawa deploy (e.g.,Build triggered: 98539c92). You can also find it with tawa status.

Build stages

The builder goes through these stages in order:

Stage	What happens
`queued`	Build accepted and waiting for a worker
`cloning`	Git clone from the linked repository
`building`	Docker image build (runs your Dockerfile)
`pushing`	Pushes image to the container registry
`deploying`	Helm upgrade/install to Kubernetes + DNS configuration
`completed`	Pods running, DNS active, service is live
`failed`	Something went wrong — check build logs for details

Status & builds

Check the current state of your service and its recent builds.

# Show service info + recent builds
tawa status

# Show a specific build's details
tawa status --build <build-id>

# Include Kubernetes pod status
tawa status --pods

# List recent builds (up to 10)
tawa builds

Example output

Service: my-api

  Repo: [email protected]:myorg/my-api.git
  Branch: main
  Dockerfile: Dockerfile

Recent builds:
BUILD    | STATUS    | BRANCH | COMMIT  | CREATED
---------+-----------+--------+---------+--------
98539c92 | completed | main   | f24e171 | 5m ago
62a825d6 | completed | main   | 2057621 | 1h ago
56da1710 | failed    | main   | 8e867d0 | 2d ago

Troubleshooting

When something goes wrong, the AI-powered troubleshooter analyzes logs across all related services and suggests fixes:

tawa troubleshoot

It automatically:

Fetches logs from your service and its dependencies
Redacts sensitive data from other services' logs
Identifies the root cause (missing scopes, health check failures, OOM, etc.)
Suggests specific fixes you can apply

What it detects

Issue	Symptom	Typical fix
Missing scopes	403 errors calling another service	`tawa scopes request`
Service not registered	404 from Janus gateway	`tawa register` or check `spec.routes`
Health check failure	Pod in CrashLoopBackOff	Ensure `/api/health` returns 200
Out of memory	OOMKilled status	Increase `insureco.io/pod-tier` annotation in catalog-info.yaml
Database connection	ECONNREFUSED on startup	Check `spec.databases` config

Common issues

“No pods found”

The service hasn't been deployed to that environment yet. Runtawa deploy (sandbox) or tawa deploy --prod(production).

Logs show nothing / pod is restarting

Your app is likely crashing on startup. Check:

Does your health endpoint (/api/health) respond with 200?
Are required environment variables set? (MONGODB_URI, etc.)
Run tawa logs --tail 200 --prod to see the crash output

Build fails at “building” stage

The Docker build failed. Common causes:

npm install failed — check package.json for missing/broken dependencies
npm run build failed — TypeScript errors in your code
Dockerfile copies a file that doesn't exist in the repo

View the full build output with tawa logs --build <id>.

Build succeeds but pod won't start

The image was built and pushed, but the container can't run:

Check tawa logs --prod for runtime errors
Ensure your app listens on the port specified in the Dockerfile (EXPOSE 3000)
Check memory: nano tier gives 256MB, small gives 512MB — enough for most Node.js apps

SSL certificate not ready

On the first deploy to a new subdomain, Cloudflare needs 1–3 minutes to provision the SSL certificate. Subsequent deploys are instant. Run tawa deploy --watch to see when it's ready.

Getting Started — deploy your first service
catalog-info.yaml Reference — all configuration options
Databases — how database provisioning works