prof

In-program profiling, callable directly from CX code. Provides timing measurement, memory snapshots, named counters, HDR histograms, structured trace events, and flamegraph emission — for the cases where a program measures itself and acts on the result. Timer, counter, histogram, and trace are the four primitives; all are impure because they observe or mutate process state.

prof:time-fn

[$prof:time-fn] -> element — Run a thunk and return a timing element carrying its elapsed time and return value.

            [?lib 'cx-stdlib/prof']
[$prof:time-fn "work" [?fn () 42]]
          
            cx-err:CXER0271

prof:now-ns

[$prof:now-ns] -> int — Return a monotonic-clock reading in nanoseconds.

            [?lib 'cx-stdlib/prof']
[$prof:now-ns]
          
            cx-err:CXER0271

prof:now-cpu-ns

[$prof:now-cpu-ns] -> int — Return the process CPU-time clock value in nanoseconds.

            [?lib 'cx-stdlib/prof']
[$prof:now-cpu-ns]
          
            cx-err:CXER0271

prof:mem-snapshot

[$prof:mem-snapshot] -> element — Capture current process memory state, always carrying rss-bytes and a timestamp.

            [?lib 'cx-stdlib/prof']
[?let [= $s [$prof:mem-snapshot]]
  [> $s@rss-bytes 0]]
          
            true

prof:gc-trigger

[$prof:gc-trigger] -> null — Request a garbage-collection cycle, best-effort; the underlying GC may decline.

            [?lib 'cx-stdlib/prof']
[$prof:gc-trigger]
          
            null

prof:counter-inc

[$prof:counter-inc] -> null — Atomically add one to the named process-global counter.

            [?lib 'cx-stdlib/prof']
[$prof:counter-inc "prof-007-hits"]
          
            null

prof:counter-add

[$prof:counter-add] -> null — Atomically add a delta to the named process-global counter.

            [?lib 'cx-stdlib/prof']
[?let [= $_ [$prof:counter-add "prof-009-bytes" 5]]
  [$prof:counter-get "prof-009-bytes"]]
          
            5

prof:counter-get

[$prof:counter-get] -> int — Read the current value of the named counter.

            [?lib 'cx-stdlib/prof']
[?let [= $_ [$prof:counter-inc "prof-008-hits"]]
  [$prof:counter-get "prof-008-hits"]]
          
            1

prof:counter-reset

[$prof:counter-reset] -> null — Reset the named counter back to zero.

            [?lib 'cx-stdlib/prof']
[?let [= $_ [$prof:counter-add "prof-011-x" 9]] [= $__ [$prof:counter-reset "prof-011-x"]]
  [$prof:counter-get "prof-011-x"]]
          
            0

prof:counter-all

[$prof:counter-all] -> map — Return a map of every counter name to its current value.

            [?lib 'cx-stdlib/prof']
[?let [= $_ [$prof:counter-add "prof-012-only" 3]]
  [$prof:counter-all]]
          
            {prof-012-only: 3}

prof:histogram-observe

[$prof:histogram-observe] -> null — Record one observation into the named histogram, creating it on first observe.

            [?lib 'cx-stdlib/prof']
[$prof:histogram-observe "prof-013-lat" 8.1]
          
            null

prof:histogram-stats

[$prof:histogram-stats] -> element — Return count, percentiles, min, max, and mean for the named histogram.

            [?lib 'cx-stdlib/prof']
[?let [= $a [$prof:histogram-observe "prof-014-lat" 1.0]] [= $b [$prof:histogram-observe "prof-014-lat" 2.0]] [= $c [$prof:histogram-observe "prof-014-lat" 3.0]] [= $s [$prof:histogram-stats "prof-014-lat"]]
  $s@count]
          
            3

prof:histogram-reset

[$prof:histogram-reset] -> null — Discard the named histogram's observations while keeping the name.

            [?lib 'cx-stdlib/prof']
[?let [= $_ [$prof:histogram-observe "prof-016-lat" 5.0]]
  [$prof:histogram-reset "prof-016-lat"]]
          
            null

prof:trace

[$prof:trace] -> null — Emit a structured trace event with the given fields to the buffer.

            [?lib 'cx-stdlib/prof']
[$prof:trace "request" {request-id="abc"}]
          
            cx-err:CXER0271

prof:trace-flush

[$prof:trace-flush] -> null — Flush buffered trace events to the configured sink.

            [?lib 'cx-stdlib/prof']
[?let [= $_ [$prof:prof-configure {trace-sink: "none"}]]
  [$prof:trace-flush]]
          
            null

prof:prof-configure

[$prof:prof-configure] -> null — Configure the trace sink, buffer size, and counter enablement.

            [?lib 'cx-stdlib/prof']
[$prof:prof-configure {trace-sink: "none"}]
          
            null

prof:time-and-trace

[$prof:time-and-trace] -> element — Time a thunk, emit a trace event with its duration, and return the timing element.

            [?lib 'cx-stdlib/prof']
[$prof:time-and-trace "work" [?fn () 42]]
          
            cx-err:CXER0271

prof:flamegraph-emit

[$prof:flamegraph-emit] -> string — Fold buffered trace events into flamegraph.pl folded-stack output, returned or written to a path.

            [?lib 'cx-stdlib/prof']
[$prof:flamegraph-emit]
          
            ''