Команда Cloudflare описує, як працювати з аналітикою та трасуванням для Markdown for Agents: де подивитися успішність конверсій, як відслідкувати часткові чи зламані перетворення HTML у Markdown і як витягнути ті ж дані через GraphQL та Cloudflare Traces.
Що таке Markdown for Agents і навіщо стежити за конверсіями
Markdown for Agents перетворює HTML вашого сайту на стиснутий Markdown, зручний для LLM-агентів. Від того, наскільки стабільно й повністю проходять ці конверсії, залежить:
- чи отримує агент повний вміст сторінки, а не урізану версію через ліміти контенту
- який обсяг токенів і витрат ви економите завдяки Markdown
- чи є проблемні сторінки або типи контенту, де конверсія часто ламається
Cloudflare додає до цього продукту повноцінний спостережний шар: дашборд в панелі, GraphQL Analytics API та інтеграцію з Cloudflare Traces.
Крок 1. Зайти в дашборд Markdown for Agents
У Cloudflare dashboard потрібно вибрати потрібну зону, а далі перейти до розділу Agent Readiness — Markdown for Agents. Тут зібрано три основні інструменти:
- Analytics — агрегована аналітика по конверсіях
- Logs — вибіркові події з детальними причинами успіху чи відмови
- Playground — майданчик, де можна руками запросити Markdown для конкретної сторінки і порівняти його з HTML
Що дивитися в Analytics
Розділ Analytics корисний, коли ви хочете оцінити загальну «здоровість» конверсій та ефект від стиснення:
- Conversion outcomes — скільки повних, часткових і невдалих конверсій отримано за період
- Estimated token reduction — приблизна економія токенів завдяки Markdown (обчислена за байтами, а не реальним токенайзером)
- Top converted pages — сторінки з найбільшою кількістю конверсій, на яких зазвичай варто перевіряти якість вмісту для агентів
- Top user agents — клієнти, що найчастіше ініціюють конверсії (наприклад, ваші системи, боти, інтеграції)
- Failure reasons — основні причини, чому конверсія не завершилася успішно
- Content limits — статистика спрацювання лімітів контенту
- Pages with partial or failed conversions — список проблемних сторінок, з яких варто почати діагностику
Практичний сценарій: якщо ви підключили агента до великої документації і бачите низький показник повної конверсії, варто подивитися список сторінок з частковими/failed конверсіями і саме їх використати в наступних кроках.
Як використовувати Logs для розбору помилок
Розділ Logs показує вибірку окремих подій конверсії зі статусом і подробицями. Для розслідування:
- відфільтруйте outcome по помилках або partial
- звузьте вибірку за failure reason, якщо вас цікавить конкретний тип проблеми
- за потреби використайте content-limit фільтр, щоб знайти випадки, де уперлися в ліміти
Ці логи зручні як стартовий рівень: ви бачите окремі невдалі події і можете вже переходити до більш глибокого аналізу через Traces або Playground.
Playground: ручна перевірка Markdown проти HTML
У Playground ви обираєте сторінку у своїй зоні, і сервіс генерує Markdown-запит для неї. На одному екрані можна:
- переглянути сирий Markdown
- подивитися превʼю, як цей Markdown відображається
- звірити результат з оригінальним HTML
- подивитися response headers, щоб зрозуміти деталі відповіді
- оцінити estimated token reduction саме для цієї сторінки
Це зручно для точкового налаштування: наприклад, якщо ви змінюєте верстку або структуру контенту на конкретній сторінці і хочете переконатися, що агенти й надалі отримують повний і компактний текст.
Крок 2. Підключити GraphQL Analytics API для звітів
Ті ж самі метрики, що видно в дашборді, доступні через GraphQL Analytics API. Для цього Cloudflare додає групу markdownForAgentsAdaptiveGroups на рівні зони й аккаунта.
Що можна отримати через markdownForAgentsAdaptiveGroups
За допомогою GraphQL можна витягнути, зокрема:
- загальні conversion totals за обраний період
- розподіл outcomes (успішні, часткові, невдалі)
- estimated token savings — оцінку зекономлених токенів
- page diagnostics по сторінках за останні 7 днів
Важливі обмеження, які підкреслює Cloudflare:
- лічильники — це sample-weighted estimates, тобто оцінки на основі вибірки подій, а не повний лог кожної конверсії
- економія токенів рахується з байтових оцінок для повних конверсій, а не з реальних підрахунків токенів модельним токенайзером
Тому ці дані корисні для трендів та порівнянь між сторінками/періодами, але не як точний білінг по токенах.
Приклад використання GraphQL в робочому процесі
Типові сценарії для команди, яка вже користується Cloudflare API:
- побудувати щотижневий звіт з динамікою повної конверсії й переліком найпроблемніших сторінок
- зіставити економію токенів з фактичними витратами у вашому LLM-провайдері (наприклад, OpenAI, Anthropic) на базовому рівні трендів
- виділити сторінки, де часто спрацьовують ліміти контенту, щоб окремо змінити структуру або розбити їх на менші
Приклад GraphQL-запиту наведено в офіційній документації Markdown for Agents, посилання на яку є в кінці статті Cloudflare.
Крок 3. Використати Cloudflare Traces для глибокого дебагу
Для більш детального розслідування конкретних запитів Cloudflare інтегрує Markdown for Agents з Cloudflare Traces. У трасах зʼявляється окремий span markdown_conversion для вибіркових стрімінгових конверсій.
Що видно в span markdown_conversion
У цьому span можна подивитися:
- conversion outcome — як завершилася конкретна конверсія
- input bytes і output bytes — обсяги вхідного HTML/вихідного Markdown
- converter CPU time — приблизну вартість конверсії за процесорним часом
- content-limit flags — чи спрацювали обмеження на розмір вмісту
Перевага Traces у тому, що цей span стоїть поруч з іншими частинами таймлайну запиту. Тобто можна подивитися, як витрати на конверсію співвідносяться з кешуванням, викликами воркерів, бекенд-відповідями тощо.
Приклад робочого розбору через Traces
Якщо в розділі Analytics видно сплеск failed конверсій на певних сторінках, можна:
- знайти декілька відповідних подій у Logs
- перейти до відповідних трас (якщо вони потрапили до вибірки)
- відкрити
markdown_conversionspan і подивитися, що саме відбувалося: чи задовго тривав конвертер, чи був надто великий input, чи спрацював content limit - зіставити це з іншими span-ами запиту — наприклад, великим часом відповіді origin або затримкою в іншому сервісі
Такий підхід допомагає зрозуміти, чи потрібно змінювати сам контент, налаштування Markdown for Agents чи інфраструктуру навколо.
Де шукати подробиці та приклади запитів
Cloudflare зводить технічні деталі в одному розділі документації Markdown for Agents. Там є:
- опис полів для GraphQL Analytics API в секції GraphQL Analytics API
- пояснення по Cloudflare Traces і полях span
markdown_conversion - приклад GraphQL-запиту до
markdownForAgentsAdaptiveGroups, який можна взяти за основу для власних звітів
Для виробничих сценаріїв варто орієнтуватися на те, що всі аналітичні значення засновані на вибірці й байтових оцінках, а отже підходять для моніторингу і порівнянь, але не як точні дані білінгу на рівні окремого запиту.
Джерело: Cloudflare Changelog