18. Кодировки Eventlog

В этом разделе описываются кодировки событий, испускаемых в журнал событий GHC. Эти события могут включать информацию о событиях планирования потоков, статистике сборки мусора, информации о профилировании, событиях отслеживания, определённых пользователем.

Этот раздел предназначен для разработчиков инструментов, которые используют эти события. GHC поставляется с файлом заголовков на C (EventlogFormat.h) содержащим символические имена идентификаторов типов событий, описанных в этом файле.

18.1. Формат журнала событий

Формат журнала спроектирован для расширяемости: старые инструменты должны иметь возможность парсить (но не обязательно понимать все) новые версии формата, а новые инструменты смогут понимать старые файлы журнала.

• Формат независим от порядка байтов: все значения представлены в порядке big-endian.

• Формат расширяемый:

  • Заголовок описывает каждый тип события и его длину. Инструменты, которые не распознают определённый тип события, могут пропустить эти события.
  • В спецификации типа события есть место для дополнительной информации, которую могут игнорировать старые инструменты.
  • К событиям можно добавить дополнительную информацию, но существующие поля изменять нельзя. Инструменты должны игнорировать дополнительные поля в конце записи события.

Поток журнала событий начинается с заголовка, описывающего типы событий, присутствующие в файле. Заголовок следует за самими записями событий, каждая из которых состоит из 64-битного временного отметки

log : EVENT_HEADER_BEGIN
      EventType*
      EVENT_HEADER_END
      EVENT_DATA_BEGIN
      Event*
      EVENT_DATA_END

EventType :
      EVENT_ET_BEGIN
      Word16         -- unique identifier for this event
      Int16          -- >=0  size of the event in bytes (minus the header)
                     -- -1   variable size
      Word32         -- length of the next field in bytes
      Word8*         -- string describing the event
      Word32         -- length of the next field in bytes
      Word8*         -- extra info (for future extensions)
      EVENT_ET_END

Event :
      Word16         -- event_type
      Word64         -- time (nanosecs)
      [Word16]       -- length of the rest (for variable-sized events only)
      ... extra event-specific info ...

Существует два класса типов событий:

• Фиксированной длины: Все записи событий фиксированного размера имеют одинаковую длину, указанную в заголовке журнала событий.
• Переменной длины: Каждая запись события включает поле длины.

18.2. Диагностика системы выполнения

• ThreadId ~ Word32
• CapNo ~ Word16
• CapSetId ~ Word32

18.2.1. Наборы возможностей

TODO

18.2.2. Информация об окружении

Эти события обычно генерируются во время запуска программы и описывают среду, в которой запускается программа.

RTS_IDENTIFIER

Тег

29

Длина

переменная

Поле CapSetId

Набор возможностей

Поле String

Имя и версия системы выполнения.

Описывает имя и версию системы выполнения, ответственной за указанный набор возможностей.

PROGRAM_ARGS

Тег

30

Длина

переменная

Поле CapSetId

Набор возможностей

Поле [String]

Аргументы командной строки, переданные программе

Описывает командную строку, используемую для запуска программы.

PROGRAM_ENV

Тег

31

Длина

переменная

Поле CapSetId

Набор возможностей

Поле [String]

Наборы пар имя/значение переменных окружения. (TODO: кодировка?)

Описывает переменные окружения, присутствующие в среде программы.

18.2.3. События потоков и планирования

CREATE_THREAD

Тег

0

Длина

фиксированная

Поле ThreadId

идентификатор потока

Помечает создание потока Haskell.

RUN_THREAD

Тег

1

Длина

фиксированная

Поле ThreadId

идентификатор потока

Указанный поток начал выполняться.

STOP_THREAD

Тег

2

Длина

фиксированная

Поле ThreadId

идентификатор потока

Поле Word16

состояние

• 1: HeapOverflow
• 2: StackOverflow
• 3: ThreadYielding
• 4: ThreadBlocked
• 5: ThreadFinished
• 6: ForeignCall
• 7: BlockedOnMVar
• 8: BlockedOnBlackHole
• 9: BlockedOnRead
• 10: BlockedOnWrite
• 11: BlockedOnDelay
• 12: BlockedOnSTM
• 13: BlockedOnDoProc
• 16: BlockedOnMsgThrowTo

Поле ThreadId

идентификатор потока, на котором происходит блокировка (только для некоторых значений статуса)

Указанный поток остановился по причине, указанной в status.

THREAD_RUNNABLE

Тег

3

Длина

фиксированная

Поле ThreadId

идентификатор потока

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

MIGRATE_THREAD

Тег

4

Длина

фиксированная

Поле ThreadId

идентификатор потока

Поле CapNo

возможность

Указанный поток был перемещён в новую возможность.

THREAD_WAKEUP

Тег

8

Длина

фиксированная

Поле ThreadId

идентификатор потока

Поле CapNo

другая возможность

Указанный поток был разбужен в другой возможности.

THREAD_LABEL

Тег

44

Длина

фиксированная

Поле ThreadId

идентификатор потока

Поле String

метка

Указанному потоку была присвоена метка (например, с помощью Control.Concurrent.setThreadLabel).

18.2.4. События сборщика мусора

GC_START

Тег

9

Длина

фиксированная

Запущен цикл сборки мусора.

GC_END

Тег

10

Длина

фиксированная

Цикл сборки мусора завершён.

REQUEST_SEQ_GC

Тег

11

Длина

фиксированная

Запрошена последовательная сборка мусора с помощью возможности.

REQUEST_PAR_GC

Тег

12

Длина

фиксированная

Запрошена параллельная сборка мусора с помощью возможности.

GC_IDLE

Тег

20

Длина

фиксированная

Запущена сборка мусора в режиме ожидания.

GC_WORK

Тег

21

Длина

фиксированная

Помечает начало конкуретного сканирования.

GC_DONE

Тег

22

Длина

фиксированная

Помечает окончание конкуретного сканирования.

GC_STATS_GHC

Тэг

53

Длина

фиксированная

Поле CapSetId

набор возможностей кучи

Поле Word16

поколение сборки мусора

Поле Word64

скопированные байты

Поле Word64

найденные байты излишка

Поле Word64

TODO

Поле Word64

количество параллельных потоков сборки мусора

Поле Word64

максимальное количество байтов, скопированных одним потоком сборщика мусора

Поле Word64

общее количество байтов, скопированных всеми потоками сборщиков мусора

Сообщает различную информацию о конфигурации кучи. Обычно генерируется во время инициализации RTS.

GC_GLOBAL_SYNC

Тэг

54

Длина

фиксированная

TODO

18.2.5. События и статистика кучи

HEAP_ALLOCATED

Тэг

49

Длина

фиксированная

Поле CapSetId

набор возможностей кучи

Поле Word64

выделенные байты

Новый фрагмент кучи был выделен указанным набором возможностей.

HEAP_SIZE

Тэг

50

Длина

фиксированная

Поле CapSetId

набор возможностей кучи

Поле Word64

размер кучи в байтах

Сообщает о размере кучи.

HEAP_LIVE

Тэг

51

Длина

фиксированная

Поле CapSetId

набор возможностей кучи

Поле Word64

размер живой кучи в байтах

Сообщает о размере живой кучи.

HEAP_INFO_GHC

Тэг

52

Длина

фиксированная

Поле CapSetId

набор возможностей кучи

Поле Word16

количество поколений сборки мусора

Поле Word64

максимальный размер кучи

Поле Word64

размер области выделения

Поле Word64

размер MBlock

Поле Word64

размер блока

Сообщает различную информацию о конфигурации кучи. Обычно генерируется во время инициализации RTS.

18.2.6. События искры

CREATE_SPARK_THREAD

Тэг

15

Длина

фиксированная

Создан поток для выполнения оценки искры.

SPARK_COUNTERS

Тэг

34

Длина

фиксированная

Периодическое сообщение о различных статистиках оценки искры.

SPARK_CREATE

Тэг

35

Длина

фиксированная

Искра добавлена в пул искр.

SPARK_DUD

Тэг

36

Длина

фиксированная

TODO

SPARK_OVERFLOW

Тэг

37

Длина

фиксированная

TODO

SPARK_RUN

Тэг

38

Длина

фиксированная

Начато выполнение оценки искры.

SPARK_STEAL

Тэг

39

Длина

фиксированная

Поле Word16

возможность, из которой была украдена искра

Искра украдена из другой возможности для оценки.

SPARK_FIZZLE

Тэг

40

Длина

фиксированная

Искра была удалена сборкой мусора до оценки.

SPARK_GC

Тэг

41

Длина

фиксированная

Неоценённая искра была удалена сборкой мусора.

18.2.7. События возможностей

CAP_CREATE

Тэг

45

Длина

фиксированная

Поле CapNo

номер возможности

Возможность запущена.

CAP_DELETE

Тэг

46

Длина

фиксированная

Возможность удалена.

CAP_DISABLE

Тэг

47

Длина

фиксированная

Возможность отключена.

CAP_ENABLE

Тэг

48

Длина

фиксированная

Возможность включена.

18.2.8. События задач

TASK_CREATE

Тэг

55

Длина

фиксированная

Поле TaskId

идентификатор задачи

Поле CapNo

номер возможности

Поле ThreadId

TODO

Помечает создание задачи.

TASK_MIGRATE

Тэг

56

Длина

фиксированная

Поле TaskId

идентификатор задачи

Поле CapNo

старая возможность

Поле CapNo

новая возможность

Помечает перемещение задачи в новую возможность.

18.2.9. События отслеживания

LOG_MSG

Тэг

16

Длина

переменная

Поле String

сообщение

Сообщение журнала из системы выполнения.

BLOCK_MARKER

Тэг

18

Длина

переменная

Поле Word32

размер

Поле Word64

время окончания в наносекундах

Поле String

имя метки

TODO

USER_MSG

Тэг

19

Длина

переменная

Поле String

сообщение

Пользовательское сообщение журнала (например, из Control.Concurrent.traceEvent).

USER_MARKER

Тэг

58

Длина

переменная

Строка поля

имя маркера

Маркер пользователя (из Debug.Trace.traceMarker).

18.3. Вывод журнала событий профилировщика кучи

Профилировщик кучи может генерировать вывод в журнал событий GHC, позволяющий коррелировать образцы с другими событиями журнала событий на протяжении жизненного цикла программы.

В этом разделе описывается структура этих событий. Тип String ниже определяется как строка UTF-8 с завершением нулем.

18.3.1. Типы событий метаданных

18.3.1.1. Начало потока образцов

Единственное событие фиксированной ширины, выпущенное во время запуска программы, описывающее следующие образцы.

HEAP_PROF_BEGIN

Тэг

160

Длина

переменная

Поле Word8

идентификатор профиля

Поле Word64

период выборки в наносекундах

Поле Word32

тип разбиения образца. Один из,

• HEAP_PROF_BREAKDOWN_COST_CENTER (вывод из -hc)
• HEAP_PROF_BREAKDOWN_CLOSURE_DESCR (вывод из -hd)
• HEAP_PROF_BREAKDOWN_RETAINER (вывод из -hr)
• HEAP_PROF_BREAKDOWN_MODULE (вывод из -hm)
• HEAP_PROF_BREAKDOWN_TYPE_DESCR (вывод из -hy)
• HEAP_PROF_BREAKDOWN_BIOGRAPHY (вывод из -hb)
• HEAP_PROF_BREAKDOWN_CLOSURE_TYPE (вывод из -hT)

Поле String

фильтр модулей

Поле String

фильтр описания замыканий

Поле String

фильтр описания типов

Поле String

фильтр центра затрат

Поле String

фильтр стека центра затрат

Поле String

фильтр ретента

Поле String

фильтр биографии

18.3.1.2. Определения центров затрат

Пакет переменной длины, создаваемый один раз для каждого центра затрат,

HEAP_PROF_COST_CENTRE

Тэг

161

Длина

фиксированная

Поле Word32

номер центра затрат

Поле String

метка

Поле String

модуль

Поле String

местоположение источника

Поле Word8

флаги:

• бит 0: является ли центр затрат CAF?

18.3.1.3. Типы событий образцов

Образец (состоящий из списка классов разбиения, например, центров затрат и размеров резидентности в куче) должен быть закодирован в теле одного или нескольких событий.

Обычно мы помечаем начало нового образца событием EVENT_HEAP_PROF_SAMPLE_BEGIN,

HEAP_PROF_SAMPLE_BEGIN

Длина

фиксированная

Поле Word64

номер образца

Помечает начало образца профилирования кучи.

Образцы биографического профилирования начинаются с события EVENT_HEAP_BIO_PROF_SAMPLE_BEGIN. Эти события также включают отметку времени, указывающую, когда был получен образец. Это связано с тем, как работает режим биографического профилирования, в котором все эти образцы будут появляться в конце журнала событий. Вы можете использовать отметку времени для переупорядочения образцов относительно других событий.

HEAP_BIO_PROF_SAMPLE_BEGIN

Тэг

166

Длина

фиксированная

Поле Word64

номер образца

Поле Word64

отметка времени журнала событий в нс

Следует перепись резидентности в куче. Поскольку события могут иметь длину не более 2^16^ байтов, для одного образца может потребоваться разбиение на несколько событий EVENT_HEAP_PROF_SAMPLE. Точный формат записей переписи определяется типом разбиения.

В конце периода выборки генерируется событие EVENT_HEAP_PROF_SAMPLE_END. Это полезно для правильной демаркации периода выборки и для записи общего времени, затраченного на профилирование.

HEAP_PROF_SAMPLE_END

Тэг

165

Длина

фиксированная

Поле Word64

номер образца

Помечает конец образца профилирования кучи.

18.3.1.4. Разбиение по центрам затрат

Пакет переменной длины, кодирующий образец профилирования кучи, разбитый по

• центру затрат (-hc)

HEAP_PROF_SAMPLE_COST_CENTRE

Тэг

163

Длина

переменная

Поле Word8

идентификатор профиля

Поле Word64

резидентность в куче в байтах

Поле Word8

глубина стека

Поле Word32[]

стек центра затрат, начиная с внутреннего (номера центров затрат)

18.3.1.5. Разбиение по строкам

Событие переменной длины, кодирующее образец кучи, разбитый по

• описанию типа (-hy)
• описанию замыкания (-hd)
• модулю (-hm)

HEAP_PROF_SAMPLE_STRING

Тэг

164

Длина

переменная

Поле Word8

идентификатор профиля

Поле Word64

резидентность в куче в байтах

Поле String

описание типа или замыкания или имя модуля

18.4. Вывод журнала событий тайм-профилировщика

Режим временного профилирования, включенный с помощью -p, также выводит события образцов в журнал событий. В начале профилирования интервал такта выводится в журнал событий, а затем при каждом такте выводится текущий стек центра затрат. В совокупности это позволяет пользователю построить приблизительный ход выполнения своей программы.

18.4.1. Событие начала профилирования

PROF_BEGIN

Тэг

168

Длина

фиксированная

Поле Word64

интервал такта в наносекундах

Помечает начало временного профиля.

18.4.2. Событие образца профилирования

Пакет переменной длины, кодирующий образец профилирования.

PROF_SAMPLE_COST_CENTRE

Тэг

167

Длина

переменная

Поле Word32

возможность

Поле Word64

текущий такт профилирования

Поле Word8

глубина стека

Поле Word32[]

стек центра затрат, начиная с внутреннего (номера центров затрат)

18.5. Событие образца биографического профилирования

Пакет переменной длины, кодирующий образец профилирования.

BIO_PROF_SAMPLE_BEGIN

Тэг

166

TODO

18.6. Вывод событий неперемещаемого сборщика мусора

Эти события отмечают различные стадии жизненного цикла non-moving collection. Они включаются набором событий +RTS -lg.

CONC_MARK_BEGIN

Тег

200

Длина

фиксированная

Отмечает начало маркировки конкурирующим сборщиком мусора.

CONC_MARK_END

Тег

201

Длина

фиксированная

Отмечает конец маркировки конкурирующим сборщиком мусора.

CONC_SYNC_BEGIN

Тег

202

Длина

фиксированная

Отмечает начало фазы синхронизации после маркировки конкурирующего сборщика мусора.

CONC_SYNC_END

Тег

203

Длина

фиксированная

Отмечает конец фазы синхронизации после маркировки конкурирующего сборщика мусора.

CONC_SWEEP_BEGIN

Тег

204

Длина

фиксированная

Отмечает начало фазы очистки конкурирующего сборщика мусора.

CONC_SWEEP_END

Тег

205

Длина

фиксированная

Отмечает конец фазы очистки конкурирующего сборщика мусора.

CONC_UPD_REM_SET_FLUSH

Тег

206

Длина

фиксированная

Отмечает сброс накопителя локального набора замеченных обновлений.

18.6.1. Перепись неподвижного куска памяти

События переписи неподвижного куска памяти (включаются набором событий +RTS -ln) предназначены для анализа фрагментации неподвижного куска памяти.

NONMOVING_HEAP_CENSUS

Тег

207

Длина

фиксированная

Поле Word8

логарифм по основанию 2 от blk_sz.

Поле Word32

количество активных сегментов.

Поле Word32

количество заполненных сегментов.

Поле Word32

количество активных блоков.

Описывает заполненность подкуска памяти blk_sz.