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:
const run = profiler.trace({
query: "How many days do I have to request a refund?",
label: { type: "keyword", values: ["30 days"] },
});Three kinds#
Keyword#
{ 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#
{ 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#
{ 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.