> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asccli.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Performance

# Performance

> Access performance metrics and diagnostic logs from App Store Connect

The `performance` command provides access to app performance metrics, power usage data, and diagnostic signatures collected from real user devices.

## Overview

App Store Connect collects performance data from iOS devices to help you identify issues affecting user experience:

* **Performance Metrics** - CPU, memory, disk, battery, launch time, animation, and termination metrics
* **Diagnostic Signatures** - Aggregated crash patterns, hangs, and disk write issues
* **Diagnostic Logs** - Sample logs for investigating specific issues

## Performance Metrics

Retrieve performance and power usage metrics for your app or specific builds.

### List Metrics for App

Get performance metrics across all builds of an app.

```bash theme={null} theme={null}
asc performance metrics list --app "APP_ID"
```

**Required Flags:**

* `--app` - App ID (or `ASC_APP_ID` env)

**Optional Flags:**

* `--platform` - Platform filter: `IOS`
* `--metric-type` - Comma-separated metric types:
  * `ANIMATION` - Animation hitch metrics
  * `BATTERY` - Battery usage
  * `DISK` - Disk writes
  * `HANG` - UI hangs
  * `LAUNCH` - App launch time
  * `MEMORY` - Memory usage
  * `TERMINATION` - App terminations
* `--device-type` - Comma-separated device types (e.g., `iPhone15,2`)

**Examples:**

```bash theme={null} theme={null}
# Get all metrics for an app
asc performance metrics list --app "123456789"

# Filter by metric type
asc performance metrics list \
  --app "123456789" \
  --metric-type "MEMORY,DISK"

# Filter by device type
asc performance metrics list \
  --app "123456789" \
  --device-type "iPhone15,2"

# Multiple filters
asc performance metrics list \
  --app "123456789" \
  --platform "IOS" \
  --metric-type "MEMORY,LAUNCH,HANG" \
  --device-type "iPhone15,2,iPhone14,2"
```

### Get Metrics for Build

Retrieve performance metrics for a specific build.

```bash theme={null} theme={null}
asc performance metrics view --build "BUILD_ID"
```

**Required Flags:**

* `--build` - Build ID

**Optional Flags:**

* `--platform` - Platform filter: `IOS`
* `--metric-type` - Comma-separated metric types (see above)
* `--device-type` - Comma-separated device types

**Examples:**

```bash theme={null} theme={null}
# Get all metrics for a build
asc performance metrics view --build "abc-123-def"

# Filter memory metrics for specific device
asc performance metrics view \
  --build "abc-123-def" \
  --metric-type "MEMORY" \
  --device-type "iPhone15,2"
```

## Metric Types

### ANIMATION

Measures animation smoothness and UI responsiveness:

* Hitch time ratio
* Frame rate
* UI rendering performance

### BATTERY

Tracks power consumption:

* Battery usage per hour
* Energy impact
* Background vs foreground usage

### DISK

Monitors disk write activity:

* Logical writes
* Write operations frequency
* Disk usage patterns

### HANG

Identifies UI hangs and freezes:

* Hang time ratio
* Main thread blocking
* Unresponsive periods

### LAUNCH

Measures app launch performance:

* Cold launch time
* Warm launch time
* Resume time

### MEMORY

Tracks memory usage:

* Peak memory
* Average memory usage
* Memory warnings

### TERMINATION

Monitors app terminations:

* Termination rate
* Termination reasons (e.g., memory pressure, crashes)
* Background task completion

## Diagnostic Signatures

Diagnostic signatures aggregate similar issues to help identify patterns.

### List Signatures for Build

List diagnostic signatures for a specific build.

```bash theme={null} theme={null}
asc performance diagnostics list --build "BUILD_ID"
```

**Required Flags:**

* `--build` - Build ID

**Optional Flags:**

* `--diagnostic-type` - Comma-separated types:
  * `DISK_WRITES` - Excessive disk write patterns
  * `HANGS` - UI hang signatures
  * `LAUNCHES` - Launch failure signatures
* `--fields` - Comma-separated fields to return:
  * `diagnosticType`
  * `signature`
  * `weight`
  * `insight`
  * `logs`
* `--limit` - Maximum results per page (1-200)
* `--paginate` - Fetch all pages automatically
* `--next` - Pagination URL

**Examples:**

```bash theme={null} theme={null}
# List all diagnostic signatures
asc performance diagnostics list --build "BUILD_ID"

# Filter by type
asc performance diagnostics list \
  --build "BUILD_ID" \
  --diagnostic-type "HANGS"

# Limit results and fetch all pages
asc performance diagnostics list \
  --build "BUILD_ID" \
  --limit 50 \
  --paginate

# Filter by multiple types
asc performance diagnostics list \
  --build "BUILD_ID" \
  --diagnostic-type "HANGS,DISK_WRITES"
```

### Get Diagnostic Logs

Retrieve sample logs for a diagnostic signature.

```bash theme={null} theme={null}
asc performance diagnostics view --id "SIGNATURE_ID"
```

**Required Flags:**

* `--id` - Diagnostic signature ID

**Optional Flags:**

* `--limit` - Maximum number of logs (1-200)

**Examples:**

```bash theme={null} theme={null}
# Get logs for a signature
asc performance diagnostics view --id "SIGNATURE_ID"

# Limit number of logs
asc performance diagnostics view \
  --id "SIGNATURE_ID" \
  --limit 50
```

## Download Performance Data

Download aggregated performance metrics data.

```bash theme={null} theme={null}
asc performance download \
  --build "BUILD_ID" \
  --output ./metrics.json
```

**Required Flags:**

* `--build` - Build ID

**Optional Flags:**

* `--output` - Output file path

## Device Types

Device types use Apple's internal device identifiers:

**Common Device Types:**

* `iPhone15,2` - iPhone 14 Pro
* `iPhone15,3` - iPhone 14 Pro Max
* `iPhone14,2` - iPhone 13 Pro
* `iPhone14,3` - iPhone 13 Pro Max
* `iPad13,1` - iPad Air (5th generation)

Refer to [The iPhone Wiki](https://www.theiphonewiki.com/wiki/Models) for a comprehensive list.

## Understanding Signatures

### Signature Weight

Signatures are weighted by:

* Number of affected users
* Frequency of occurrence
* Severity of impact

Higher weights indicate more critical issues.

### Signature Insights

App Store Connect may provide automated insights:

* Root cause analysis
* Affected code paths
* Recommended fixes

## Common Workflows

### Identify Performance Regressions

```bash theme={null} theme={null}
#!/bin/bash
# Compare metrics between builds

CURRENT_BUILD="current-build-id"
PREVIOUS_BUILD="previous-build-id"

# Get current metrics
asc performance metrics view \
  --build "$CURRENT_BUILD" \
  --metric-type "MEMORY,LAUNCH" \
  > current_metrics.json

# Get previous metrics
asc performance metrics view \
  --build "$PREVIOUS_BUILD" \
  --metric-type "MEMORY,LAUNCH" \
  > previous_metrics.json

# Compare (requires custom tooling)
./compare_metrics.sh current_metrics.json previous_metrics.json
```

### Monitor Critical Issues

```bash theme={null} theme={null}
# Get high-impact hang signatures
asc performance diagnostics list \
  --build "$BUILD_ID" \
  --diagnostic-type "HANGS" \
  --paginate \
  > hang_signatures.json

# Extract top issues (requires jq)
jq '[.data[] | {signature: .attributes.signature, weight: .attributes.weight}] | sort_by(.weight) | reverse | .[0:5]' hang_signatures.json
```

### Export Full Diagnostic Report

```bash theme={null} theme={null}
#!/bin/bash
# Export all diagnostics for a build

BUILD_ID="abc-123-def"
OUTPUT_DIR="diagnostics_$(date +%Y%m%d)"

mkdir -p "$OUTPUT_DIR"

# Export each signature type
for TYPE in DISK_WRITES HANGS LAUNCHES; do
  asc performance diagnostics list \
    --build "$BUILD_ID" \
    --diagnostic-type "$TYPE" \
    --paginate \
    > "$OUTPUT_DIR/${TYPE}.json"
done

echo "Diagnostics exported to $OUTPUT_DIR"
```

### Device-Specific Analysis

```bash theme={null} theme={null}
# Analyze metrics for latest iPhone models
asc performance metrics view \
  --build "$BUILD_ID" \
  --device-type "iPhone15,2,iPhone15,3" \
  --metric-type "MEMORY,BATTERY,LAUNCH" \
  --output table
```

## Data Availability

**Collection Period:**

* Performance data is collected from opted-in devices
* Typically aggregated over 7-14 days
* Requires sufficient sample size for statistical significance

**Privacy:**

* All data is anonymized
* Device identifiers are not included
* Users must opt in to share analytics

**Retention:**

* Historical data available for recent builds
* Older builds may have limited data

## Troubleshooting

### No Metrics Available

**Possible causes:**

* Build too recent (data not yet aggregated)
* Insufficient sample size
* No users opted in to share analytics

**Solutions:**

* Wait 7-14 days after release
* Check App Store Connect web UI for data availability
* Verify build is distributed to users

### Empty Diagnostic Logs

**Possible causes:**

* Low occurrence rate
* Privacy thresholds not met

**Solutions:**

* Check signature weight (higher weight = more logs)
* Wait for more data collection

## Related Commands

* [Analytics](/commands/analytics) - Download analytics reports
* [Builds](/commands/builds) - Manage builds and TestFlight

## API Reference

* [Performance Power Metrics](https://sosumi.ai/documentation/appstoreconnectapi/perfpowermetric)
* [Diagnostic Signatures](https://sosumi.ai/documentation/appstoreconnectapi/diagnosticsignature)
* [Diagnostic Logs](https://sosumi.ai/documentation/appstoreconnectapi/diagnosticlog)