IKuznetsov: Новая страница: «= Мониторинг производительности веб-запросов = ЕдиныйАгент для '''Android''' предоставляет комплексные возможности мониторинга веб-запросов. * Автоматическая инструментация — автоматически фиксирует все веб-запросы, отправленные через `HttpUrlConnection` и...»

2026-08-19T16:43:41Z

Новая страница: «= Мониторинг производительности веб-запросов = ЕдиныйАгент для '''Android''' предоставляет комплексные возможности мониторинга веб-запросов. * Автоматическая инструментация — автоматически фиксирует все веб-запросы, отправленные через <code>HttpUrlConnection</code> и...»

Новая страница

= Мониторинг производительности веб-запросов =

ЕдиныйАгент для '''Android''' предоставляет комплексные возможности мониторинга веб-запросов.

* Автоматическая инструментация — автоматически фиксирует все веб-запросы, отправленные через <code>HttpUrlConnection</code> или <code>OkHttp</code>.
* '''W3C Trace Context''' — активирует связь между фронтендом и бэкендом путем распространения заголовков контекста трассировки.
* Создание отчетов вручную — формирование отчетов о веб-запросах из пользовательских сетевых конфигураций.
* Обогащение событий — добавление пользовательских свойств к событиям веб-запросов.

== Автоматизированная инструментация веб-запросов ==

ЕдиныйАгент для '''Android''' автоматически отслеживает веб-запросы, выполняемые с использованием встроенного API <code>HttpUrlConnection</code> '''Android''', и сохраняет их в виде событий в Хранилище данных. То же самое относится и к запросам, выполняемым с помощью широко используемой библиотеки <code>OkHttp</code>.

Каждое событие состоит из четко определенных полей типа «ключ-значение», как указано в Семантическом словаре для пользовательских событий.

Эти данные можно запрашивать напрямую в Хранилище данных с помощью '''DQL'''.

=== Что фиксируется автоматически ===

Подробный обзор сообщаемых данных и их структуры можно найти в Семантическом словаре. Следующий список содержит обзор данных, которые автоматически отслеживаются ЕдинымАгентом:

* '''URL''' запроса.
* Метод '''HTTP''' ('''GET''', '''POST''', '''PUT''', '''DELETE''' и т. д.).
* Код состояния ответа.
* Продолжительность запроса.
* Исключение (в случае неудачи запроса).

=== Поддерживаемые HTTP-фреймворки ===

Автоматизированные измерительные приборы работают со следующими системами:

* <code>HttpURLConnection</code>.
* <code>OkHttp</code>: только версии 3, 4 и 5.

Если ваша библиотека для обработки веб-запросов основана на одном из поддерживаемых фреймворков, внутренние классы библиотеки автоматически инструментируются. Например, '''Retrofit''' версии 2 основан на '''OkHttp''', поэтому все веб-запросы '''Retrofit''' автоматически инструментируются.

=== Ограничения ===

* Протоколы, отличные от '''HTTP''', не поддерживаются.
* Запросы от неподдерживаемых фреймворков необходимо обрабатывать вручную.
* Не рекомендуется использовать несколько инструментов мониторинга одновременно с включенной функцией инструментирования веб-запросов. Это может привести к проблемам совместимости, некорректным или недействительным отчетам о данных и потере информации мониторинга. Если вы все же решите это сделать, тщательно протестируйте инструменты, чтобы убедиться в их корректной совместной работе.

=== Отключить автоматическую настройку измерительных приборов ===

Чтобы отключить автоматическую инструментацию веб-запросов, установите флаг <code>webRequests.enabled</code> в значение <code>false</code> в блоке <code>astromkey</code> файла <code>configurations</code> вашего приложения <code>build.gradle</code>:

'''Groovy'''
<pre>
astromkey {
configurations {
sampleConfig {
webRequests.enabled false
}
}
}
</pre>

'''Kotlin'''
<pre>
configure<com.astromkey.tools.android.dsl.AstromkeyExtension> {
configurations {
create("sampleConfig") {
webRequests.enabled(false)
}
}
}
</pre>

=== Фильтрация веб-запросов по URL ===

Используйте свойство <code>urlFilters</code> внутри блока <code>webRequests</code>, чтобы предотвратить автоматическую инструментацию запросов, '''URL'''-адреса которых соответствуют одному или нескольким шаблонам регулярных выражений. Любой запрос, соответствующий хотя бы одному шаблону, исключается из автоматической инструментации и не будет отслеживаться.

Значение по умолчанию — пустой список, то есть по умолчанию никакие '''URL'''-адреса не отфильтровываются.

'''Groovy'''
<pre>
astromkey {
configurations {
sampleConfig {
webRequests {
urlFilters "example.com", "^http://", "\.test\."
}
}
}
}
</pre>

'''Kotlin'''
<pre>
configure<com.astromkey.tools.android.dsl.AstromkeyExtension> {
configurations {
create("sampleConfig") {
webRequests {
urlFilters("example.com", "^http://", "\.test\.")
}
}
}
}
</pre>

Каждый шаблон представляет собой регулярное выражение, сопоставляемое со всем '''URL'''-адресом.

== Контекст трассировки W3C для связи между фронтендом и бэкендом ==

SDK поддерживает добавление контекста трассировки '''W3C''', который позволяет связывать мобильные запросы с серверными службами. Подробнее см. раздел «Связывание фронтенда и бэкенда с использованием контекста трассировки W3C».

=== Автоматическое распространение заголовка контекста трассировки ===

В большинстве случаев вам не нужно самостоятельно устанавливать заголовки контекста трассировки '''W3C'''. Когда активна автоматическая инструментация веб-запросов, ЕдиныйАгент проверяет каждый исходящий запрос и решает, следует ли генерировать, сохранять или оставлять заголовки контекста трассировки без изменений, основываясь на обнаруженных данных.

==== Отсутствуют заголовки (типичный случай) ====

Если запрос не содержит заголовков трассировки, ЕдиныйАгент генерирует новый действительный запрос <code>traceparent</code> и добавляет соответствующую запись <code>tracestate</code> с контекстом, специфичным для Ключ-АСТРОМ.

Это позволяет установить корреляцию между мобильным запросом и трассировкой на стороне сервиса. См. раздел «Связь между фронтендом и бэкендом».

==== Существующий действительный <code>traceparent</code> заголовок ====

Если запрос уже содержит действительный идентификатор поставщика <code>traceparent</code>, ЕдиныйАгент сохраняет его и обновляет <code>tracestate</code>, добавляя информацию, специфичную для Ключ-АСТРОМ, без перезаписи существующих записей о поставщике.

Если общий размер данных <code>tracestate</code> станет слишком большим, ЕдиныйАгент может сократить количество записей, чтобы они оставались в пределах ограничений '''W3C'''. Данные Ключ-АСТРОМ сохраняются, когда это возможно.

=== Отключить автоматическое распространение контекста трассировки ===

Если вы не хотите, чтобы заголовки контекста трассировки '''W3C''' автоматически добавлялись к исходящим запросам, вы можете отключить эту функцию.

# Перейдите в раздел '''Ключевые показатели опыта''' > '''Обзор'''.
# Выберите '''Мобильные устройства''', чтобы просмотреть все мобильные версии сайта.
# Выберите интерфейс, который хотите настроить.
# На вкладке '''Настройки''' выберите '''Связь между фронтендом и бэкендом'''.
# Отключите функцию '''Включить связь между фронтендом и бэкендом через контекст трассировки W3C'''.

=== Передача заголовков контекста трассировки вручную ===

Если вы используете собственный сетевой стек, вы можете самостоятельно передавать заголовки '''W3C Trace Context''' и при этом сопоставлять запрос с распределенными трассировками Ключ-АСТРОМ.

Используйте <code>Astromkey.generateTraceContext(traceparent, tracestate)</code> для создания или обогащения контекста трассировки в соответствии с официальной спецификацией '''W3C Trace Context''':

* Если значение <code>traceparent</code> равно <code>null</code>, ЕдиныйАгент генерирует новый <code>traceparent</code> и соответствующий <code>tracestate</code> (включая информацию, специфичную для поставщика Ключ-АСТРОМ).
* Если <code>traceparent</code> присутствует и действителен, ЕдиныйАгент сохраняет его и дополняет <code>tracestate</code> информацией, специфичной для поставщика Ключ-АСТРОМ (без перезаписи существующих записей о поставщике).
* Если контекст трассировки создать не удаётся (например, из-за недопустимости <code>traceparent</code> или запрета на захват/тегирование), API возвращает значение <code>null</code>, и изменять заголовки запроса не следует.

Затем вы можете повторно использовать полученные данные <code>traceparent</code> для сопоставления событий веб-запроса, зарегистрированных вручную.

'''Kotlin'''
<pre>
val request = Request.Builder()
.url("https://api.example.com/data")
.build()

// Считываем существующие заголовки (если таковые имеются)
val existingTraceparent = request.header("traceparent")
val existingTracestate = request.header("tracestate")

// Генерация/обогащение контекста трассировки
val traceContext = Astromkey.generateTraceContext(existingTraceparent, existingTracestate)
val traceparentForReporting: String? = traceContext?.traceparent

if (traceContext != null) {
request = request.newBuilder()
.header("traceparent", traceContext.traceparent)
.header("tracestate", traceContext.tracestate)
.build()
}

// ...здесь выполните свой HTTP-запрос...
val requestData = HttpRequestEventData(request.url.toString(), request.method)
.withDuration(duration)
.withStatusCode(statusCode)

if (traceparentForReporting != null) {
requestData.withTraceparentHeader(traceparentForReporting)
}

Astromkey.sendHttpRequestEvent(requestData)
</pre>

'''Java'''
<pre>
Request request = new Request.Builder()
.url("https://api.example.com/data")
.build();

// Считываем существующие заголовки (если таковые имеются)
String existingTraceparent = request.header("traceparent");
String existingTracestate = request.header("tracestate");

// Генерация/обогащение контекста трассировки
TraceContext traceContext = Astromkey.generateTraceContext(existingTraceparent, existingTracestate);
String traceparentForReporting = traceContext != null ? traceContext.getTraceparent() : null;
if (traceContext != null) {
request = request.newBuilder()
.header("traceparent", traceContext.getTraceparent())
.header("tracestate", traceContext.getTracestate())
.build();
}

// ...здесь выполните свой HTTP-запрос...
HttpRequestEventData requestData = new HttpRequestEventData(request.url().toString(), request.method())
.withDuration(duration)
.withStatusCode(statusCode);

if (traceparentForReporting != null) {
requestData.withTraceparentHeader(traceparentForReporting);
}

Astromkey.sendHttpRequestEvent(requestData);
</pre>

== Сообщайте о веб-запросах вручную ==

Для сетевых библиотек, не охваченных автоматической инструментацией, вы можете вручную сообщать о веб-запросах, используя <code>HttpRequestEventData</code>.

=== Основное использование ===

'''Kotlin'''
<pre>
// Создание данных запроса с указанием URL-адреса и метода HTTP
val requestData = HttpRequestEventData("https://api.example.com/data", "GET")
.withDuration(250) // Длительность в миллисекундах
.withStatusCode(200) // Код состояния HTTP
.withBytesSent(128) // Отправлено байтов
.withBytesReceived(4096) // Получено байтов

// Отправка события веб-запроса
Astromkey.sendHttpRequestEvent(requestData)
</pre>

'''Java'''
<pre>
// Создание данных запроса с указанием URL-адреса и метода HTTP
HttpRequestEventData requestData = new HttpRequestEventData("https://api.example.com/data", "GET")
.withDuration(250) // Длительность в миллисекундах
.withStatusCode(200) // Код состояния HTTP
.withBytesSent(128) // Отправлено байтов
.withBytesReceived(4096); // Получено байтов

// Отправка события веб-запроса
Astromkey.sendHttpRequestEvent(requestData);
</pre>

=== Неудачный запрос ===

В случае неудачной попытки выполнения запроса, укажите информацию об ошибке:

'''Kotlin'''
<pre>
val requestData = HttpRequestEventData("https://api.example.com/data", "POST")
.withDuration(1500)
.withThrowable(exception)

Astromkey.sendHttpRequestEvent(requestData)
</pre>

'''Java'''
<pre>
HttpRequestEventData requestData = new HttpRequestEventData("https://api.example.com/data", "POST")
.withDuration(1500)
.withThrowable(exception);

Astromkey.sendHttpRequestEvent(requestData);
</pre>

=== Добавить пользовательские свойства ===

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

'''Kotlin'''
<pre>
val requestData = HttpRequestEventData(url, "POST")
.withDuration(300)
.withStatusCode(201)
.addEventProperty("event_properties.api_version", "v2")
.addEventProperty("event_properties.endpoint", "users")

Astromkey.sendHttpRequestEvent(requestData)
</pre>

'''Java'''
<pre>
HttpRequestEventData requestData = new HttpRequestEventData(url, "POST")
.withDuration(300)
.withStatusCode(201)
.addEventProperty("event_properties.api_version", "v2")
.addEventProperty("event_properties.endpoint", "users");

Astromkey.sendHttpRequestEvent(requestData);
</pre>

Ключи пользовательских свойств должны иметь префикс <code>event_properties.</code> — свойства без этого префикса будут отброшены.

== Обогащение событий (модификаторы) ==

Модификаторы событий позволяют обогащать события веб-запросов дополнительными данными перед их отправкой. Это полезно для добавления контекста из запроса или ответа, который не захватывается автоматически. ЕдиныйАгент для '''Android''' в настоящее время предоставляет эту функцию только для запросов, выполняемых с помощью фреймворка '''OkHttp'''. Кроме того, вы также можете добавить другие свойства события через <code>EventModifier</code>.

При одновременном использовании обоих подходов сначала выполняется первый шаг, <code>OkHttpEventModifier</code>, а затем второй <code>EventModifier</code>.

=== Добавить модификатор веб-запроса ===

Чтобы добавить модификатор веб-запроса, реализуйте интерфейс <code>OkHttpEventModifier</code> и передайте его методу <code>Astromkey.addHttpEventModifier</code>. Модификатор может получить доступ к объектам запроса и ответа для извлечения дополнительных данных и добавления их к событию. В случае исключения модификатор может получить доступ к объектам запроса и исключения для извлечения дополнительных данных и добавления их к событию.

Из-за особенностей обработки тела ответа '''OkHttp''', вам необходимо использовать <code>peekBody()</code> вместо <code>body()</code>, чтобы избежать потребления потока ответа. Таким образом, тело ответа останется доступным для последующего использования в вашей обычной системе обработки ответов.

Если вы используете <code>body()</code> модификатор для доступа к телу ответа, при последующей попытке повторного его обработки вы получите исключение.

'''Kotlin'''
<pre>
val modifier: OkHttpEventModifier = object : OkHttpEventModifier {
override fun modifyEvent(request: Request, response: Response): JSONObject {
val event = JSONObject()

// Доступ к подробностям ответа
val serverTiming = response.header("Server-Timing")
if (serverTiming != null) {
event.put("event_properties.server_timing", serverTiming)
}

// Просматривайте только тело ответа, не обрабатывайте его.
val body = response.peekBody(1000)
event.put("event_properties.body", body.toString())

return event
}

override fun modifyEvent(request: Request, throwable: Throwable): JSONObject {
val event = JSONObject()

// Добавьте пользовательские заголовки или информацию запроса в качестве свойств
val customHeader = request.header("X-Custom-Header")
if (customHeader != null) {
event.put("event_properties.custom_header", customHeader)
}
return event
}
}

Astromkey.addHttpEventModifier(modifier)
</pre>

'''Java'''
<pre>
OkHttpEventModifier modifier = new OkHttpEventModifier() {
@Override
public JSONObject modifyEvent(Request request, Response response) {
JSONObject event = new JSONObject();

// Доступ к подробностям ответа
String serverTiming = response.header("Server-Timing");
if (serverTiming != null) {
event.put("event_properties.server_timing", serverTiming);
}

// Просматривайте только тело ответа, не обрабатывайте его.
ResponseBody body = response.peekBody(1000);
event.put("event_properties.body", body.toString());

return event;
}

@Override
public JSONObject modifyEvent(Request request, Throwable throwable) {
JSONObject event = new JSONObject();

// Добавьте пользовательские заголовки или информацию запроса в качестве свойств
String customHeader = request.header("X-Custom-Header");
if (customHeader != null) {
event.put("event_properties.custom_header", customHeader);
}
return event;
}
};

Astromkey.addHttpEventModifier(modifier);
</pre>

=== Доступные свойства контекста ===

<code>OkHttpEventModifier</code> предоставляет методы обратного вызова для двух сценариев:

* <code>modifyEvent(Request request, Response response)</code>
* <code>modifyEvent(Request request, Throwable throwable)</code>

Первый метод вызывается после завершения запроса и получения ответа. Обратите внимание, что ответ может быть неуспешным, например, если сервер возвращает код состояния 4xx или 5xx.

Второй метод вызывается в случае, если запрос завершился с исключением.

{| class="wikitable"
|-
! Метод обратного вызова !! Параметр !! Тип !! Описание
|-
| <code>modifyEvent(request, response)</code> || <code>request</code> || <code>okhttp3.Request</code> || Исходный объект запроса '''OkHttp'''
|-
| || <code>response</code> || <code>okhttp3.Response</code> || Объект ответа '''OkHttp''' (используйте <code>peekBody()</code> для чтения тела ответа)
|-
| <code>modifyEvent(request, throwable)</code> || <code>request</code> || <code>okhttp3.Request</code> || Исходный объект запроса '''OkHttp'''
|-
| || <code>throwable</code> || <code>Throwable</code> || Исключение, которое привело к сбою запроса.
|}

=== Удалить модификатор ===

Когда модификатор больше не нужен, удалите его, используя ссылку на модификатор:

'''Kotlin'''
<pre>
Astromkey.removeEventModifier(modifier)
</pre>

'''Java'''
<pre>
Astromkey.removeEventModifier(modifier);
</pre>

=== Фильтрация запросов ===

Верните значение <code>null</code> из модификатора, чтобы предотвратить отправку события:

'''Kotlin'''
<pre>
val filterModifier: OkHttpEventModifier = object : OkHttpEventModifier {
override fun modifyEvent(request: Request, response: Response?): JSONObject? {
if (request.url.toString().contains("analytics.example.com")) {
return null // вернуть null для события drop
} else {
return JSONObject()
}
}

override fun modifyEvent(request: Request?, throwable: Throwable?): JSONObject? {
if (throwable is IOException) {
val event = JSONObject()
// Информация о выбросах добавляется автоматически
return event
} else {
// Возвращает null, чтобы отменить событие
return null
}
}
}

Astromkey.addHttpEventModifier(filterModifier)
</pre>

'''Java'''
<pre>
OkHttpEventModifier filterModifier = new OkHttpEventModifier() {
@Override
public JSONObject modifyEvent(Request request, Response response) {
if (request.url().toString().contains("analytics.example.com")) {
return null; // вернуть null для события drop
} else {
return new JSONObject();
}
}

@Override
public JSONObject modifyEvent(Request request, Throwable throwable) {
if (throwable instanceof IOException) {
JSONObject event = new JSONObject();
// Информация о выбросах добавляется автоматически
return event;
} else {
// Возвращает null, чтобы отменить событие
return null;
}
}
};

Astromkey.addHttpEventModifier(filterModifier);
</pre>

Мониторинг производительности веб-запросов - История изменений