// Query and interpret documentation analytics data collected by Do11y. Use when asked to analyze docs performance, find pages to improve, interpret engagement metrics, investigate user behavior, audit instrumentation quality, or produce optimization recommendations from Do11y data.
| name | analyze-do11y-data |
| description | Query and interpret documentation analytics data collected by Do11y. Use when asked to analyze docs performance, find pages to improve, interpret engagement metrics, investigate user behavior, audit instrumentation quality, or produce optimization recommendations from Do11y data. |
Ask for these credentials if not already provided:
us-east-1.aws.edge.axiom.cocurl -s -X POST "https://DOMAIN/v1/query/_apl?format=tabular`" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"apl": "APL_QUERY", "startTime": "START", "endTime": "END"}'
Replace ['do11y'] with ['DATASET'] in every APL query. Results are in tables[0].columns[] (parallel arrays); field names are in tables[0].fields[].name.
Parse with:
| python3 -c "
import json,sys
d=json.load(sys.stdin)
cols=d['tables'][0]['columns']
fields=[f['name'] for f in d['tables'][0]['fields']]
for i in range(len(cols[0])):
print({fields[j]: cols[j][i] for j in range(len(fields))})
"
Run these queries in parallel for a full audit. All use ['do11y'] — replace with your dataset.
['do11y']
| extend section = extract("^/docs/([^/]+)", 1, path)
| where eventType == 'page_exit'
| summarize visits = count(), avgTime = avg(activeTimeSeconds), avgScroll = avg(maxScrollDepth) by section
| order by visits desc
['do11y']
| where eventType == 'page_view' and isFirstPage == true
| summarize entries = count() by path
| order by entries desc
| take 25
['do11y']
| summarize pageViews = countif(eventType == 'page_view'), searches = countif(eventType == 'search_opened') by sessionId, path
| where pageViews > 0
| summarize totalViews = sum(pageViews), sessionsWithSearch = countif(searches > 0) by path
| extend searchRate = round(100.0 * sessionsWithSearch / totalViews, 1)
| where totalViews > 10
| order by searchRate desc
| take 20
['do11y']
| where eventType == 'page_exit'
| summarize avgTime = avg(activeTimeSeconds), avgScroll = avg(maxScrollDepth), visits = count() by path
| where visits > 5 and avgTime < 10 and avgScroll < 25
| order by visits desc
['do11y']
| where eventType == 'page_exit'
| summarize visits = count(), avgScroll = avg(maxScrollDepth), avgTime = avg(activeTimeSeconds) by path
| where visits > 20 and avgScroll < 30
| order by visits desc
['do11y']
| where eventType == 'page_exit'
| summarize total = count(), completed = countif(maxScrollDepth >= 90) by path
| extend completionRate = round(100.0 * completed / total, 1)
| where total > 10
| order by completionRate desc
| take 20
['do11y']
| where eventType in ('toc_click', 'page_view')
| summarize tocClicks = countif(eventType == 'toc_click'), views = countif(eventType == 'page_view') by path
| where views > 10
| extend tocRate = round(100.0 * tocClicks / views, 1)
| order by tocRate desc
| take 20
['do11y']
| where eventType == 'tab_switch' and isDefault == false
| summarize switches = count() by tabLabel
| order by switches desc
| take 20
['do11y']
| where eventType == 'feedback'
| summarize total = count(), helpful = countif(rating == 'yes'), notHelpful = countif(rating == 'no') by path
| extend helpfulPct = round(helpful * 100.0 / total, 1)
| where total >= 3
| order by helpfulPct asc
['do11y']
| where eventType == 'page_view'
| order by _time asc
| summarize pages = make_list(path), pageCount = count() by sessionId
| where pageCount > 1
| extend lastPage = tostring(pages[array_length(pages) - 1])
| summarize exits = count() by lastPage
| order by exits desc
| take 20
['do11y']
| where eventType == 'page_view' and not(path startswith '/docs/')
| summarize visits = count() by path
| order by visits desc
| take 20
['do11y']
| where eventType == 'page_view' and isFirstPage == true
| summarize sessions = count() by referrerCategory
| order by sessions desc
After running the audit queries, check for these common gaps:
| Check | How to spot it | Likely cause |
|---|---|---|
| Referrer tracking blind | > 90% null referrerCategory | Referrer classification not running before first page_view fires |
| Code language unknown | > 90% language: "unknown" in code_copied events | language attribute not read from code block's CSS class |
| TOC clicks near zero | Zero or near-zero toc_click events despite traffic | TOC element selector doesn't match site markup |
| Section dwell all identical | Every row returns the same visibleSeconds | IntersectionObserver timer resetting on visibility change rather than accumulating |
| No feedback events | Zero feedback events despite traffic | Feedback widget not rendered or selector not matched |
Flag any instrumentation gaps at the top of the report before interpreting content metrics — they affect which findings are reliable.
| Metric | Good | Warning |
|---|---|---|
| Avg scroll depth | > 60% | < 25% |
| Avg active time | 30–120s | < 10s |
| Scroll completion (90%+) | > 40% | < 15% |
| Search rate after landing | Low | > 5% (confusion signal) |
| TOC click rate | < 5% | > 15% (page too long or poorly organized) |
| Feedback helpful % | > 80% | < 50% |
| Pages per session | > 3 | 1 (bounce) |
High search rate on a page = users arrived with intent the page doesn't fulfill. High TOC rate = users are hunting for a section, suggesting the page is too long or its headings are unclear. High exit rate on a page that is also a top entry point = the page is a dead end.
Use pages with scroll completion > 50% as structural templates for rewrites.
Organize output into these sections:
For each finding, cite the specific pages affected, the metric values vs threshold, and a concrete change linked to the page's file path in the docs repo where possible.
For deeper analysis — AI traffic by platform, page-to-page transitions, code copy rates, section reading patterns, expand/collapse behaviour, device breakdown — see QUERIES.md.