Apache CloudStack performs many operations asynchronously — such as VM deployments, volume operations, and network changes. The async_job table in the CloudStack database is the primary source of truth for tracking, debugging, and correlating logs related to background jobs.

Why Async Jobs Matter

Whenever a CloudStack user (via API or UI) triggers an operation that takes time to complete, the Management Server creates an entry in the async_job table. This allows the system to:

  • Queue, monitor, and retry jobs
  • Track failures and their root cause
  • Link jobs to resources (e.g., a VM or volume)
  • Correlate job execution with logs
  • Debug user issues and system problems after the fact

Table Location

Found in the cloud database:

USE cloud;
SHOW TABLES LIKE 'async_job';

Archived jobs go to:

async_job_arch

Table Structure (Key Fields)

ColumnDescription
idUnique job ID (seen as job-1234 in logs)
user_idUser who triggered the operation
account_idOwning account
job_cmdFully qualified command (e.g., org.apache.cloudstack.api.command.user.vm.DeployVMCmd)
job_status0 = In progress, 1 = Success, 2 = Failed
job_result_code0 = OK, 1 = Error
job_resultJSON output or failure info
instance_typeType of target resource (e.g., VirtualMachine)
instance_idID of affected resource
createdTime job was created
relatedRelated job ID (for nested jobs)

How It Helps with Log Analysis

Matching job-XXXX in Logs

When you grep logs like management-server.log, you’ll see entries such as:

(API-Job-Executor-9:ctx-8b33bdf8 job-5948) Executing DeployVMCmd

This job-5948 refers to:

SELECT * FROM async_job WHERE id = 5948;

This lets you:

  • Identify which operation the log is referring to
  • See the full job result or error (which logs often abbreviate)
  • Correlate nested jobs using the related field
  • Understand sequence if multiple jobs fire for the same resource

Example Flow

  1. Log shows error during VM deploy:
job-6123: Deployment failed due to insufficient capacity
  1. Find more context:
SELECT job_cmd, instance_id, job_result
FROM async_job
WHERE id = 6123;
  1. Output might show:
{
  "errorcode": 530,
  "errortext": "Unable to create virtual machine due to insufficient capacity"
}

This can then be used to guide:

  • Capacity planning
  • Retry logic
  • User support resolution

Useful SQL Queries

Show recent jobs

SELECT id, job_cmd, job_status, job_result_code, created
FROM async_job
ORDER BY created DESC
LIMIT 20;

Show failed jobs

SELECT id, job_cmd, job_result, created
FROM async_job
WHERE job_status = 2
ORDER BY created DESC
LIMIT 20;

Show jobs for a specific VM or resource

SELECT id, job_cmd, job_status, job_result
FROM async_job
WHERE instance_id = <VM_ID>
  AND instance_type = 'VirtualMachine';

Check archived jobs (if nothing in async_job)

SELECT id, job_cmd, job_status, created
FROM async_job_arch
ORDER BY created DESC
LIMIT 20;

When to Use

Use CaseHow async_job Helps
VM won’t deploySee command, resource ID, and error message
UI spinner hangsFind out if job is stuck (status = 0)
Debug logsMatch job-xxxx to full DB context
Audit user actionsIdentify who triggered what and when
Performance issuesFind long-running or high-volume job types
Nested failuresUse related to see parent-child job chains

Tips

  • job_result is stored as JSON — copy-paste into a JSON viewer for readability
  • Use async_job_arch for historical analysis
  • Use related to trace chained jobs (e.g., DeployVM may create a volume or NIC via sub-jobs)

Summary

The async_job table is not just a backend detail — it’s an essential debugging and log correlation tool in CloudStack. Whether you’re troubleshooting a failed VM deployment or understanding backend activity patterns, this table connects user actions, resource changes, and system logs.

Use it regularly to get deep visibility into how your CloudStack system is operating.