fxt

package module
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Jun 29, 2023 License: Apache-2.0 Imports: 5 Imported by: 0

README

fxt

Fuschia Trace Format (fxt) is a file format for storing trace / counter events in a compact binary format. These trace files can then be viewed with an interactive web-based UI: https://ui.perfetto.dev/

FXT was created by Google for use in their experimental operating system Fuschia. It's very well documented, simple to write, and can express lots of different types of events and data.

There are lots of other tracing file formats out there.

  • chrome://tracing
    • chrome://tracing is extremely simple and you just need a Chrome browser to view it.
    • But it is json-based. So the file can quickly explode in size for large traces.
  • Perfetto
    • Perfetto is the successor to chrome://tracing and has many improvements.
    • It's protobuf-based, so it's much smaller / compact.
    • However, protobuf can be a pain to use. You generally want to use the .proto file to generate a generator/parser, but that's a lot of extra steps / maintenance
  • Speedscope
    • Speedscope is a web-based trace visualizer like Perfetto UI
    • It can view quite a few different formats
    • In addition, it has its own json-based trace format
    • Which, unfortunately, has the same issues as chrome://tracing
  • Many many more

This repo is a library for creating FXT files

Documentation

Overview

Package fxt is a library for creating [Fuschia Trace Format](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md) files.

FXT is a file format for storing trace / counter events in a compact binary format. These trace files can then be viewed with an interactive web-based UI: https://ui.perfetto.dev/

FXT was created by Google for use in their experimental operating system [Fuschia](https://fuchsia.dev/fuchsia-src). It's very well documented, simple to write, and can express lots of different types of events and data.

There are lots of other tracing file formats out there.

* [chrome://tracing](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview)

  • chrome://tracing is extremely simple and you just need a Chrome browser to view it.
  • But it is json-based. So the file can quickly explode in size for large traces.

* [Perfetto](https://perfetto.dev/)

  • Perfetto is the successor to chrome://tracing and has many improvements.
  • It's protobuf-based, so it's much smaller / compact.
  • However, protobuf can be a pain to use. You generally want to use the .proto file to generate a generator/parser, but that's a lot of extra steps / maintenance

* [Speedscope](https://github.com/jlfwong/speedscope/wiki/Importing-from-custom-sources#speedscopes-file-format)

  • Speedscope is a web-based trace visualizer like Perfetto UI
  • It can view quite a few different formats
  • In addition, it has its own json-based trace format
  • Which, unfortunately, has the same issues as chrome://tracing

* Many many more

FXT is a simple format to write, and it's binary. So it's a bit of the best of both worlds

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BlobType added in v0.3.0 

type BlobType int
const (
	BlobTypeData       BlobType = 1
	BlobTypeLastBranch BlobType = 2
	BlobTypePerfetto   BlobType = 3
)

type KernelObjectID 

type KernelObjectID uint64

KernelObjectID is a unique identifier for a kernel object for example, a process or thread

type Thread 

type Thread struct {
	ProcessId KernelObjectID
	ThreadId  KernelObjectID
}

Thread uniquely identifies a thread within a process

type Writer 

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

Writer is a struct for writing an FXT file. It has methods for adding records to the file

func NewWriter 

func NewWriter(filePath string) (*Writer, error)

NewWriter creates a new FXT file at `filePath` and initializes it with the FXT header It returns a Writer instance which can be used to add records to the file

func (*Writer) AddAsyncBeginEvent added in v0.2.0 

func (w *Writer) AddAsyncBeginEvent(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64, asyncCorrelationId uint64) error

AddAsyncBeginEvent adds an async begin event record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#async-begin-event

If strings and/or process/thread IDs aren't already in the string / thread tables respectively, string and thread records will be automatically created. Any future events will use the table references.

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#string-record https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#thread-record

func (*Writer) AddAsyncBeginEventWithArgs added in v0.3.0 

func (w *Writer) AddAsyncBeginEventWithArgs(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64, asyncCorrelationId uint64, arguments map[string]interface{}) error

AddAsyncBeginEventWithArgs is the same as AddAsyncBeginEvent, but it allows you to additionally include arguments within the event record

func (*Writer) AddAsyncEndEvent added in v0.2.0 

func (w *Writer) AddAsyncEndEvent(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64, asyncCorrelationId uint64) error

AddAsyncEndEvent adds an async end event record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#async-end-event

If strings and/or process/thread IDs aren't already in the string / thread tables respectively, string and thread records will be automatically created. Any future events will use the table references.

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#string-record https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#thread-record

func (*Writer) AddAsyncEndEventWithArgs added in v0.3.0 

func (w *Writer) AddAsyncEndEventWithArgs(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64, asyncCorrelationId uint64, arguments map[string]interface{}) error

AddAsyncEndEventWithArgs is the same as AddAsyncEndEvent, but it allows you to additionally include arguments within the event record

func (*Writer) AddAsyncInstantEvent added in v0.2.0 

func (w *Writer) AddAsyncInstantEvent(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64, asyncCorrelationId uint64) error

AddAsyncInstantEvent adds an async instant event record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#async-instant-event

If strings and/or process/thread IDs aren't already in the string / thread tables respectively, string and thread records will be automatically created. Any future events will use the table references.

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#string-record https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#thread-record

func (*Writer) AddAsyncInstantEventWithArgs added in v0.3.0 

func (w *Writer) AddAsyncInstantEventWithArgs(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64, asyncCorrelationId uint64, arguments map[string]interface{}) error

AddAsyncInstantEventWithArgs is the same as AddAsyncInstantEvent, but it allows you to additionally include arguments within the event record

func (*Writer) AddBlobRecord added in v0.3.0 

func (w *Writer) AddBlobRecord(name string, data []byte, blobType BlobType) error

AddBlobRecord adds a blob record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#blob-record

func (*Writer) AddContextSwitchRecord added in v0.3.0 

func (w *Writer) AddContextSwitchRecord(cpuNumber uint16, outgoingThreadState uint8, outgoingThreadId KernelObjectID, incomingThreadId KernelObjectID, timestamp uint64) error

AddContextSwitchRecord adds a context switch scheduling record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#context-switch-record-scheduling-event-record-type-1

func (*Writer) AddContextSwitchRecordWithArgs added in v0.3.0 

func (w *Writer) AddContextSwitchRecordWithArgs(cpuNumber uint16, outgoingThreadState uint8, outgoingThreadId KernelObjectID, incomingThreadId KernelObjectID, timestamp uint64, arguments map[string]interface{}) error

AddContextSwitchRecordWithArgs is the same as AddContextSwitchRecord, but it allows you to additionally include arguments within the scheduling record

func (*Writer) AddCounterEvent added in v0.2.0 

func (w *Writer) AddCounterEvent(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64, arguments map[string]interface{}, counterId uint64) error

AddCounterEvent adds a counter event record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#counter-event

If strings and/or process/thread IDs aren't already in the string / thread tables respectively, string and thread records will be automatically created. Any future events will use the table references.

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#string-record https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#thread-record

func (*Writer) AddDurationBeginEvent added in v0.2.0 

func (w *Writer) AddDurationBeginEvent(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64) error

AddDurationBeginEvent adds a duration begin event record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#duration-begin-event

If strings and/or process/thread IDs aren't already in the string / thread tables respectively, string and thread records will be automatically created. Any future events will use the table references.

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#string-record https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#thread-record

func (*Writer) AddDurationBeginEventWithArgs added in v0.3.0 

func (w *Writer) AddDurationBeginEventWithArgs(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64, arguments map[string]interface{}) error

AddDurationBeginEventWithArgs is the same as AddDurationBeginEvent, but it allows you to additionally include arguments within the event record

func (*Writer) AddDurationCompleteEvent added in v0.2.0 

func (w *Writer) AddDurationCompleteEvent(category string, name string, processId KernelObjectID, threadId KernelObjectID, beginTimestamp uint64, endTimestamp uint64) error

AddDurationCompleteEvent adds a duration complete event record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#duration-complete-event

If strings and/or process/thread IDs aren't already in the string / thread tables respectively, string and thread records will be automatically created. Any future events will use the table references.

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#string-record https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#thread-record

func (*Writer) AddDurationCompleteEventWithArgs added in v0.3.0 

func (w *Writer) AddDurationCompleteEventWithArgs(category string, name string, processId KernelObjectID, threadId KernelObjectID, beginTimestamp uint64, endTimestamp uint64, arguments map[string]interface{}) error

AddDurationCompleteEventWithArgs is the same as AddDurationCompleteEvent, but it allows you to additionally include arguments within the event record

func (*Writer) AddDurationEndEvent added in v0.2.0 

func (w *Writer) AddDurationEndEvent(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64) error

AddDurationEndEvent adds a duration end event record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#duration-end-event

If strings and/or process/thread IDs aren't already in the string / thread tables respectively, string and thread records will be automatically created. Any future events will use the table references.

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#string-record https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#thread-record

func (*Writer) AddDurationEndEventWithArgs added in v0.3.0 

func (w *Writer) AddDurationEndEventWithArgs(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64, arguments map[string]interface{}) error

AddDurationEndEventWithArgs is the same as AddDurationEndEvent, but it allows you to additionally include arguments within the event record

func (*Writer) AddFlowBeginEvent added in v0.2.0 

func (w *Writer) AddFlowBeginEvent(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64, flowCorrelationId uint64) error

AddFlowBeginEvent adds an flow begin event record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#flow-begin-event

If strings and/or process/thread IDs aren't already in the string / thread tables respectively, string and thread records will be automatically created. Any future events will use the table references.

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#string-record https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#thread-record

func (*Writer) AddFlowBeginEventWithArgs added in v0.3.0 

func (w *Writer) AddFlowBeginEventWithArgs(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64, flowCorrelationId uint64, arguments map[string]interface{}) error

AddFlowBeginEventWithArgs is the same as AddFlowBeginEvent, but it allows you to additionally include arguments within the event record

func (*Writer) AddFlowEndEvent added in v0.2.0 

func (w *Writer) AddFlowEndEvent(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64, flowCorrelationId uint64) error

AddFlowEndEvent adds an flow end event record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#flow-end-event

If strings and/or process/thread IDs aren't already in the string / thread tables respectively, string and thread records will be automatically created. Any future events will use the table references.

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#string-record https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#thread-record

func (*Writer) AddFlowEndEventWithArgs added in v0.3.0 

func (w *Writer) AddFlowEndEventWithArgs(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64, flowCorrelationId uint64, arguments map[string]interface{}) error

AddFlowEndEventWithArgs is the same as AddFlowEndEvent, but it allows you to additionally include arguments within the event record

func (*Writer) AddFlowStepEvent added in v0.2.0 

func (w *Writer) AddFlowStepEvent(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64, flowCorrelationId uint64) error

AddFlowStepEvent adds an flow step event record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#flow-step-event

If strings and/or process/thread IDs aren't already in the string / thread tables respectively, string and thread records will be automatically created. Any future events will use the table references.

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#string-record https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#thread-record

func (*Writer) AddFlowStepEventWithArgs added in v0.3.0 

func (w *Writer) AddFlowStepEventWithArgs(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64, flowCorrelationId uint64, arguments map[string]interface{}) error

AddFlowStepEventWithArgs is the same as AddFlowStepEvent, but it allows you to additionally include arguments within the event record

func (*Writer) AddInitializationRecord 

func (w *Writer) AddInitializationRecord(numTicksPerSecond uint64) error

AddInitializationRecord adds an initialization record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#initialization-record

This specifies the number of ticks per second for all event records after this

func (*Writer) AddInstantEvent added in v0.2.0 

func (w *Writer) AddInstantEvent(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64) error

AddInstantEvent adds an instant event record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#instant-event

If strings and/or process/thread IDs aren't already in the string / thread tables respectively, string and thread records will be automatically created. Any future events will use the table references.

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#string-record https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#thread-record

func (*Writer) AddInstantEventWithArgs added in v0.3.0 

func (w *Writer) AddInstantEventWithArgs(category string, name string, processId KernelObjectID, threadId KernelObjectID, timestamp uint64, arguments map[string]interface{}) error

AddInstantEventWithArgs is the same as AddInstantEvent, but it allows you to additionally include arguments within the event record

func (*Writer) AddProviderEventRecord 

func (w *Writer) AddProviderEventRecord(providerId uint32, eventType providerEventType) error

AddProviderEventRecord adds a provider event metadata record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#provider-event-metadata

func (*Writer) AddProviderInfoRecord 

func (w *Writer) AddProviderInfoRecord(providerId uint32, providerName string) error

AddProviderInfoRecord adds a provider info metadata record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#provider-info-metadata

func (*Writer) AddProviderSectionRecord 

func (w *Writer) AddProviderSectionRecord(providerId uint32) error

AddProviderSectionRecord adds a provider section metadata record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#provider-section-metadata

func (*Writer) AddThreadWakeupRecord added in v0.3.0 

func (w *Writer) AddThreadWakeupRecord(cpuNumber uint16, wakingThreadId KernelObjectID, timestamp uint64) error

AddContextSwitchRecord adds a thread wakeup scheduling record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#thread-wakeup-record-scheduling-event-record-type-2

func (*Writer) AddThreadWakeupRecordWithArgs added in v0.3.0 

func (w *Writer) AddThreadWakeupRecordWithArgs(cpuNumber uint16, wakingThreadId KernelObjectID, timestamp uint64, arguments map[string]interface{}) error

AddThreadWakeupRecordWithArgs is the same as AddThreadWakeupRecord, but it allows you to additionally include arguments within the scheduling record

func (*Writer) AddUserspaceObjectRecord added in v0.3.0 

func (w *Writer) AddUserspaceObjectRecord(name string, processId KernelObjectID, pointerValue uintptr, arguments map[string]interface{}) error

AddUserspaceObjectRecord adds a userspace object record to the file

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#userspace-object-record

func (*Writer) Close 

func (w *Writer) Close() error

Close closes the underlying file

func (*Writer) SetProcessName added in v0.2.0 

func (w *Writer) SetProcessName(processId KernelObjectID, name string) error

SetProcessName adds a kernel object record to give a human-readable name to a process ID

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#kernel-object-record

func (*Writer) SetThreadName added in v0.2.0 

func (w *Writer) SetThreadName(processId KernelObjectID, threadId KernelObjectID, name string) error

SetThreadName adds a kernel object record

https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/reference/tracing/trace-format.md#kernel-object-record

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.