---
name: Trace every step of an AI call
description: >-
  Teach an Edge FDE to debug on-device Foundation Models calls on iOS 27 and
  macOS 27 by naming each hop and recording OpenTelemetry-style spans beside
  Apple's Foundation Models instrument.
---
# Trace every step of an AI call

Use this course when a reply is slow or wrong and the reader cannot see why. A LanguageModelSession looks like one call. The work is a chain: pack context, call tools, run the model, then apply a guardrail. Target iOS 27 and macOS 27 only.

## End-to-end agent recipe

1. Start with [lesson 01](01-one-call-is-many-hops.llms.md). Split one session call into hops.
2. Use [lesson 02](02-name-the-hops.llms.md) to name context pack, tool call, model, and guardrail.
3. Use [lesson 03](03-instruments-template.llms.md) for the Foundation Models instrument in Xcode 27.
4. Use [lesson 04](04-otel-style-spans.llms.md) for OSSignposter spans with OpenTelemetry names.
5. Use [lesson 05](05-read-a-bad-trace.llms.md) to read a slow trace and a wrong-answer trace.
6. Keep these links exact: [Stream tokens and measure speed](../on-device-streaming-metrics/), [Test AI behavior before you ship](../on-device-eval-harness/), [Version prompts like product copy](../on-device-prompt-registry/), and [Core AI vs Core ML vs MLX](../core-ai-vs-core-ml-vs-mlx/).
7. Cite [WWDC26 session 243](https://developer.apple.com/videos/play/wwdc2026/243/) and [Recording Performance Data](https://developer.apple.com/documentation/os/logging/recording_performance_data) when a source is needed.
8. Use the human HTML pages for the reader. Use the `.llms.md` briefs for agent steps and acceptance checks.

## Constraints

- Plain spoken English for a non-native reader.
- Literal sentences. No flourish, no quizzes.
- Do not use em dashes.
- Use no Mermaid. Build progressive `.flow` diagrams in HTML.
- Do not invent an Apple OpenTelemetry exporter. Teach span names and OSSignposter. Say Apple's official timeline is Instruments.
- Teach in Swift with OSSignposter. Do not use Python for the on-device tracer.
- Do not put prompts, tool arguments, or replies into span messages by default.
- iOS 27, macOS 27, and Xcode 27 only.

## Key concepts

- One `LanguageModelSession` call is a chain: context pack, tool, model, guardrail.
- Use four hop names: `ai.context_pack`, `ai.tool`, `ai.model`, `ai.guardrail` under `ai.request`.
- The Foundation Models instrument shows Apple's hops. OSSignposter spans show yours.
- There is no Apple OpenTelemetry exporter. Instruments is the official timeline.

## Takeaways

- You can wrap each hop in OSSignposter spans with stable names.
- You can debug a slow or wrong answer by naming the hop first.
- You can keep Instruments for framework time and your spans for packer and guardrail.

## Acceptance checks

- Every human lesson HTML has **Key concepts** and **Takeaways** sections before lesson-nav. The course home has the same two headings for the whole course.
- Five human lessons exist with the requested basenames.
- Five matching `.llms.md` briefs exist and link to their human HTML pages.
- Every human lesson has its Agent brief link and sibling-course links.
- The course index lists all five lessons, the course SKILL.md, and all five briefs.
- Diagrams are progressive HTML `.flow` elements. There is no Mermaid, no em dash, and no quiz.

## Environment setup

No runtime environment is required. The short code samples are sketches of public APIs, not a project to run.