---
title: "Add OpenTelemetry-style spans"
lesson_id: "04"
---

# Add OpenTelemetry-style spans

- **Lesson ID:** 04
- **Goal:** Add OSSignposter spans with OpenTelemetry-style names. State that Apple does not ship an OTel exporter for this API.
- **Human lesson:** [04-otel-style-spans.html](04-otel-style-spans.html)

## Prerequisites

- Lesson 03, or a recorded Instruments trace.

## Inputs, outputs, and artifacts

- **Inputs:** The four hop names.
- **Outputs:** A small span helper and a nesting rule.
- **Artifacts:** Progressive `.flow` diagrams and a signpost sketch.

## Agent build steps

1. Say there is no official Foundation Models OpenTelemetry exporter.
2. Name OSSignposter as the Apple recorder.
3. Use ai.request, ai.context_pack, ai.tool, ai.model, ai.guardrail.
4. Forbid prompts in span messages.
5. Mark the helper as a sketch.

## Constraints

Keep the language simple, friendly, and literal. iOS 27 and macOS 27 only. No quizzes, Mermaid, or em dashes. Do not invent API names. Mark sketches as sketches and tell the reader to confirm them in the Xcode 27 SDK.

## Key concepts

- Apple does not ship an OpenTelemetry exporter. Use the span idea with OSSignposter.
- Parent `ai.request` has children for context pack, model, and guardrail.
- Nest `ai.tool` per tool call.
- Attributes carry tool, model, profile, and prompt version. No user text in the span body.

## Takeaways

- Keep the same span names in every feature.
- Two tool calls means two `ai.tool` child spans.
- Names matter even without a collector.

## Acceptance checks

- OTel-style names are listed.
- OSSignposter is the recorder.
- Prompt text is forbidden in spans.
- Sibling links, progressive `.flow` diagrams, and an Agent brief link are present.
- [ ] Proceed to [lesson 05 brief](05-read-a-bad-trace.llms.md).