main
ply4 git calls37 ms45 KiB3 cachedprotocol v2
298 lines13 KiBRaw
1// Input distributions from Workers Observability span events (issue #73). Pure: no network, no clock. The adapter
2// (scripts/calibrate/query.ts) fetches the events; this module turns them into per-route, per-attribute distributions
3// (n, p50/p90/p99/p99.9, max, a log2 histogram) and categorical counts, and prints them.
4//
5// Where an attribute lives on an event: Workers Observability indexes a span's attributes under `source`. The runtime's
6// own attributes arrive nested by their dots (`source.http.response.status_code`, test/fixtures/cd/canary-spans.json);
7// a custom attribute set with ctx.tracing may arrive nested the same way or as one dotted key. Both are read: `source`
8// is flattened to dotted paths, and a literal dotted key wins over a nested one of the same path.
9import { find, orNull, unwrapOr } from '../../src/option.ts'
10import { mapGet, recordGet } from '../../src/absent.ts'
11import { asRecord } from '../cd/json.ts'
12import { percentile, scriptVersionId } from '../cd/telemetry.ts'
13import { CATEGORICAL, NOT_INPUTS } from './attributes.ts'
15export const ROUTE_KEY = 'ply.route'
16export const VERSION_KEY = 'ply.script_version'
17/** A span that carries no `ply.route`: a span from before #73, or one the Worker did not stamp. */
18export const UNROUTED = 'unrouted'
19/** Every route together. A threshold that is not per route (a cap shared by all of /v1) reads this group. */
20export const ALL_ROUTES = '*'
21/** Every /v1 route together: the group the /v1 API's caps (src/limits.ts API_CAPS) are set against. */
22export const API_GROUP = 'api'
24/** A `/v1` route key (`GET /v1/tree`), as src/index.js stamps it. */
25export function isApiRoute(route: string): boolean {
26 return /^[A-Z]+ \/v1\//.test(route)
29/** The percentiles printed and cited. p99.9 is the tail a hard cap is set against. */
30export const QUANTILES = [0.5, 0.9, 0.99, 0.999] as const
32export type Quantile = (typeof QUANTILES)[number]
34export type Bucket = {
35 /** Values in (lower, upper]. The first bucket is [0, 1]; a negative value has its own bucket with upper 0. */
36 readonly upper: number
37 readonly count: number
40export type Distribution = {
41 readonly n: number
42 readonly min: number
43 readonly max: number
44 readonly p50: number
45 readonly p90: number
46 readonly p99: number
47 readonly p999: number
48 readonly histogram: readonly Bucket[]
51export type CategoryCounts = Readonly<Record<string, number>>
53export type GroupStats = {
54 readonly route: string
55 /** Distinct `ply.script_version` (or `$workers.scriptVersion.id`) values seen in this group, sorted. */
56 readonly versions: readonly string[]
57 /** Span events in the group. */
58 readonly events: number
59 readonly numeric: Readonly<Record<string, Distribution>>
60 readonly categorical: Readonly<Record<string, CategoryCounts>>
63export type CalibrationStats = {
64 readonly events: number
65 /** Span events with no attributes to read (a malformed row). */
66 readonly skipped: number
67 /** By route, sorted; ALL_ROUTES then API_GROUP first. */
68 readonly groups: readonly GroupStats[]
71type Scalar = string | number | boolean
73/** `source` flattened to dotted paths. Nested objects become `a.b.c`; a literal `a.b.c` key replaces the nested one. */
74export function flattenAttributes(source: unknown): Readonly<Record<string, Scalar>> {
75 const nested: Record<string, Scalar> = {}
76 const literal: Record<string, Scalar> = {}
77 const walk = (value: unknown, path: string, depth: number): void => {
78 if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
79 if (path.includes('.') && depth === 1) literal[path] = value
80 else nested[path] = value
81 return
82 }
83 const rec = asRecord(value)
84 if (!rec || Array.isArray(value) || depth > 12) return
85 for (const [key, child] of Object.entries(rec)) walk(child, path === '' ? key : `${path}.${key}`, depth + 1)
86 }
87 walk(source, '', 0)
88 return { ...nested, ...literal }
91function scalarOf(value: unknown): Scalar | null {
92 return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' ? value : null
95/** The attributes of one span event, with the route and version it ran under. Null for a row with no `source`. */
96export function eventAttributes(event: unknown): { readonly route: string; readonly version: string | null; readonly attrs: Readonly<Record<string, Scalar>> } | null {
97 const rec = asRecord(event)
98 if (!rec) return null
99 const source = asRecord(rec.source)
100 if (!source) return null
101 const attrs = flattenAttributes(source)
102 const route = scalarOf(attrs[ROUTE_KEY])
103 const stamped = scalarOf(attrs[VERSION_KEY])
104 const cloudflare = scalarOf(attrs['cloudflare.script_version.id'])
105 const version = typeof stamped === 'string' && stamped !== ''
106 ? stamped
107 : typeof cloudflare === 'string' && cloudflare !== '' ? cloudflare : scriptVersionId(rec)
108 return { route: typeof route === 'string' && route !== '' ? route : UNROUTED, version, attrs }
111/** An attribute that is an input distribution: a finite number under `git.` or `ply.`, not an id, constant or echo. */
112export function isInputAttribute(key: string, value: Scalar): value is number {
113 if (typeof value !== 'number' || !Number.isFinite(value)) return false
114 if (!key.startsWith('git.') && !key.startsWith('ply.')) return false
115 return !NOT_INPUTS.includes(key)
118const CATEGORY_KEYS: readonly string[] = CATEGORICAL
120/** Categorical keys: the fixed taxonomy plus every ply operation's `<root>.outcome`. */
121export function isCategoryAttribute(key: string): boolean {
122 return CATEGORY_KEYS.includes(key) || /^git\.[a-z_]+(\.[a-z_]+)*\.outcome$/.test(key)
125/** Upper bound of the log2 bucket that holds `value`: 1 for [0, 1], then 2, 4, 8, ... A negative value is bucket 0. */
126export function bucketUpper(value: number): number {
127 if (value < 0) return 0
128 if (value <= 1) return 1
129 return 2 ** Math.ceil(Math.log2(value))
132export function log2Histogram(values: readonly number[]): Bucket[] {
133 const counts = new Map<number, number>()
134 for (const value of values) {
135 if (!Number.isFinite(value)) continue
136 const upper = bucketUpper(value)
137 counts.set(upper, unwrapOr(mapGet(counts, upper), 0) + 1)
138 }
139 return [...counts.entries()].sort((a, b) => a[0] - b[0]).map(([upper, count]) => ({ upper, count }))
142/**
143 * n, min, max, p50/p90/p99/p99.9 and the histogram. Null for an empty series.
144 * The percentile is the CD's (scripts/cd/telemetry.ts): sorted[floor((n - 1) * p)], an observed value, never interpolated.
145 */
146export function distribution(values: readonly number[]): Distribution | null {
147 const finite = values.filter(value => Number.isFinite(value))
148 if (finite.length === 0) return null
149 const at = (p: number): number => {
150 const value = percentile(finite, p)
151 return value === null ? Number.NaN : value
152 }
153 let min = Infinity
154 let max = -Infinity
155 for (const value of finite) {
156 if (value < min) min = value
157 if (value > max) max = value
158 }
159 return { n: finite.length, min, max, p50: at(0.5), p90: at(0.9), p99: at(0.99), p999: at(0.999), histogram: log2Histogram(finite) }
162/** The value of `q` on a distribution. */
163export function quantileOf(dist: Distribution, q: Quantile | 1): number {
164 switch (q) {
165 case 0.5: return dist.p50
166 case 0.9: return dist.p90
167 case 0.99: return dist.p99
168 case 0.999: return dist.p999
169 case 1: return dist.max
170 }
173type Accumulator = { events: number; versions: Set<string>; numeric: Map<string, number[]>; categorical: Map<string, Map<string, number>> }
175function accumulator(): Accumulator {
176 return { events: 0, versions: new Set(), numeric: new Map(), categorical: new Map() }
179function add(acc: Accumulator, version: string | null, attrs: Readonly<Record<string, Scalar>>, only: ReadonlySet<string> | null): void {
180 acc.events += 1
181 if (version) acc.versions.add(version)
182 for (const [key, value] of Object.entries(attrs)) {
183 if (only !== null && !only.has(key)) continue
184 if (isCategoryAttribute(key)) {
185 const counts = unwrapOr(mapGet(acc.categorical, key), new Map<string, number>())
186 const label = String(value)
187 counts.set(label, unwrapOr(mapGet(counts, label), 0) + 1)
188 acc.categorical.set(key, counts)
189 }
190 if (!isInputAttribute(key, value)) continue
191 const series = unwrapOr(mapGet(acc.numeric, key), [])
192 series.push(value)
193 acc.numeric.set(key, series)
194 }
197function finish(route: string, acc: Accumulator): GroupStats {
198 const numeric: Record<string, Distribution> = {}
199 for (const key of [...acc.numeric.keys()].sort()) {
200 const dist = distribution(unwrapOr(mapGet(acc.numeric, key), []))
201 if (dist) numeric[key] = dist
202 }
203 const categorical: Record<string, CategoryCounts> = {}
204 for (const key of [...acc.categorical.keys()].sort()) {
205 const counts = unwrapOr(mapGet(acc.categorical, key), new Map<string, number>())
206 categorical[key] = Object.fromEntries([...counts.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1)))
207 }
208 return { route, versions: [...acc.versions].sort(), events: acc.events, numeric, categorical }
211export type StatsOptions = {
212 /** Keep only these attributes (numeric or categorical). Null keeps every input attribute. */
213 readonly attributes: readonly string[] | null
214 /** Keep only these routes. Null keeps every route. ALL_ROUTES and API_GROUP are computed over what is kept. */
215 readonly routes: readonly string[] | null
216 /** Keep only these versions. Null keeps every version. */
217 readonly versions: readonly string[] | null
220/** No filter: every route, version and input attribute. */
221export const EVERYTHING: StatsOptions = { attributes: null, routes: null, versions: null }
223/** Group span events by route (and ALL_ROUTES), and summarize every input attribute in each group. */
224export function calibrationStats(events: readonly unknown[], options: StatsOptions = EVERYTHING): CalibrationStats {
225 const only = options.attributes ? new Set(options.attributes) : null
226 const routes = options.routes ? new Set(options.routes) : null
227 const versions = options.versions ? new Set(options.versions) : null
228 const all = accumulator()
229 const api = accumulator()
230 const byRoute = new Map<string, Accumulator>()
231 let skipped = 0
232 let kept = 0
233 for (const event of events) {
234 const read = eventAttributes(event)
235 if (!read) {
236 skipped += 1
237 continue
238 }
239 if (routes !== null && !routes.has(read.route)) continue
240 if (versions !== null && (read.version === null || !versions.has(read.version))) continue
241 kept += 1
242 const acc = unwrapOr(mapGet(byRoute, read.route), accumulator())
243 add(acc, read.version, read.attrs, only)
244 byRoute.set(read.route, acc)
245 add(all, read.version, read.attrs, only)
246 if (isApiRoute(read.route)) add(api, read.version, read.attrs, only)
247 }
248 const groups = [finish(ALL_ROUTES, all), finish(API_GROUP, api), ...[...byRoute.keys()].sort().map(route => finish(route, unwrapOr(mapGet(byRoute, route), accumulator())))]
249 return { events: kept, skipped, groups }
252export function groupOf(stats: CalibrationStats, route: string): GroupStats | null {
253 return orNull(find(stats.groups, group => group.route === route))
256/** One attribute's distribution in one route group, or null when the group or the attribute is absent. */
257export function numericOf(stats: CalibrationStats, route: string, attribute: string): Distribution | null {
258 const group = groupOf(stats, route)
259 return group === null ? null : orNull(recordGet(group.numeric, attribute))
262const BAR_WIDTH = 40
264function fmt(value: number): string {
265 if (Number.isInteger(value)) return String(value)
266 return value.toFixed(3).replace(/0+$/, '').replace(/\.$/, '')
269function histogramLines(histogram: readonly Bucket[]): string[] {
270 const peak = histogram.reduce((most, bucket) => Math.max(most, bucket.count), 0)
271 return histogram.map(bucket => {
272 const width = peak === 0 ? 0 : Math.max(1, Math.round((bucket.count / peak) * BAR_WIDTH))
273 return ` <=${fmt(bucket.upper).padStart(12)} ${String(bucket.count).padStart(7)} ${'#'.repeat(width)}`
274 })
277/** One attribute's summary line: n, p50/p90/p99/p99.9, max. */
278export function distributionLine(key: string, dist: Distribution): string {
279 return ` ${key} n=${dist.n} p50=${fmt(dist.p50)} p90=${fmt(dist.p90)} p99=${fmt(dist.p99)} p99.9=${fmt(dist.p999)} max=${fmt(dist.max)}`
282/** The report: per route, per attribute, the summary line and its histogram; then categorical counts. */
283export function statsText(stats: CalibrationStats, window: { readonly from: number; readonly to: number }, histograms = true): string {
284 const lines = [
285 `calibrate: ${new Date(window.from).toISOString()} .. ${new Date(window.to).toISOString()} span events=${stats.events} skipped=${stats.skipped}`,
286 ]
287 for (const group of stats.groups) {
288 lines.push('', `route ${group.route} events=${group.events} versions=${group.versions.length === 0 ? '-' : group.versions.join(',')}`)
289 for (const [key, dist] of Object.entries(group.numeric)) {
290 lines.push(distributionLine(key, dist))
291 if (histograms) lines.push(...histogramLines(dist.histogram))
292 }
293 for (const [key, counts] of Object.entries(group.categorical)) {
294 lines.push(` ${key} ${Object.entries(counts).map(([value, count]) => `${value}=${count}`).join(' ')}`)
295 }
296 }
297 return `${lines.join('\n')}\n`
Diagnostics4 git calls · 37 ms
CallStatusSizeTime037 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200145 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=145
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=145
git.pkt.payload.max=76
git.ls_refs.count=2
git.ls_refs.head=refs/heads/main
fetchblob:none · deepen 1020040 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=41349
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=526b305930b8ef382f2d7a1f9c0238730a585921
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=6
git.pkt.data=4
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=41349
git.pkt.payload.max=41254
git.sideband.band1.bytes=41253
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=61
git.pack.bytes=41253
git.pack.ofs_delta=0
git.pack.ref_delta=0
git.pack.chain.max=0
git.pack.trailer=ab60efef4b7243678c75de64a4386986ee885c1c
git.pack.full=61
Open pack map
fetch2004.4 KiB · hit31 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=30
git.response.bytes=4504
git.response.cache=HIT
git.response.duration_ms=31
git.fetch.wants=98c3867f96cf2953eb071ebf456b7be091649dbf
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=4504
git.pkt.payload.max=4483
git.sideband.band1.bytes=4482
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/ply-web.git
Ref
refs/heads/main
Commit
526b305930b8ef382f2d7a1f9c0238730a585921
cf-ray
a5e303e32d247929
Request
34c08e94…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format