Operate

Logs, diagnose & scaling

See what your app is doing, find out why it isn’t healthy, and give it the right amount of room — the same answers in the console, the CLI, and the API.

Logs

Anything your app writes to standard output or standard error is a log line. Follow them live across every instance, or look back:

Terminal

apprail logs shop/web -f
apprail logs shop/web --tail 500 --env staging

Logs come from the service’s current instances, so lines from instances that have since been replaced aren’t kept. Send anything you need long-term to your own logging service. Build output is kept with each build, and job output with each run.

Metrics

Terminal

apprail metrics shop/web --json

CPU and memory for each instance, measured every 30 seconds, next to what the instance is allowed. The console shows the same on the service page.

Requests, errors, and where visitors come from are in Traffic.

Diagnose

When something’s wrong, start here. apprail diagnose — or Diagnose on the service page — looks at the deployment history, every instance and its restarts, and the last hour of platform events, and explains what it finds in plain words, most serious first.

Terminal

apprail diagnose shop/web

Finding	What to do
Out of memory (with the limit)	Raise memory with `--memory`, or find the leak
Process keeps exiting (with the exit code)	Check `apprail logs`; make sure the app listens on `0.0.0.0:$PORT`
Health check failing (with path and port)	Make the health path answer 2xx or 3xx quickly, or change it
The image listens on another port	Set the port Apprail names — it reads the ports the image declares
Image can’t be pulled	Check the image name, or add a registry credential
No room to start an instance	Use smaller instances or fewer of them; running instances keep serving
Deployment waiting for approval	An owner or admin approves it in the console
Never deployed	Deploy something first

It needs only read access, so a read-only agent token can diagnose without being able to change anything. With --json it returns a status — healthy, degraded, failing, deploying, not_deployed, or unknown — and the findings; the command exits with code 2 when the service is failing.

Instance size

Terminal

apprail services update shop/web --cpu 500 --memory 1024 --apply production

CPU is in millicores (1000 = one full CPU) and memory in MB. Each instance gets exactly what it asks for, reserved: 250 millicores and 512 MB by default. An instance that uses more memory than it has is restarted — diagnose will say so.

Settings changes apply on the next deployment. To roll them out now, add --apply production (or another environment); the console asks where to apply them.

Scaling

Run a fixed number of instances, or let Apprail scale on CPU between a minimum and a maximum (up to 20):

Terminal

apprail services update shop/web --instances 3
apprail services update shop/web --instances 2 --max-instances 6 --target-cpu 70
apprail services update shop/web --max-instances 0     # turn autoscaling off

Instances are added as soon as average CPU is above the target (20–95%, default 70%).
They’re removed slowly — after five minutes of lower use, one a minute — so short dips don’t cause churn. After a spike, extra instances go away about ten minutes after the load stops.
Deployments and variable changes keep the current number of instances instead of resetting to the minimum, and a rollback restores the range the release ran with.
Your workspace’s limits count the maximum, so autoscaling can never take you past them.
Works for workers too.

Scale on a queue’s backlog

A worker that consumes a queue can scale on how much work is waiting instead of on CPU. Apprail checks the queue’s backlog — messages waiting plus those in progress — about every 30 seconds, and aims for a set number per instance.

Terminal

apprail services update shop/worker --instances 1 --max-instances 8 --scale-queue orders --messages-per-instance 50 --apply production
apprail services update shop/worker --scale-queue ""   # back to CPU

With 400 messages waiting and 50 per instance, it runs 8 instances; with 30 waiting, 1.
It adds instances at once and removes them slowly: after five minutes of a smaller backlog, one a minute.
The queue is found by name in each environment, so staging’s worker follows staging’s queue.
Idle at zero. A worker scaling on a queue can have a minimum of 0 (--instances 0): after five minutes with nothing waiting it stops completely, and an instance starts within about a minute and a half of messages arriving. A new release still starts one instance so its health check proves it works.
If there’s no queue with that name, or its depth hasn’t been measured recently, the count is left alone and diagnose says why. It also warns when the backlog outgrows the maximum.

Choose a target well above what an idle instance uses. If an idle instance already sits at 30% CPU (health checks, timers), a 50% target can keep two instances running forever; the default 70% avoids that.

Sleep when idle

A web service that is only used now and then — an admin tool, a preview, a side project — can scale to zero when nobody is using it and wake on the next request.

Terminal

apprail services update shop/admin --sleep-after 15 --apply production
apprail services update shop/admin --sleep-after 0   # always on again

After the set time (5 minutes to 24 hours) with no public requests — counted at Apprail’s gateway, with any request still in flight, such as an open WebSocket, keeping it awake — it scales to zero and uses no CPU or memory.
The next request wakes it. That request, and any that arrive meanwhile, wait while an instance starts, typically a few seconds plus your app’s own start-up, and are then answered normally. If it takes longer than 90 seconds, a browser gets a “Starting up” page that retries.
Only public requests wake it. Calls from your other services to its private address fail while it sleeps, so keep services others depend on always on.
Not with CPU autoscaling, and not for workers (a worker scaling on a queue can idle at zero instead). A new release wakes it for its health check; a variable change does not.
apprail diagnose and the console say when it is asleep.

Not available yet: scaling on memory or request rate, and scheduled scaling.