gizlang/profile
what a program says to its profile. Any Gizlang program profiles itself when GIZLANG_PROFILE names a file (giz profile run -- PROGRAM); giz profile then reads it. The runtime records tasks, I/O, children and samples by itself; this module adds what only the program knows: the phases of its run, the spans of its requests and steps, instants, counters and the owners of its memory. A span is the running task's until it ends, and the tasks it spawns meanwhile start in it, so the profile's causal graph ties their I/O and CPU to it. When the program is not profiled, each call costs one test.
import * as Profile from "gizlang/profile";Types
Span
type Span = { id: i64; parent: i64; start: i64; name: string; }A span of work: its id, the span it runs in, its start (now) and its name. Id 0 when nothing records.
id:i64parent:i64start:i64name:string
Functions
recording
function recording(): boolWhether this process records a profile now.
Effects: io, alloc.
kernels
function kernels(): boolWhether this process records each kernel of a GPU graph by itself (GIZLANG_PROFILE_GPU=kernels): the GPU work runs unrecorded, kernel by kernel, slower but timed.
Effects: fail, io, alloc.
now
function now(): i64The profile's clock: CLOCK_MONOTONIC nanoseconds.
Effects: io, alloc.
newId
function newId(): i64A new id of a span or an operation, unique among this process's and naming it; 0 when nothing records.
Effects: io, alloc.
current
function current(): i64The running task's span, 0 for none.
Effects: io, alloc.
phase
function phase(name: string): voidStarts the phase NAME of this program in its profile (a page's "load", then its "layout"): the part of the run that follows, until the next phase. The report gives each its wall and CPU time, faults and memory.
Effects: fail, io, alloc.
label
function label(at: u64, n: i64, name: string): voidNames the N bytes mapped at AT as NAME's in the owners of the profile's memory (a VM's heap, a model's weights).
Effects: fail, io, alloc.
begin
function begin(name: string): SpanStarts the span NAME in the running one: the running task's span until it ends.
Effects: io, alloc.
join
function join(name: string, parent: string): SpanStarts the span NAME as the child of PARENT, a span of another process (a traceparent's 16 hex digits): the profile joins the two processes' graphs there.
Effects: fail, io, alloc.
mark
function mark(name: string): voidThe instant NAME.
Effects: fail, io, alloc.
guest
function guest(vm: u64, links: i64, depth: i64, room: i64, exits: i64, callee: i64, info: i64, kind: i64, doubles: u64): u64Makes the VM whose state is at VM (0: none) the guest stack of this thread's samples, read by its layout: the state's words at LINKS, DEPTH, ROOM and EXITS, a frame's function at CALLEE from its frame pointer, a function's info at INFO, its KIND, and values from DOUBLES up as numbers. Gives the VM it replaces.
Effects: fail, io, alloc.
guestName
function guestName(info: u64, name: string): voidNames the guest function whose info is at INFO: samples show NAME where they hold it.
Effects: fail, io, alloc.
guestCode
function guestCode(at: u64, size: i64, name: string): voidNames the SIZE bytes of compiled code at AT as the guest function NAME's: samples in that code show jit NAME.
Effects: fail, io, alloc.
counter
function counter(name: string, value: i64): voidThe value of the counter NAME now (queue depth, bytes held, tokens a second).
Effects: fail, io, alloc.
event
function event(kind: i64, start: i64, end: i64, span: i64, parent: i64, resource: i64, bytes: i64, status: i64, a: i64, b: i64, text: string): voidAn event of KIND with every field (gizhw/gpu's kernels and copies, on the GPU's clock mapped to this one).
Effects: fail, io, alloc.
traceSpan
function traceSpan(): stringThe 16 lowercase hex digits of the running span, as a traceparent's parent id; "" when nothing records or no span runs (a traceparent's span is never all zeros).
Effects: fail, io, alloc.
traceId
function traceId(): stringThe 32 hex digits of this process's trace id, for a traceparent this process starts.
Effects: fail, io, alloc.
Methods
Span.end
function Span.end(self: Span): voidEnds the span: its parent runs again.
Effects: fail, io, alloc.
Span.finish
function Span.finish(self: Span, bytes: i64, status: i64, resource: i64): voidEnds the span with what it did: the BYTES it moved, its STATUS (0 ok) and the RESOURCE it used (a descriptor, a table, a model slot).
Effects: fail, io, alloc.
Constants
SPAN
const SPAN: i64 = Wire.PROFILE_SPANThe kind of a span event: a named piece of work with a start and an end. The runtime numbers every kind.
MARK
const MARK: i64 = Wire.PROFILE_MARKThe kind of a mark: an instant with a name.
COUNTER
const COUNTER: i64 = Wire.PROFILE_COUNTERThe kind of a counter: a named value at an instant.
LINK
const LINK: i64 = Wire.PROFILE_LINKThe kind of a link: one span waits for or follows another.
GPU_KERNEL
const GPU_KERNEL: i64 = Wire.PROFILE_GPU_KERNELThe kind of a GPU kernel: its run on the device, on the CPU clock.
GUEST
const GUEST: i64 = Wire.PROFILE_GUESTThe kind of a VM's function (gizvm): the info that samples name it by, and its name, file and line.
GUEST_CODE
const GUEST_CODE: i64 = Wire.PROFILE_GUEST_CODEThe kind of a VM's compiled code (gizvm): its address, size and the name of its function.
GPU_COPY
const GPU_COPY: i64 = Wire.PROFILE_GPU_COPYThe kind of a GPU copy: bytes between host and device, or on the device.
GPU_GRAPH
const GPU_GRAPH: i64 = Wire.PROFILE_GPU_GRAPHThe kind of a GPU graph replay.
GPU_MEMORY
const GPU_MEMORY: i64 = Wire.PROFILE_GPU_MEMORYThe kind of a GPU allocation or release.
GPU_SYNC
const GPU_SYNC: i64 = Wire.PROFILE_GPU_SYNCThe kind of a wait for the GPU.
DEVICE_GIVEN
const DEVICE_GIVEN: i64 = Wire.PROFILE_DEVICE_GIVENA device buffer given, whose stack the runtime adds, and dropped (gizhw/gpu): resource is its address.
DEVICE_FREED
const DEVICE_FREED: i64 = Wire.PROFILE_DEVICE_FREEDA device buffer given before (DEVICE_GIVEN) and now freed: resource is its address.
GPU_LAUNCH
const GPU_LAUNCH: i64 = Wire.PROFILE_GPU_LAUNCHA kernel or replay launched, whose stack the runtime adds: span is the id its GPU_KERNEL or GPU_GRAPH event takes.
GPU_WORK
const GPU_WORK: i64 = Wire.PROFILE_GPU_WORKA kernel's work (Gpu.work), beside its GPU_KERNEL event: a = its operations, b = the bytes it moves, text its name.