---
title: Metal debugger
framework: xcode
role: collectionGroup
path: xcode/metal-debugger
---

# Metal debugger

Debug and profile your Metal workload with a GPU trace.

## Overview

Overview The Metal debugger consists of a suite of tools for debugging and profiling your Metal app. Unlike pausing at breakpoints during runtime, you can capture your Metal workload for multiple frames and then jump back and forth in time to explore the captured work. The Metal debugger enables you to explore the dependencies between passes, and offers insights for improving the performance of your app. You can also debug your shaders in draw commands and compute dispatches to fix sources of artifacts (see Investigating visual artifacts). In addition, the Metal debugger displays your Metal workload on a profiling timeline and offers detailed statistics like performance counters and per-line shader profiling data. These tools can help you identify and eliminate performance bottlenecks in your app (see Optimizing GPU performance). To investigate GPU traces from the command line, use gpudebug, an interactive terminal-based debugger. Because its interface is text-based and self-discoverable, AI agents can run it autonomously to navigate traces, inspect state, and fetch resources to diagnose rendering issues without human intervention. For more information, see Investigating GPU issues with AI agents.

For additional information about the Metal debugger, see the following video sessions: Metal Shader Debugging and Profiling Gain insights into your Metal app with Xcode 12 Optimize Metal apps and games with GPU counters Discover Metal debugging, profiling, and asset creation tools Profile and optimize your game’s memory

## Topics

### Essentials

- [Capturing a Metal workload in Xcode](xcode/capturing-a-metal-workload-in-xcode.md)
- [Capturing a Metal workload programmatically](xcode/capturing-a-metal-workload-programmatically.md)
- [Replaying a GPU trace file](xcode/replaying-a-gpu-trace-file.md)
- [Investigating visual artifacts](xcode/investigating-visual-artifacts.md)
- [Optimizing GPU performance](xcode/optimizing-gpu-performance.md)
- [Debugging with interactive command-line tools](xcode/debugging-with-interactive-command-line-tools.md)
- [Investigating GPU issues with AI agents](xcode/investigating-gpu-issues-with-ai-agents.md)

### Metal workload analysis

- [Analyzing your Metal workload](xcode/analyzing-your-metal-workload.md)
- [Analyzing resource dependencies](xcode/analyzing-resource-dependencies.md)
- [Analyzing memory usage](xcode/analyzing-memory-usage.md)
- [Analyzing Apple GPU performance using a visual timeline](xcode/analyzing-apple-gpu-performance-using-a-visual-timeline.md)
- [Analyzing Apple GPU performance using counter statistics](xcode/analyzing-apple-gpu-performance-using-counter-statistics.md)
- [Analyzing Apple GPU performance with performance heat maps](xcode/analyzing-apple-gpu-performance-using-performance-heatmaps-a17-m3.md)
- [Analyzing Apple GPU performance using the shader cost graph](xcode/analyzing-apple-gpu-performance-using-shader-cost-graph-a17-m3.md)
- [Analyzing non-Apple GPU performance using counter statistics](xcode/analyzing-non-apple-gpu-performance-using-counter-statistics.md)

### Metal resource inspection

- [Inspecting acceleration structures](xcode/inspecting-acceleration-structures.md)
- [Inspecting buffers](xcode/inspecting-buffers.md)
- [Inspecting pipeline states](xcode/inspecting-pipeline-states.md)
- [Inspecting sampler states](xcode/inspecting-sampler-states.md)
- [Inspecting shaders](xcode/inspecting-shaders.md)
- [Inspecting textures](xcode/inspecting-textures.md)

### Metal command analysis

- [Inspecting the bound resources for a command](xcode/inspecting-the-bound-resources-for-a-command.md)
- [Inspecting the geometry of a draw command](xcode/inspecting-the-geometry-of-a-draw-command.md)
- [Inspecting the attachments of a draw command](xcode/inspecting-the-attachments-of-a-draw-command.md)
- [Debugging the shaders within a draw command or compute dispatch](xcode/debugging-the-shaders-within-a-draw-command-or-compute-dispatch.md)
- [Analyzing draw command and compute dispatch performance with GPU counters](xcode/analyzing-draw-command-and-compute-dispatch-performance-with-gpu-counters.md)
- [Analyzing draw command and compute dispatch performance with pipeline statistics](xcode/analyzing-draw-command-and-compute-dispatch-performance-with-pipeline-statistics.md)

## See Also

### Graphics

- [Metal developer workflows](xcode/metal-developer-workflows.md)