Пакет trace
Обзор
Пакет trace содержит средства для генерации трассировок выполнения программ для отладчика выполнения Go.
Отслеживание действий среды выполнения
Трассировка выполнения захватывает широкий спектр событий выполнения, таких как создание/блокировка/разблокировка горутин, вход/выход/блокировка системных вызовов, события, связанные с сборкой мусора, изменения размера кучи, запуск/остановка процессора и т. д. Когда включено профилирование ЦП, отладчик выполнения старается включить и эти образцы. Для большинства событий фиксируется точное отметка времени с точностью до наносекунд и стек-трейс. Сгенерированную трассировку можно интерпретировать с помощью `go tool trace`.
Поддержка трассировки тестов и бенчмарков, созданных с помощью стандартного пакета тестирования, интегрирована в `go test`. Например, следующая команда выполняет тесты в текущей директории и записывает файл трассировки (trace.out).
go test -trace=trace.out
Этот пакет runtime/trace предоставляет API для добавления эквивалентной поддержки трассировки в автономную программу. Обратитесь к примеру, который демонстрирует использование этого API для включения трассировки.
Также существует стандартный HTTP-интерфейс для трассировки данных. Добавление следующей строки установит обработчик по адресу /debug/pprof/trace для загрузки живой трассировки:
import _ "net/http/pprof"
Дополнительные сведения о всех точках входа отладки, установленных этим импортом, см. в пакете net/http/pprof.
Аннотации пользователя
Пакет trace предоставляет API для аннотаций пользователя, которые можно использовать для регистрации интересных событий во время выполнения.
Существует три типа пользовательских аннотаций: сообщения журнала, области и задачи.
Log отправляет отметку времени сообщения в трассировку выполнения вместе с дополнительной информацией, такой как категория сообщения и какая горутина вызвала Log. Отладчик выполнения предоставляет интерфейсы для фильтрации и группировки горутин с использованием категории журнала и сообщения, предоставленного в Log.
Область предназначена для регистрации временного интервала во время выполнения горутины. По определению, область начинается и заканчивается в одной и той же горутине. Области могут быть вложены, чтобы представлять подинтервалы. Например, следующий код записывает четыре области в трассировку выполнения, чтобы отслеживать продолжительность последовательных шагов в процессе приготовления капучино.
trace.WithRegion(ctx, "makeCappuccino", func() {
// orderID allows to identify a specific order
// among many cappuccino order region records.
trace.Log(ctx, "orderID", orderID)
trace.WithRegion(ctx, "steamMilk", steamMilk)
trace.WithRegion(ctx, "extractCoffee", extractCoffee)
trace.WithRegion(ctx, "mixMilkCoffee", mixMilkCoffee)
})
Задача — это компонент более высокого уровня, который помогает в отслеживании логических операций, таких как запрос RPC, запрос HTTP или интересная локальная операция, для которой могут потребоваться несколько горутин, работающих совместно. Поскольку задачи могут включать несколько горутин, они отслеживаются с помощью объекта context.Context. NewTask создает новую задачу и встраивает её в возвращаемый объект context.Context. Сообщения журнала и области прикрепляются к задаче, если таковая имеется, в контексте, переданном в Log и WithRegion.
Например, предположим, что мы решили взбить молоко, извлечь кофе и смешать молоко с кофе в отдельных горутинах. С задачей инструмент трассировки может определить горутины, участвующие в конкретном заказе капучино.
ctx, task := trace.NewTask(ctx, "makeCappuccino")
trace.Log(ctx, "orderID", orderID)
milk := make(chan bool)
espresso := make(chan bool)
go func() {
trace.WithRegion(ctx, "steamMilk", steamMilk)
milk <- true
}()
go func() {
trace.WithRegion(ctx, "extractCoffee", extractCoffee)
espresso <- true
}()
go func() {
defer task.End() // When assemble is done, the order is complete.
<-espresso
<-milk
trace.WithRegion(ctx, "mixMilkCoffee", mixMilkCoffee)
}()
Инструмент трассировки вычисляет задержку задачи, измеряя время между созданием задачи и завершением задачи, и предоставляет распределения задержек для каждого типа задачи, обнаруженного в трассировке.
Пример
Пример демонстрирует использование пакета trace для отслеживания выполнения программы Go. Вывод трассировки будет записан в файл trace.out
Код:
package trace_test
import (
"fmt"
"log"
"os"
"runtime/trace"
)
// Example demonstrates the use of the trace package to trace
// the execution of a Go program. The trace output will be
// written to the file trace.out
func Example() {
f, err := os.Create("trace.out")
if err != nil {
log.Fatalf("failed to create trace output file: %v", err)
}
defer func() {
if err := f.Close(); err != nil {
log.Fatalf("failed to close trace file: %v", err)
}
}()
if err := trace.Start(f); err != nil {
log.Fatalf("failed to start trace: %v", err)
}
defer trace.Stop()
// your program here
RunMyProgram()
}
func RunMyProgram() {
fmt.Printf("this function will be traced")
}
Индекс
Примеры
Файлы пакета
annotation.go trace.go
func IsEnabled 1.11
func IsEnabled() bool
IsEnabled сообщает, включена ли трассировка. Информация является рекомендательной. Статус трассировки может измениться к моменту возврата этой функции.
func Log 1.11
func Log(ctx context.Context, category, message string)
Log записывает одноразовое событие с заданной категорией и сообщением. Категория может быть пустой, и API предполагает, что в системе имеется лишь несколько уникальных категорий.
func Logf 1.11
func Logf(ctx context.Context, category, format string, args ...any)
Logf похож на Log, но значение форматируется с помощью указанного формата.
func Start 1.5
func Start(w io.Writer) error
Start включает трассировку для текущей программы. Во время трассировки трассировка буферизуется и записывается в w. Start возвращает ошибку, если трассировка уже включена.
func Stop 1.5
func Stop()
Stop останавливает текущую трассировку, если она существует. Stop возвращает только после завершения всех записей для трассировки.
func WithRegion 1.11
func WithRegion(ctx context.Context, regionType string, fn func())
WithRegion запускает область, связанную с вызывающей горутиной, выполняет fn, а затем завершает область. Если контекст содержит задачу, область связывается с задачей. В противном случае область прикрепляется к фоновой задаче.
regionType используется для классификации областей, поэтому должно быть только несколько уникальных типов областей.
тип Region 1.11
Region — это область кода, интервал выполнения которого отслеживается.
type Region struct {
// contains filtered or unexported fields
}
func StartRegion 1.11
func StartRegion(ctx context.Context, regionType string) *Region
StartRegion запускает область и возвращает её. Метод Region.End возвращаемой области Region должен вызываться из той же горутины, где область была запущена. Внутри каждой горутины области должны быть вложены. То есть области, запущенные после этой области, должны быть завершены до того, как эта область может быть завершена. Рекомендуемое использование
defer trace.StartRegion(ctx, "myTracedRegion").End()
func (*Region) End 1.11
func (r *Region) End()
End помечает конец области отслеживаемого кода.
тип Task 1.11
Task — это тип данных для отслеживания определенной пользователем логической операции.
type Task struct {
// contains filtered or unexported fields
}
func NewTask 1.11
func NewTask(pctx context.Context, taskType string) (ctx context.Context, task *Task)
NewTask создаёт экземпляр задачи с типом taskType и возвращает его вместе с контекстом, который содержит задачу. Если входной контекст содержит задачу, новая задача является её подзадачей.
taskType используется для классификации экземпляров задач. Инструменты анализа, такие как отладчик выполнения Go, могут предполагать, что в системе имеется ограниченное число уникальных типов задач.
Возвращаемый Task's метод Task.End используется для пометки завершения задачи. Инструмент трассировки измеряет задержку задачи, как время между созданием задачи и вызовом метода End, и предоставляет распределение задержек по каждому типу задачи. Если метод End вызывается несколько раз, используется только первый вызов при измерении задержки.
ctx, task := trace.NewTask(ctx, "awesomeTask")
trace.WithRegion(ctx, "preparation", prepWork)
// preparation of the task
go func() { // continue processing the task in a separate goroutine.
defer task.End()
trace.WithRegion(ctx, "remainingWork", remainingWork)
}()
func (*Task) End 1.11
func (t *Task) End()
End помечает конец операции, представленной Task.
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/runtime/trace/
