Power & Performance with asc

Download performance metrics and diagnostic logs to monitor app performance indicators — launch time, hang rate, disk writes, memory use, battery life, termination, and animation hitches.

Authentication

asc auth login --key-id <id> --issuer-id <id> --private-key-path ~/.asc/AuthKey.p8

How to Navigate (CAEOAS Affordances)

Every JSON response contains an "affordances" field with ready-to-run commands — IDs already filled in. Follow the affordances to drill down from metrics to diagnostics to logs.

App metrics → Diagnostics → Logs flow:

// 1. asc perf-metrics list --app-id app-1 → shows performance overview
{
  "id": "app-1-LAUNCH-launchTime",
  "category": "LAUNCH",
  "latestValue": 1.5,
  "affordances": {
    "listAppMetrics": "asc perf-metrics list --app-id app-1"
  }
}

// 2. asc diagnostics list --build-id build-1 → shows hotspots
{
  "id": "sig-1",
  "diagnosticType": "HANGS",
  "weight": 45.2,
  "affordances": {
    "listLogs": "asc diagnostic-logs list --signature-id sig-1",
    "listSignatures": "asc diagnostics list --build-id build-1"
  }
}

// 3. asc diagnostic-logs list --signature-id sig-1 → shows call stacks
{
  "id": "sig-1-0-0",
  "bundleId": "com.example.app",
  "callStackSummary": "main > UIKit > layoutSubviews",
  "affordances": {
    "listLogs": "asc diagnostic-logs list --signature-id sig-1"
  }
}

Typical Workflows

Check app performance at a glance

asc perf-metrics list --app-id 123456789 --pretty

Investigate a specific metric type

# Launch time only
asc perf-metrics list --app-id 123456789 --metric-type LAUNCH --pretty

# Hang rate only
asc perf-metrics list --app-id 123456789 --metric-type HANG --pretty

Compare build-specific metrics

asc builds list --app-id 123456789 --output table
asc perf-metrics list --build-id build-abc --pretty

Diagnose hangs in a build

# 1. List diagnostic signatures (hang hotspots)
asc diagnostics list --build-id build-abc --diagnostic-type HANGS --pretty

# 2. Drill into the top signature's call stacks
asc diagnostic-logs list --signature-id sig-1 --pretty

Full investigation pipeline

# Start from builds
BUILD_ID=$(asc builds list --app-id APP_ID | jq -r '.data[0].id')

# Check performance metrics
asc perf-metrics list --build-id "$BUILD_ID" --pretty

# Find hang hotspots
asc diagnostics list --build-id "$BUILD_ID" --diagnostic-type HANGS --pretty

# Get call stacks for the heaviest signature
SIG_ID=$(asc diagnostics list --build-id "$BUILD_ID" --diagnostic-type HANGS \
  | jq -r '.data | sort_by(-.weight) | .[0].id')
asc diagnostic-logs list --signature-id "$SIG_ID" --pretty

Performance Metric Categories

Diagnostic Types

Reading Results

PerformanceMetric — one row per metric identifier (e.g. launchTime, peakMemory), flattened from the nested Xcode Metrics API. Key fields:

• category — which metric group (LAUNCH, HANG, etc.)
• latestValue + unit — most recent measurement
• goalValue — Apple's recommended target
• parentType — "app" or "build" (tells you whether this came from app-level or build-level metrics)

DiagnosticSignatureInfo — a recurring issue pattern ranked by weight (% of occurrences). Higher weight = more impactful. insightDirection of "UP" means the issue is getting worse.

DiagnosticLogEntry — individual log with device metadata and callStackSummary (top 5 frames joined with >).

Full Command Reference

See commands.md for all flags and examples.