Перейти к содержанию

Глава 34. Трассировка и диагностика

Действия трассировки предназначены для отладки обработки запросов. Используются преимущественно в слое <Diagnostics>, но могут размещаться в любом слое для точечной диагностики.

Поддерживаемые свойства. Канонический набор trace.* в BlueCoat 7.3 — четыре свойства: trace.request(), trace.destination(), trace.session(), trace.diagnostic(). Из них поддержаны trace.request и trace.session, а trace.destination управляет путём вывода. trace.diagnostic() в BlueCoat нельзя писать руками (генерируется автоматически из define probe) — Redcoat его не разбирает (при недоступности — отказ); проявляется только при импорте скомпилированной BlueCoat-политики с define probe. Дополнительно поддержано Redcoat-расширение trace.rules(yes|no) (отдельного trace.rules в BlueCoat 7.3 нет — там детализация правил входит в вывод trace.request). Семейство неработающих форм (trace(), trace.level(), trace.response(), trace.body(), trace.timing(), trace.id(), trace.output()) удалено — раньше они молча ничего не делали при разборе; теперь CPL их не принимает (строки пропускаются, валидация завершается ошибкой). Вывод трассировки извлекается по BlueCoat-совместимому URL https://<appliance>:8081/Policy/Trace/<path> (+ структурный /api/v1/policy-trace/*).

34.1. trace.request(yes|no) — трассировать транзакцию

Включает трассировку и помещает в трассу полное описание обрабатываемой транзакции (параметры запроса, выставленные свойства, эффекты всех действий). Это фактический «мастер-переключатель»: при trace.request(no) вывод не генерируется вообще, даже если активен trace.rules.

Синтаксис:

trace.request(yes|no)

Тип: Нетерминальное. Слои: любой (обычно <Diagnostics>). Алиас: trace_request(...).

Пример:

<Diagnostics>
    client.address=10.0.1.100 trace.request(yes)

34.2. trace.rules(yes|no) — трассировать оценку правил [Redcoat extension]

⚠️ Redcoat-расширение, НЕ BlueCoat 7.3. Отдельного свойства trace.rules в BlueCoat 7.3 нет — там детализация оценки правил (match / miss / n/a) входит в вывод trace.request. Redcoat выделяет это в отдельную форму как удобство.

Управляет трассировкой оценки правил: какие правила дали match / miss / n/a.

Синтаксис:

trace.rules(yes|no)

Тип: Нетерминальное. Алиас: trace_rules(...).

Пример:

<Diagnostics>
    client.address=10.0.1.100 trace.request(yes) trace.rules(yes)

34.3. trace.destination(<path>) — куда писать трассировку

Направляет вывод трассировки в именованный объект. path — имя файла, путь-директория или оба, относительно корня Policy/Trace. Запись происходит после полного завершения обработки запроса и связанного ответа. Извлекается по https://<appliance>:8081/Policy/Trace/<path>.

Синтаксис:

trace.destination(<path>)

Тип: Нетерминальное.

Нормализация (BlueCoat-паритет). Пустое значение или путь-директория (с завершающим /) резолвятся в default_trace.html внутри неё (subdir/ → subdir/default_trace.html). Применяется одинаково на стороне записи (ключ хранилища) и чтения (/Policy/Trace/<path>).

Пример:

<Diagnostics>
    url.host=example.com trace.request(yes) trace.destination(example/)
    ; → трасса доступна на /Policy/Trace/example/default_trace.html

34.4. trace.session(yes|no) — трассировать всю сессию

Свойство BlueCoat 7.3 (CPL Reference, «Tracing», стр. 369). При yes трассируются все транзакции, завершающиеся в текущей сессии. В слое <SSL-Intercept> это покрывает SSL-intercept-транзакцию, SSL-tunnel-транзакцию и (если перехвачены) любые HTTPS forward-proxy-транзакции, порождённые на сессии. По умолчанию — no.

Поведение: трассировка включается на всё соединение; вложенные SSL-intercept-транзакции наследуют это включение.

Синтаксис:

trace.session(yes|no)

Тип: Нетерминальное. Алиас (Redcoat): trace_session(...).

Слои: <Admin>, <Cache>, <Diagnostic>, <DNS-Proxy>, <Exception>, <Forward>, <Proxy>, <SSL>, <SSL-Intercept>. Транзакции: все.

Особенность (частичная совместимость с BlueCoat). Включение трассировки имеет защитный срок жизни 5 минут (а не строго «время жизни сессии»); сессия не объединяется между переподключениями (каждое TCP-соединение — отдельная область действия).

Пример:

<Diagnostics>
    client.address=10.0.1.100 trace.session(yes)

Удалённые формы. Следующие не-BlueCoat формы ранее молча ничего не делали при разборе и удалены — теперь CPL их не принимает: trace(yes|no), trace.level(...), trace.response(...), trace.body(...), trace.timing(...), trace.id(...), trace.output(...). Канонический аналог trace.output — trace.destination (§34.3).

34.7. profile(yes/no) — профилирование

Включает сбор метрик производительности для совпавших запросов.

Синтаксис:

profile(yes|no)
profile.output(<file>)

where: yes/no — включить/отключить; file — путь к файлу отчёта.

Тип: Нетерминальное (оба).

Слои и транзакции: Diagnostics.

Пример:

<Diagnostics>
    profile(yes)
    profile.output(/tmp/profile.log)

34.8. debug.header(name, value) — отладочный заголовок

Добавляет пользовательский отладочный заголовок в HTTP-ответ.

Синтаксис:

debug.header(<name>, <value>)

where: name — имя заголовка; value — значение.

Тип: Нетерминальное.

Слои и транзакции: Diagnostics.

Пример:

<Diagnostics>
    debug.header(X-Debug-Rule, "matched_admin_block")

34.9. debug.request_id(yes/no) — идентификатор запроса

Добавляет заголовок X-Request-ID к ответу.

Синтаксис:

debug.request_id(yes|no)

Тип: Нетерминальное.

Слои и транзакции: Diagnostics.

34.10. debug.timing(yes/no) — тайминг в заголовках

Добавляет заголовок X-Proxy-Timing с метриками производительности.

Синтаксис:

debug.timing(yes|no)

Тип: Нетерминальное.

Слои и транзакции: Diagnostics.

34.11. dump.request_headers / .response_headers / .request_body / .response_body

Включает дамп заголовков и/или тела в отладочный вывод.

Синтаксис:

dump.request_headers(yes|no)
dump.response_headers(yes|no)
dump.request_body(yes|no)
dump.response_body(yes|no)

Тип: Все четыре — нетерминальные.

Слои и транзакции: Diagnostics.

34.12. timing.threshold(ms) — порог замедления

Логирует запросы, обработка которых превысила указанный порог. Записывает в лог с деталями тайминга.

Синтаксис:

timing.threshold(<ms>)

where: ms — порог в миллисекундах (целое число).

Тип: Нетерминальное.

Слои и транзакции: Diagnostics.

Пример:

<Diagnostics>
    timing.threshold(1000)                 ; логировать запросы > 1 секунды

Комплексный пример:

<Diagnostics>
    ; Трассировка запросов от конкретного клиента
    client.address=10.0.1.100 trace.request(yes) trace.rules(yes) trace.session(yes)

    ; Логирование медленных запросов
    timing.threshold(1000)

    ; Добавить request ID ко всем ответам
    debug.request_id(yes)

    ; Дамп заголовков для отладки
    client.address=10.0.1.200 dump.request_headers(yes) dump.response_headers(yes)