Capture an Indexing Trace with the REST API
To debug indexing results, capture an indexing trace: it shows how a file was converted and split.
About This Task
Unlike query pipelines, an index doesn't record a trace for every run. You ask for one when you reindex a single file.
Prerequisites
- You need an API key. For details, see Generate API Keys.
- The index must be deployed.
Capture a Trace
-
Call the reindex endpoint for a file and set the
capture_tracequery parameter totrue:curl --request POST \--url "https://api.cloud.deepset.ai/api/v1/workspaces/<WORKSPACE_NAME>/indexes/<INDEX_NAME>/files/<FILE_ID>/reindex?capture_trace=true" \--header "Authorization: Bearer <YOUR_API_KEY>"The endpoint returns
204when the file is queued for indexing. -
When the run finishes, read the trace with the API:
- To list the index's traces, newest first, send a
GETrequest to/api/v2/workspaces/{workspace_id}/indexes/{pipeline_index_id}/traces. - To read one trace, including its spans, send a
GETrequest to/api/v2/workspaces/{workspace_id}/indexes/{pipeline_index_id}/traces/{run_id}.
In the UI, open the index and click the Traces tab.
- To list the index's traces, newest first, send a
Keep the following in mind:
capture_tracedefaults tofalse. If you omit it, the file is reindexed without a trace.- The trace covers the whole batch the file is indexed in, so when the queue is busy, it can also show other files. Each file in the trace has its own
capture_tracevalue, so you can tell which file you requested. - Only the single-file reindex request can capture a trace. File uploads, dataset imports, upload sessions, and reindexing files by status never capture one.The only exception is the final attempt for a file that keeps failing, which is always traced.
For the full request and response details, see the Schedule Single File For Indexing API reference.
Check the Batch Size
A trace covers a whole batch of files, so its size helps you tell whether a slow or failed run came from a large batch. Each trace reports the total source size of the batch in bytes, and each file in the batch reports its own size:
- In the UI, the Traces tab has a Batch size column. When you open a trace, the header shows the Batch size, and each file in the Files in this run list shows its size. Sizes appear in KB, MB, or GB, whichever fits best.
- With the API, the list response returns
batch_size_bytesfor each trace. The response for a single trace returnsbatch_size_bytesfor the batch andsizefor each file infiles. Both values are in bytes.
Traces recorded before the size was tracked have no batch size. The UI shows a dash for them, and the API returns null for batch_size_bytes and size.
Diagnose a File That Failed After Repeated Attempts
When indexing a file fails repeatedly, the platform makes one last attempt. If that attempt also fails, the file is marked as failed. To find out why, use these sources:
- The file's error message. It names the likely cause when the platform recognizes it, for example a worker process killed by the operating system because it ran out of memory, a timeout, or an error from a model provider. When the cause isn't recognized, the message contains the original error.
- The trace of the final attempt. You don't need to request it: the index always records a trace for this attempt, so you can see which component failed. Open the index and click the Traces tab, or read the trace with the API as described in Capture a Trace.
- The batch size. Files fail as a batch, so the error message applies to every file in that batch. Check the batch and file sizes in the trace to see whether a large file or batch caused a memory problem.
If the cause points to the size of a file, split the file or remove it from the index, then reindex the remaining files.
Related Information
Was this page helpful?