GizStack
View .mdOpen in ChatGPTOpen in Claude

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.

gizlang
import * as Profile from "gizlang/profile";

Types

Span

gizlang
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: i64
  • parent: i64
  • start: i64
  • name: string

Functions

recording

gizlang
function recording(): bool

Whether this process records a profile now.

Effects: io, alloc.

kernels

gizlang
function kernels(): bool

Whether 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

gizlang
function now(): i64

The profile's clock: CLOCK_MONOTONIC nanoseconds.

Effects: io, alloc.

newId

gizlang
function newId(): i64

A new id of a span or an operation, unique among this process's and naming it; 0 when nothing records.

Effects: io, alloc.

current

gizlang
function current(): i64

The running task's span, 0 for none.

Effects: io, alloc.

phase

gizlang
function phase(name: string): void

Starts 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

gizlang
function label(at: u64, n: i64, name: string): void

Names 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

gizlang
function begin(name: string): Span

Starts the span NAME in the running one: the running task's span until it ends.

Effects: io, alloc.

join

gizlang
function join(name: string, parent: string): Span

Starts 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

gizlang
function mark(name: string): void

The instant NAME.

Effects: fail, io, alloc.

guest

gizlang
function guest(vm: u64, links: i64, depth: i64, room: i64, exits: i64, callee: i64, info: i64, kind: i64, doubles: u64): u64

Makes 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

gizlang
function guestName(info: u64, name: string): void

Names the guest function whose info is at INFO: samples show NAME where they hold it.

Effects: fail, io, alloc.

guestCode

gizlang
function guestCode(at: u64, size: i64, name: string): void

Names 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

gizlang
function counter(name: string, value: i64): void

The value of the counter NAME now (queue depth, bytes held, tokens a second).

Effects: fail, io, alloc.

event

gizlang
function event(kind: i64, start: i64, end: i64, span: i64, parent: i64, resource: i64, bytes: i64, status: i64, a: i64, b: i64, text: string): void

An 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

gizlang
function traceSpan(): string

The 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

gizlang
function traceId(): string

The 32 hex digits of this process's trace id, for a traceparent this process starts.

Effects: fail, io, alloc.

Methods

Span.end

gizlang
function Span.end(self: Span): void

Ends the span: its parent runs again.

Effects: fail, io, alloc.

Span.finish

gizlang
function Span.finish(self: Span, bytes: i64, status: i64, resource: i64): void

Ends 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

gizlang
const SPAN: i64 = Wire.PROFILE_SPAN

The kind of a span event: a named piece of work with a start and an end. The runtime numbers every kind.

MARK

gizlang
const MARK: i64 = Wire.PROFILE_MARK

The kind of a mark: an instant with a name.

COUNTER

gizlang
const COUNTER: i64 = Wire.PROFILE_COUNTER

The kind of a counter: a named value at an instant.

gizlang
const LINK: i64 = Wire.PROFILE_LINK

The kind of a link: one span waits for or follows another.

GPU_KERNEL

gizlang
const GPU_KERNEL: i64 = Wire.PROFILE_GPU_KERNEL

The kind of a GPU kernel: its run on the device, on the CPU clock.

GUEST

gizlang
const GUEST: i64 = Wire.PROFILE_GUEST

The kind of a VM's function (gizvm): the info that samples name it by, and its name, file and line.

GUEST_CODE

gizlang
const GUEST_CODE: i64 = Wire.PROFILE_GUEST_CODE

The kind of a VM's compiled code (gizvm): its address, size and the name of its function.

GPU_COPY

gizlang
const GPU_COPY: i64 = Wire.PROFILE_GPU_COPY

The kind of a GPU copy: bytes between host and device, or on the device.

GPU_GRAPH

gizlang
const GPU_GRAPH: i64 = Wire.PROFILE_GPU_GRAPH

The kind of a GPU graph replay.

GPU_MEMORY

gizlang
const GPU_MEMORY: i64 = Wire.PROFILE_GPU_MEMORY

The kind of a GPU allocation or release.

GPU_SYNC

gizlang
const GPU_SYNC: i64 = Wire.PROFILE_GPU_SYNC

The kind of a wait for the GPU.

DEVICE_GIVEN

gizlang
const DEVICE_GIVEN: i64 = Wire.PROFILE_DEVICE_GIVEN

A device buffer given, whose stack the runtime adds, and dropped (gizhw/gpu): resource is its address.

DEVICE_FREED

gizlang
const DEVICE_FREED: i64 = Wire.PROFILE_DEVICE_FREED

A device buffer given before (DEVICE_GIVEN) and now freed: resource is its address.

GPU_LAUNCH

gizlang
const GPU_LAUNCH: i64 = Wire.PROFILE_GPU_LAUNCH

A kernel or replay launched, whose stack the runtime adds: span is the id its GPU_KERNEL or GPU_GRAPH event takes.

GPU_WORK

gizlang
const GPU_WORK: i64 = Wire.PROFILE_GPU_WORK

A kernel's work (Gpu.work), beside its GPU_KERNEL event: a = its operations, b = the bytes it moves, text its name.