OpenTelemetry Visual Handbook · lab
The agent sees the edges. Your code is the dark middle.
You added the agent, restarted, and the traces arrived: the request, the SQL query, the call to payments, all with the right attributes. The checkout takes 240 ms, and the trace explains 90 of them. The other 150 ms are in code the agent has never heard of.
Zero-code instrumentation hooks libraries. It does not know what your functions are doing between two library calls, so that time sits in the root span with no child to say where it went. A few manual spans, placed where the time is, finish the picture.
Break it
- Read the trace with nothing wrapped. Three spans, and a red track where the root span has no child: 150 ms that the breakdown does not explain.
- Wrap the discount rules. One manual span lights 70 ms; it becomes a child of the request the agent already traced.
- Wrap the cache lookup instead. 10 ms of light. Manual spans are cheap to add and expensive to read — put them where the time is, not everywhere.
Predict before you look
Answer first, then try it in the simulation.
A service runs with the auto-instrumentation agent. A request takes 240 ms; the trace shows the HTTP server span, a 40 ms database span and a 50 ms outgoing HTTP span. Where are the other 150 ms?
Commit to an answer first. You cannot change it afterwards.
What people get wrong
Each row is a belief the simulation is built to take apart. The right column is the documentation, with the link.
| What people believe | What the docs say |
|---|---|
| Auto-instrumentation traces the whole application. | It instruments the libraries it knows — frameworks, drivers, clients — by hooking them at load time. Code you wrote between two library calls produces no span. source |
| If the trace has no span for it, it did not take time. | Time inside a span that no child covers is that span's own time. In an auto-instrumented service, it is usually your business logic — present in the duration, absent from the breakdown. source |
| Manual and automatic instrumentation are alternatives. | They compose: manual spans created inside an auto-instrumented request become children of the active span, so you add them only where the edges are not enough. source |
Where this connects
Manual spans is how to write the spans this lab asks for, and what goes wrong when you do. The three providers is what the agent installs behind the API.
Check your understanding
The assessment for this lab has not been authored yet.