Automated log sampling for review workflows

Last updated: March 6, 2026

Summary

Automatically sample a percentage of logs and flag them for human review using BTQL's SAMPLE clause to randomly select spans, then the API to mark them for review. This provides two approaches: sampling any random spans or sampling complete traces by targeting root spans only.

Applicable To

Plans: Any

Deployments: Any

Configuration Steps

Method 1: Sample random spans

Step 1: Query for random span IDs

Use BTQL with SAMPLE clause to randomly select spans for review:

select: id 
from: project_logs('<project_id>')
filter: created >= now() - interval 30 day
sample: 1%
-- limit: 1000 -- optional hard limit

Run this query via the BTQL API to get a list of span IDs.

Step 2: Flag spans for review

Use the API to mark sampled spans for review following the flagging logs via API guide.

Method 2: Sample complete traces (root spans only)

Step 1: Query for root span IDs

First, fetch a list of root span IDs to ensure you sample complete traces:

select: root_span_id 
from: project_logs('<project_id>')
filter: created >= now() - interval 30 day
sample: 0.5%
-- limit: 1000 -- optional hard limit

Step 2: Query for corresponding span IDs

Then fetch the span IDs for the sampled root spans:

select: id
from: project_logs('<project_id>')
where: span_id IN ('<root_span_id_1>', '<root_span_id_2>', '<root_span_id_n>')

Note: span_id and id are different fields. You'll need to build the second query in a script to include the full list of root span IDs.

Step 3: Flag spans for review

Use the API to mark the sampled root spans for review following the flagging logs via API guide.

Important Notes

The SAMPLE clause only works with BTQL syntax, not in UI filters
Method 1 samples any span within traces; Method 2 samples root spans for complete trace context
Both methods require scripting to process the query results and make API calls