Lesson 17.1017.10 Watching a connector

In everyday life. A package-tracking page shows each scan: picked up, sorted, out for delivery. The warehouse keeps its own records: which shelf, which belt. Joined by the tracking number, the two tell the story of a late package. Neither says whether the right item is in the box.

What you will learn. How to follow one request through the AI app and the connector, and what such a record can and cannot prove.

Why it matters. When a run is slow or wrong, only the connector's own records show what happened inside it.

Going further. The lab's servers already write one log line per request. This section shows how to follow one request through both the AI app and the connector.

One request, start to finish. Ana asks why sorting her open invoices took 40 seconds. The builder looks at two records of that run, side by side:

• The AI app's record shows three calls to list_open_invoices (17.4), then 14 calls to get_purchase_order, one per open invoice plus a repeat, about 6 seconds in all. The rest of the 40 seconds was the model reading and writing. The slowest call took 1.8 seconds. The repeat was INV-8310, the invoice with no purchase order.
• The connector's record, joined to the same run, shows why. Most of the slowest call's 1.8 seconds went to reading data files. And the first of the two identical calls returned the missing-PO tool error. The model tried again even though the error said to tell the AP lead. So the error's wording, or the tool's description, needs work.

Neither record says whether Ana's answer was right. Acceptance check A6, "Is INV-8310 ready to pay?", with the answer Ana expects, says that. This joined view needs a viewer program. In the lab you see the connector's side only.

What is a trace?

OpenTelemetry is an open standard for programs to write timed records of their work in one shared format, so any viewer can read them. A log line says one thing happened. A trace shows each step and how long it took. Three words are enough here:

• A trace is the record of one request, start to finish, such as Ana's 40-second run.
• A span is one timed step inside a trace, such as one tool call. Spans can sit inside other spans.
• Attributes are labels on a span, like "which tool" or "did it fail".

In Chapter 16 you could watch only from the AI app's side. Now the connector is your code, so you can add its side.

What can each side see?

How are the two sides joined?

The AI app can put a short ID for the trace inside each message it sends. A connector that reads it records its spans as part of the same trace, and both sides can send their records to the same viewer, a program for reading traces. If the app sends no ID, the connector's spans still exist, but stand alone. In the lab you see only the connector's side, printed on your computer (field guide F7). Joining the AI app's side needs a viewer, which the lab does not use.

What should the records be called?

OpenTelemetry has agreed names for what to record about an MCP call. For example, the span for a call to find_vendor is named tools/call find_vendor, after the message from 17.1. Use the agreed names, so any viewer understands your records. They are still a draft, so they may change. Field guide F8 lists them.

What should the records leave out?

Content. A tool's inputs and replies can hold private data, so the agreed names leave them out unless you opt in. Brightline never does. The connector records which tool ran, how long it took, how many invoices matched, and whether it failed. Never names, notes, account numbers or keys.

At work. The builder has the agent add one span per tool call, with the agreed names, an invoice count, and a smaller span for reading data. First the agent checks whether the MCP code library it uses already records each call, to avoid recording every call twice. In the project's notes file, NOTES.md, the builder names acceptance check A6, not the trace, as the evidence that the missing-PO answer was right.

The operating rule: record each call in the connector with the agreed names, join the AI app's trace when it sends one, record counts and outcomes but never content, and take correctness from tests, not traces.

Figure 17.17. The connector's spans join the AI app's trace when it sends one. The acceptance check, not the trace, says the answer was right.