Skip to content

Instrument your app

Labels

A label says what a right answer should cite. It is what turns a description of a query into a diagnosis.

Why a label#

ChunkTrace does not guess which chunk should have been retrieved. You tell it, and it finds the stage that lost that chunk. Without a label, a trace gets one finding, NO_LABEL, and a timeline with nothing marked.

Pass the label when you start a run:

JavaScript
const run = profiler.trace({
  query: "How many days do I have to request a refund?",
  label: { type: "keyword", values: ["30 days"] },
});

Three kinds#

Keyword#

JavaScript
{ type: "keyword", values: ["30 days", "thirty days"] }

A chunk is labeled if its text contains any of the values. Matching ignores case.

This is the easiest label to write: you know the fact the answer needs, not where it lives. Your store has to return chunk text for it to work.

Document#

JavaScript
{ type: "document", document_ids: ["refund-policy"] }

Every chunk of these documents is labeled. Use it when you know the right source but not the exact passage. Your store has to return a document_id on each hit.

Chunk#

JavaScript
{ type: "chunk", chunk_ids: ["refund-policy#2"] }

Exactly these chunks. The most precise label, and the only one that can name a chunk your index doesn't contain.

Matching happens in your app#

The SDK checks each chunk against the label before the trace leaves your process and sends only the result, a matches_label flag per chunk. Chunk text is not needed on the server. See What leaves your app.

More than one labeled chunk#

A label can match several chunks. Each one gets its own finding, and the earliest loss is the primary finding.

When nothing matches#

If no chunk matches the label, even in the unfiltered search, the finding is NOT_RETRIEVABLE. Usually the document was never indexed, or chunking split the phrase you are looking for.