tracing

package
v3.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 13, 2024 License: MIT Imports: 17 Imported by: 6

README

Tracing

Documentation

Overview

Package tracing help simulator users to trace what is happening in the simulation.

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	HookPosTaskStart = &sim.HookPos{Name: "HookPosTaskStart"}
	HookPosTaskStep  = &sim.HookPos{Name: "HookPosTaskStep"}
	HookPosTaskEnd   = &sim.HookPos{Name: "HookPosTaskEnd"}
)

A list of hook poses for the hooks to apply to

Functions

func AddTaskStep

func AddTaskStep(
	id string,
	domain NamedHookable,
	what string,
)

AddTaskStep marks that a milestone has been reached when processing a task.

func CollectTrace

func CollectTrace(domain NamedHookable, tracer Tracer)

CollectTrace let the tracer to collect trace from a domain

func EndTask

func EndTask(
	id string,
	domain NamedHookable,
)

EndTask notifies the hooks about the end of a task.

func MsgIDAtReceiver

func MsgIDAtReceiver(msg sim.Msg, domain NamedHookable) string

MsgIDAtReceiver generates a standard ID for the message task at the message receiver.

func StartTask

func StartTask(
	id string,
	parentID string,
	domain NamedHookable,
	kind string,
	what string,
	detail interface{},
)

StartTask notifies the hooks that hook to the domain about the start of a task.

func StartTaskWithSpecificLocation

func StartTaskWithSpecificLocation(
	id string,
	parentID string,
	domain NamedHookable,
	kind string,
	what string,
	location string,
	detail interface{},
)

StartTaskWithSpecificLocation notifies the hooks that hook to the domain about the start of a task, and is able to customize `where` field of a task, especially for network tracing.

func TraceReqComplete

func TraceReqComplete(
	msg sim.Msg,
	domain NamedHookable,
)

TraceReqComplete terminates the message handling task.

func TraceReqFinalize

func TraceReqFinalize(
	msg sim.Msg,
	domain NamedHookable,
)

TraceReqFinalize terminates the message task. This function should be called when the sender receives the response.

func TraceReqInitiate

func TraceReqInitiate(
	msg sim.Msg,
	domain NamedHookable,
	taskParentID string,
)

TraceReqInitiate generatse a new task. The new task has Type="req_out", What=[the type name of the message]. This function is to be called by the sender of the message.

func TraceReqReceive

func TraceReqReceive(
	msg sim.Msg,
	domain NamedHookable,
)

TraceReqReceive generates a new task for the message handling. The kind of the task is always "req_in".

Types

type AverageTimeTracer

type AverageTimeTracer struct {
	// contains filtered or unexported fields
}

AverageTimeTracer can collect the total time of executing a certain type of task. If the execution of two tasks overlaps, this tracer will simply add the two task processing time together.

func NewAverageTimeTracer

func NewAverageTimeTracer(
	timeTeller sim.TimeTeller,
	filter TaskFilter,
) *AverageTimeTracer

NewAverageTimeTracer creates a new AverageTimeTracer

func (*AverageTimeTracer) AverageTime

func (t *AverageTimeTracer) AverageTime() sim.VTimeInSec

AverageTime returns the total time has been spent on a certain type of tasks.

func (*AverageTimeTracer) EndTask

func (t *AverageTimeTracer) EndTask(task Task)

EndTask records the end of the task

func (*AverageTimeTracer) StartTask

func (t *AverageTimeTracer) StartTask(task Task)

StartTask records the task start time

func (*AverageTimeTracer) StepTask

func (t *AverageTimeTracer) StepTask(_ Task)

StepTask does nothing

func (*AverageTimeTracer) TotalCount

func (t *AverageTimeTracer) TotalCount() uint64

TotalCount returns the total number of tasks.

type BusyTimeTracer

type BusyTimeTracer struct {
	// contains filtered or unexported fields
}

BusyTimeTracer traces the that a domain is processing a kind of task. If the task processing time overlaps, this tracer only consider one instance of the overlapped time.

func NewBusyTimeTracer

func NewBusyTimeTracer(
	timeTeller sim.TimeTeller,
	filter TaskFilter,
) *BusyTimeTracer

NewBusyTimeTracer creates a new BusyTimeTracer

func (*BusyTimeTracer) BusyTime

func (t *BusyTimeTracer) BusyTime() sim.VTimeInSec

BusyTime returns the total time has been spent on a certain type of tasks.

func (*BusyTimeTracer) EndTask

func (t *BusyTimeTracer) EndTask(task Task)

EndTask records the end of the task

func (*BusyTimeTracer) StartTask

func (t *BusyTimeTracer) StartTask(task Task)

StartTask records the task start time

func (*BusyTimeTracer) StepTask

func (t *BusyTimeTracer) StepTask(_ Task)

StepTask does nothing

func (*BusyTimeTracer) TerminateAllTasks

func (t *BusyTimeTracer) TerminateAllTasks(now sim.VTimeInSec)

TerminateAllTasks will mark all the tasks as completed.

type CSVTraceReader

type CSVTraceReader struct {
	// contains filtered or unexported fields
}

CSVTraceReader is a task tracer that can read tasks from a CSV file.

func NewCSVTraceReader

func NewCSVTraceReader(path string) *CSVTraceReader

NewCSVTraceReader creates a new CSVTraceReader.

func (*CSVTraceReader) ListComponents

func (r *CSVTraceReader) ListComponents() []string

ListComponents queries the components that have tasks.

func (*CSVTraceReader) ListTasks

func (r *CSVTraceReader) ListTasks(query TaskQuery) []Task

ListTasks queries tasks .

type CSVTraceWriter

type CSVTraceWriter struct {
	// contains filtered or unexported fields
}

CSVTraceWriter is a task tracer that can store the tasks into a CSV file.

func NewCSVTraceWriter

func NewCSVTraceWriter(path string) *CSVTraceWriter

NewCSVTraceWriter creates a new CSVTracerBackend.

func (*CSVTraceWriter) Flush

func (t *CSVTraceWriter) Flush()

Flush flushes the tasks to the CSV file.

func (*CSVTraceWriter) Init

func (t *CSVTraceWriter) Init()

Init creates the tracing csv file. If the file already exists, it will be overwritten.

func (*CSVTraceWriter) Write

func (t *CSVTraceWriter) Write(task Task)

Write writes a task to the CSV file.

type DBTracer

type DBTracer struct {
	// contains filtered or unexported fields
}

DBTracer is a tracer that can store tasks into a database. DBTracers can connect with different backends so that the tasks can be stored in different types of databases (e.g., CSV files, SQL databases, etc.)

func NewDBTracer

func NewDBTracer(
	timeTeller sim.TimeTeller,
	backend TracerBackend,
) *DBTracer

NewDBTracer creates a new DBTracer.

func (*DBTracer) EndTask

func (t *DBTracer) EndTask(task Task)

EndTask marks the end of a task.

func (*DBTracer) SetTimeRange

func (t *DBTracer) SetTimeRange(startTime, endTime sim.VTimeInSec)

SetTimeRange sets the time range of the tracer.

func (*DBTracer) StartTask

func (t *DBTracer) StartTask(task Task)

StartTask marks the start of a task.

func (*DBTracer) StepTask

func (t *DBTracer) StepTask(_ Task)

StepTask marks a step of a task.

func (*DBTracer) Terminate

func (t *DBTracer) Terminate()

Terminate terminates the tracer.

type MySQLTraceReader

type MySQLTraceReader struct {
	// contains filtered or unexported fields
}

MySQLTraceReader can read tasks from a MySQL database.

func NewMySQLTraceReader

func NewMySQLTraceReader(dbName string) *MySQLTraceReader

NewMySQLTraceReader returns a new MySQLTraceReader. The Init function must be called before using the reader.

func (*MySQLTraceReader) Init

func (r *MySQLTraceReader) Init()

Init establishes a connection to MySQL.

func (*MySQLTraceReader) ListComponents

func (r *MySQLTraceReader) ListComponents() []string

ListComponents returns a list of components in the trace.

func (*MySQLTraceReader) ListTasks

func (r *MySQLTraceReader) ListTasks(query TaskQuery) []Task

ListTasks returns a list of tasks in the trace according to the given query.

type MySQLTraceWriter

type MySQLTraceWriter struct {
	// contains filtered or unexported fields
}

MySQLTraceWriter is a task tracer that can store the tasks into a MySQL database.

func NewMySQLTraceWriter

func NewMySQLTraceWriter() *MySQLTraceWriter

NewMySQLTraceWriter returns a new MySQLWriter. The init function must be called before using the backend.

func (*MySQLTraceWriter) Flush

func (t *MySQLTraceWriter) Flush()

Flush writes all the tasks in the buffer into the database.

func (*MySQLTraceWriter) Init

func (t *MySQLTraceWriter) Init()

Init establishes a connection to MySQL and creates a database.

func (*MySQLTraceWriter) Write

func (t *MySQLTraceWriter) Write(task Task)

Write writes the task into the database.

type NamedHookable

type NamedHookable interface {
	sim.Named
	sim.Hookable
	InvokeHook(sim.HookCtx)
}

NamedHookable represent something both have a name and can be hooked

type SQLiteTraceReader

type SQLiteTraceReader struct {
	*sql.DB
	// contains filtered or unexported fields
}

SQLiteTraceReader is a reader that reads trace data from a SQLite database.

func NewSQLiteTraceReader

func NewSQLiteTraceReader(filename string) *SQLiteTraceReader

NewSQLiteTraceReader creates a new SQLiteTraceReader.

func (*SQLiteTraceReader) Init

func (r *SQLiteTraceReader) Init()

Init establishes a connection to the database.

func (*SQLiteTraceReader) ListComponents

func (r *SQLiteTraceReader) ListComponents() []string

ListComponents returns a list of components in the trace.

func (*SQLiteTraceReader) ListTasks

func (r *SQLiteTraceReader) ListTasks(query TaskQuery) []Task

ListTasks returns a list of tasks in the trace according to the given query.

type SQLiteTraceWriter

type SQLiteTraceWriter struct {
	*sql.DB
	// contains filtered or unexported fields
}

SQLiteTraceWriter is a writer that writes trace data to a SQLite database.

func NewSQLiteTraceWriter

func NewSQLiteTraceWriter(path string) *SQLiteTraceWriter

NewSQLiteTraceWriter creates a new SQLiteWriter.

func (*SQLiteTraceWriter) Flush

func (t *SQLiteTraceWriter) Flush()

Flush writes all the buffered tasks to the database.

func (*SQLiteTraceWriter) Init

func (t *SQLiteTraceWriter) Init()

Init establishes a connection to the database.

func (*SQLiteTraceWriter) Write

func (t *SQLiteTraceWriter) Write(task Task)

Write writes a task to the database.

type StepCountTracer

type StepCountTracer struct {
	// contains filtered or unexported fields
}

StepCountTracer can collect the total time of a certain step is triggerred.

func NewStepCountTracer

func NewStepCountTracer(filter TaskFilter) *StepCountTracer

NewStepCountTracer creates a new StepCountTracer

func (*StepCountTracer) EndTask

func (t *StepCountTracer) EndTask(task Task)

EndTask records the end of the task

func (*StepCountTracer) GetStepCount

func (t *StepCountTracer) GetStepCount(stepName string) uint64

GetStepCount returns the number of steps that is recorded with a certain step name.

func (*StepCountTracer) GetStepNames

func (t *StepCountTracer) GetStepNames() []string

GetStepNames returns all the step names collected.

func (*StepCountTracer) GetTaskCount

func (t *StepCountTracer) GetTaskCount(stepName string) uint64

GetTaskCount returns the number of tasks that is recorded to have a certain step with a given name.

func (*StepCountTracer) StartTask

func (t *StepCountTracer) StartTask(task Task)

StartTask records the task start time

func (*StepCountTracer) StepTask

func (t *StepCountTracer) StepTask(task Task)

StepTask does nothing

type Task

type Task struct {
	ID         string         `json:"id"`
	ParentID   string         `json:"parent_id"`
	Kind       string         `json:"kind"`
	What       string         `json:"what"`
	Where      string         `json:"where"`
	StartTime  sim.VTimeInSec `json:"start_time"`
	EndTime    sim.VTimeInSec `json:"end_time"`
	Steps      []TaskStep     `json:"steps"`
	Detail     interface{}    `json:"-"`
	ParentTask *Task          `json:"-"`
}

A Task is a task

type TaskFilter

type TaskFilter func(t Task) bool

TaskFilter is a function that can filter interesting tasks. If this function returns true, the task is considered useful.

type TaskQuery

type TaskQuery struct {
	// Use ID to select a single task by its ID.
	ID string

	// Use ParentID to select all the tasks that are children of a task.
	ParentID string

	// Use Kind to select all the tasks that are of a kind.
	Kind string

	// Use Where to select all the tasks that are executed at a location.
	Where string

	// Enable time range selection.
	EnableTimeRange bool

	// Use StartTime to select tasks that overlaps with the given task range.
	StartTime, EndTime float64

	// EnableParentTask will also query the parent task of the selected tasks.
	EnableParentTask bool
}

TaskQuery is used to define the tasks to be queried. Not all the field has to be set. If the fields are empty, the criteria is ignored.

type TaskStep

type TaskStep struct {
	Time sim.VTimeInSec `json:"time"`
	What string         `json:"what"`
}

A TaskStep represents a milestone in the processing of task

type TotalTimeTracer

type TotalTimeTracer struct {
	// contains filtered or unexported fields
}

TotalTimeTracer can collect the total time of executing a certain type of task. If the execution of two tasks overlaps, this tracer will simply add the two task processing time together.

func NewTotalTimeTracer

func NewTotalTimeTracer(
	timeTeller sim.TimeTeller,
	filter TaskFilter,
) *TotalTimeTracer

NewTotalTimeTracer creates a new TotalTimeTracer

func (*TotalTimeTracer) EndTask

func (t *TotalTimeTracer) EndTask(task Task)

EndTask records the end of the task

func (*TotalTimeTracer) StartTask

func (t *TotalTimeTracer) StartTask(task Task)

StartTask records the task start time

func (*TotalTimeTracer) StepTask

func (t *TotalTimeTracer) StepTask(_ Task)

StepTask does nothing

func (*TotalTimeTracer) TotalTime

func (t *TotalTimeTracer) TotalTime() sim.VTimeInSec

TotalTime returns the total time has been spent on a certain type of tasks.

type TraceReader

type TraceReader interface {
	// ListComponents returns all the locations used in the trace.
	ListComponents() []string

	// ListTasks queries tasks .
	ListTasks(query TaskQuery) []Task
}

TraceReader can parse a trace file.

type Tracer

type Tracer interface {
	StartTask(task Task)
	StepTask(task Task)
	EndTask(task Task)
}

A Tracer can collect task traces

Example

Example for how to use standard tracers

package main

import (
	"fmt"

	"github.com/sarchlab/akita/v3/sim"
	"github.com/sarchlab/akita/v3/tracing"
)

type SampleTimeTeller struct {
	time sim.VTimeInSec
}

func (t *SampleTimeTeller) CurrentTime() sim.VTimeInSec {
	return t.time
}

type SampleDomain struct {
	*sim.HookableBase
	timeTeller sim.TimeTeller
	taskIDs    []int
	nextID     int
}

func (d *SampleDomain) Name() string {
	return "sample domain"
}

func (d *SampleDomain) Start() {
	tracing.StartTask(
		fmt.Sprintf("%d", d.nextID),
		"",
		d,
		"sampleTaskKind",
		"something",
		nil,
	)
	d.taskIDs = append(d.taskIDs, d.nextID)

	d.nextID++
}

func (d *SampleDomain) End() {
	tracing.EndTask(
		fmt.Sprintf("%d", d.taskIDs[0]),
		d,
	)
	d.taskIDs = d.taskIDs[1:]
}

// Example for how to use standard tracers
func main() {
	timeTeller := &SampleTimeTeller{}
	domain := &SampleDomain{
		HookableBase: sim.NewHookableBase(),
		timeTeller:   timeTeller,
	}

	filter := func(t tracing.Task) bool {
		return t.Kind == "sampleTaskKind"
	}

	totalTimeTracer := tracing.NewTotalTimeTracer(timeTeller, filter)
	busyTimeTracer := tracing.NewBusyTimeTracer(timeTeller, filter)
	avgTimeTracer := tracing.NewAverageTimeTracer(timeTeller, filter)
	tracing.CollectTrace(domain, totalTimeTracer)
	tracing.CollectTrace(domain, busyTimeTracer)
	tracing.CollectTrace(domain, avgTimeTracer)

	timeTeller.time = 1
	domain.Start()
	timeTeller.time = 1.5
	domain.Start()
	timeTeller.time = 2
	domain.End()
	timeTeller.time = 3
	domain.End()

	fmt.Println(totalTimeTracer.TotalTime())
	fmt.Println(busyTimeTracer.BusyTime())
	fmt.Println(avgTimeTracer.AverageTime())

}
Output:

2.5
2
1.25

type TracerBackend

type TracerBackend interface {
	// Write writes a task to the storage.
	Write(task Task)

	// Flush flushes the tasks to the storage, in case if the backend buffers
	// the tasks.
	Flush()
}

TracerBackend is a backend that can store tasks.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL