Build Insights

Analyze build performance, cache efficiency, and team productivity

Tuist Build Insights provides deep visibility into your build performance, helping you identify bottlenecks, optimize caching, and track improvements over time.

Overview

Build Insights captures detailed telemetry from every build:

Build Performance

Duration, file compilation, and target metrics

Cache Efficiency

Hit rates, latency, and storage analysis

Team Trends

Productivity tracking and historical comparisons

All build data is automatically collected when you run tuist build or tuist test while authenticated with Tuist Cloud.

Key Metrics

Build Duration

What it measures

Total time from build start to completion, including:

• Dependency resolution
• Source compilation
• Linking
• Resource processing
• Cache operations

Use it to:

• Track build performance trends
• Measure impact of caching improvements
• Compare build times across branches
• Identify performance regressions

Compilation Performance

What it measures

Individual file and target compilation times:

• Swift compilation
• Objective-C/C compilation
• Per-file duration
• Slowest files and targets

Use it to:

• Find slow-compiling files
• Optimize problematic code
• Identify complex type inference
• Track compilation improvements

Cache Metrics

What it measures

Binary cache performance:

• Cache hit rate (local + remote)
• Cache read/write latency
• Bandwidth usage
• Storage efficiency

Use it to:

• Validate caching is working
• Measure cache impact on build time
• Identify cache performance issues
• Optimize cache strategy

Build Issues

What it measures

Warnings and errors during builds:

• Error types and frequency
• Warning signatures
• Affected targets
• Issue trends

Use it to:

• Track technical debt
• Monitor warning reduction goals
• Identify recurring problems
• Prioritize fixes

Dashboard Views

Overview

Get a high-level summary of your project’s build health:

┌──────────────────────────────────────┐
│ Build Performance (Last 30 days)     │
└──────────────────────────────────────┘

Avg Build Time:     3m 42s  ↓ 15%
Cache Hit Rate:     87%     ↑ 12%
Successful Builds:  245/250 (98%)
Total Builds:       250

Build Timeline

Visualize build duration trends over time:

• Daily averages - Spot performance changes
• Success/failure rates - Track reliability
• Configuration breakdown - Debug vs Release
• Branch comparison - Feature vs main

Compilation Analysis

Drill into compilation performance:

Slowest Files

File	Target	Duration
NetworkManager.swift	Core	8.2s
UserViewModel.swift	Features	6.5s
APIClient.swift	Core	5.8s

Slowest Targets

Target	Files	Duration
Core	142	45.2s
Features	89	32.1s
Networking	34	18.7s

File Types

Type	Count	Total Time
Swift	315	2m 15s
Objective-C	42	28s
C/C++	8	4s

Cache Performance

Analyze cache effectiveness:

1. Hit Rates

   • Local hits: Artifacts found in local cache
   • Remote hits: Downloaded from Tuist Cloud
   • Misses: Required full rebuild

   Local:  45% (↑↑↑ 242 targets)
   Remote: 42% (↓↓  228 targets)  
   Miss:   13% (↓    71 targets)
   
2. Latency

   Read and write performance:

   • P50, P90, P99 latencies
   • Cache operation duration
   • Network bandwidth usage
3. Storage

   Cache storage metrics:

   • Total cache size
   • Download/upload volumes
   • Compression ratios

Build Comparison

Compare builds to measure improvements:

Before/After Optimization

# Run baseline build
tuist build

# Make optimizations
# ...

# Run comparison build
tuist build

View side-by-side comparison in dashboard:

Metric	Before	After	Change
Duration	5m 23s	2m 18s	🚀 -57%
Cache Hits	45%	89%	↑ +44%
Compiled Files	315	34	↓ -89%

Branch Comparison

Compare feature branch builds against main:

• Build time regression detection
• Cache performance changes
• New warnings introduced
• Compilation overhead

Custom Analytics

Tags and Labels

Organize builds with custom metadata:

# Tag builds by feature
tuist build --tag feature:payments

# Label by environment  
tuist build --tag env:staging

# Add custom metadata
tuist build --custom-values ci:github run:1234

Filter and analyze by tags in the dashboard.

CI Provider Integration

Automatic CI metadata capture:

• GitHub Actions - Workflow, run ID, PR number
• GitLab CI - Pipeline ID, job name
• Bitrise - Build slug, branch
• CircleCI - Build number, workflow ID
• Buildkite - Build ID, agent
• Codemagic - Build ID, workflow

Custom Values

Track project-specific metrics:

tuist build --custom-values \
  squad:checkout \
  sprint:42 \
  platform:ios

Query builds by custom values:

tuist insights list --custom-values squad=checkout

Alerts and Notifications

Performance Degradation

Get notified when builds slow down:

• Threshold alerts - Build time exceeds X minutes
• Regression detection - 20%+ slower than baseline
• Cache hit rate drops - Below target percentage

Build Failures

Track build reliability:

• Failure rate increases - More than X% failures
• Recurring errors - Same issue multiple times
• Flaky builds - Intermittent failures

Configure Alerts

Set up alerts in Tuist Cloud:

1. Navigate to Project Settings > Insights
2. Enable alert types
3. Configure thresholds
4. Choose notification channels (email, Slack)

API Access

Query insights programmatically:

# Get recent builds
curl -H "Authorization: Bearer $TUIST_TOKEN" \
  https://api.tuist.io/projects/PROJECT_ID/builds

# Get build details
curl -H "Authorization: Bearer $TUIST_TOKEN" \
  https://api.tuist.io/builds/BUILD_ID

Use the API to:

• Build custom dashboards
• Integrate with internal tools
• Export data for analysis
• Create custom alerts

Best Practices

Establish baselines

• Run builds consistently (same machine, config)
• Track main branch performance
• Measure before/after optimizations
• Document expected build times

Monitor trends

• Review insights weekly
• Watch for gradual degradation
• Celebrate improvements
• Share metrics with team

Act on data

• Fix slowest compilation files
• Improve cache hit rates
• Reduce warnings over time
• Optimize target dependencies

Set goals

• Target build time (e.g., under 2 minutes)
• Cache hit rate goal (e.g., 85%+)
• Zero warnings policy
• 99%+ build success rate

Example Optimizations

Reduce Compilation Time

1. Identify slow files

   Use Build Insights to find files taking >5 seconds

2. Simplify complex code

   • Break up large functions
   • Add explicit types
   • Reduce generic constraints
   • Split complex expressions
3. Measure improvement

   tuist build
   

   Compare before/after in dashboard

Improve Cache Hit Rate

1. Check cache metrics

   Identify targets with low hit rates

2. Stabilize dependencies

   • Pin package versions
   • Avoid changing shared code
   • Use stable interfaces
3. Warm cache in CI

   - run: tuist cache warm
   
4. Monitor improvement

   Track hit rate increase over time

Insights for Teams

Team Productivity

Track team-wide metrics:

• Total builds per day - Development activity
• Average build time - Developer experience
• CI vs local builds - Where builds happen
• Peak build hours - Resource planning

Cost Analysis

Understand build infrastructure costs:

• CI minutes used - Build time × runs
• Cache storage - Artifact size and retention
• Bandwidth - Cache downloads/uploads

Developer Experience

Measure and improve DX:

• Time to first build - Onboarding
• Clean build duration - Worst case
• Incremental build time - Daily workflow
• Cache effectiveness - Build speedup

Data Retention

Build data is retained according to your plan:

• Free plan: 30 days
• Team plan: 90 days
• Enterprise plan: Custom retention

Export data for longer-term analysis via API.

Privacy & Security

Build insights contain metadata only, not source code:

• File paths and names
• Build configuration
• Duration metrics
• Error messages

No source code is uploaded to Tuist Cloud.

Next Steps

Binary Caching

Optimize cache usage based on insights

Bundle Size Analysis

Analyze your app’s binary size