Operations and Reporting#

Inspect Migration Readiness#

The Router records CPU and GPU executions under a logical job identifier. Use these APIs to understand its current state:

Endpoint

Use

GET /api/v2/job_migration_readiness

Inspect qualification, profiling, validation, and next-run readiness.

GET /api/v2/route_decision

Read the last persisted route without recalculating it.

GET /api/v2/job_recommendations

Retrieve recommended configuration or the best tested historical configuration.

For example:

curl -sS \
  'http://<router-api-host>:8000/api/v2/job_migration_readiness?aether_job_id=<job-id>' \
  | python3 -m json.tool

curl -sS \
  'http://<router-api-host>:8000/api/v2/route_decision?aether_job_id=<job-id>' \
  | python3 -m json.tool

A predicted speedup does not establish migration readiness. Review the actual GPU profile, validation outcome, and applicable cost or SLA policy. Comparing event-log metrics provides different evidence from comparing output data; interpret the validation result according to the checks run.

Analyze, Tune, and Validate#

The CLI exposes the individual stages as well as an end-to-end workflow. Use each command’s --help for release-specific options and platform requirements:

Command

Purpose

aether qualify

Analyze CPU event logs and obtain initial GPU recommendations.

aether profile

Analyze GPU event logs and update configuration recommendations.

aether tune

Execute iterative GPU trials to refine configuration and optional cluster shape.

aether validate

Validate a GPU run against a CPU baseline using the supported checks.

aether run

Orchestrate qualification, GPU execution, tuning, and validation.

aether diagnose

Compare paired CPU/GPU event logs to investigate performance.

aether cluster

Inspect, register, or manage platform clusters.

For a first analysis of existing CPU logs:

aether qualify --event_log <cpu-event-log-uri>

Qualification alone does not submit a GPU workload. Commands such as run, tune, and cluster creation can provision resources or execute jobs; configure the target platform and execution environment first.

Review Job History and Reports#

Use the report commands to inspect jobs and measured outcomes:

aether report summary
aether report list
aether report job --aether_job_id <job-id>
aether report ui

The report UI defaults to http://127.0.0.1:5000. Use the CLI’s host and port options when serving it through your deployment. Point reporting at the same job-history database as the Router service to see its runs.

Monitor the Service#

Use GET /live for process liveness, GET /healthz for readiness and database connectivity, and GET /version for runtime version information. Readiness does not confirm that remote Spark clusters or storage are usable; verify those through the relevant job or platform operation.

For shared deployments, use PostgreSQL and managed REST and worker processes. If durable queues are enabled, deploy their corresponding workers; accepted work cannot complete without them. Inspect the installed release’s worker options with aether rest worker --help.

When a Job Remains on CPU#

  1. Confirm repeated executions use the same logical job identifier.

  2. Check completion-processing status and event-log access for the CPU run.

  3. If using shadow evaluation, confirm capture artifacts exist, replay is supported and configured, and a GPU Spark Connect server can start.

  4. Inspect GPU execution failures, profiling results, and validation status.

  5. Review readiness, routing policy, and any allowlist or denylist overrides.

Keep using the normal CPU execution path while resolving missing or failing evaluation evidence. Use the Router’s recorded results to decide the next step rather than assuming that every qualified job should route to GPU.