main
ply4 git calls29 ms46 KiB3 cachedprotocol v2
336 lines17 KiBRaw
1import { existsSync } from 'node:fs'
2import { mkdir, writeFile } from 'node:fs/promises'
3import { basename, dirname, join, relative } from 'node:path'
4import { atIndex, chainGet, mapGet } from '../../src/absent.ts'
5import { unwrapOr } from '../../src/option.ts'
6import { chartPng, type ChartSeries, type Rgb } from './charts.ts'
7import { readEvents, type CdEvent } from './log.ts'
8import { FAST_BURN } from './slo.ts'
10type Measurement = { readonly [key: string]: unknown }
12function measurement(event: CdEvent): Measurement | null {
13 if (event.kind !== 'observation') return null
14 const value = event.payload.measurement
15 if (value === null || typeof value !== 'object' || Array.isArray(value)) return null
16 return value as Measurement
19function num(value: unknown): number | null {
20 return typeof value === 'number' && Number.isFinite(value) ? value : null
23function field(value: unknown, key: string): unknown {
24 return unwrapOr(chainGet(value, key), null)
27function textOrDash(value: string | null): string {
28 return value === null ? '-' : value
31function numCell(value: unknown): number | string {
32 const parsed = num(value)
33 return parsed === null ? '-' : parsed
36function firstNum(...values: readonly unknown[]): number | null {
37 for (const value of values) {
38 const parsed = num(value)
39 if (parsed !== null) return parsed
40 }
41 return null
44function numOrZero(...values: readonly unknown[]): number {
45 const parsed = firstNum(...values)
46 return parsed === null ? 0 : parsed
49function labelOf(labels: readonly string[], index: number): string {
50 return unwrapOr(atIndex(labels, index), '')
53function findShare<T>(items: readonly T[], keep: (item: T) => boolean): T | null {
54 for (const item of items) {
55 if (keep(item)) return item
56 }
57 return null
60const BURN_FALLBACK: Rgb = [15, 23, 42]
62function burnAt(step: object, name: string): number {
63 if (!('burns' in step)) return 0
64 const value = chainGet(burnsOf(step.burns), name)
65 if (value.tag === 'none' || typeof value.value !== 'number') return 0
66 return value.value
69function burnsOf(value: unknown): { readonly [slo: string]: number | null } {
70 if (value === null || typeof value !== 'object' || Array.isArray(value)) return {}
71 const out: { [slo: string]: number | null } = {}
72 for (const [key, burn] of Object.entries(value)) {
73 out[key] = burn === null ? null : num(burn)
74 }
75 return out
78function summarize(event: CdEvent): string {
79 if (event.kind === 'lifecycle') {
80 if (event.payload.event === 'run_started') return 'run started'
81 if (event.payload.event === 'resumed') return `resumed ${event.payload.sha.slice(0, 12)}`
82 return `run finished ${event.payload.verdict}`
83 }
84 if (event.kind === 'command') return `${event.payload.argv.join(' ')} exit ${event.payload.exitCode}`.slice(0, 120)
85 if (event.kind === 'observation') {
86 const measured = measurement(event)
87 const source = measured === null ? null : field(measured, 'source')
88 return typeof source === 'string' ? source : 'measurement'
89 }
90 if (event.kind === 'decision') return `${event.payload.outcome}: ${event.payload.reason}`
91 if (event.kind === 'state_change') {
92 const after = event.payload.after.map(share => `${share.percentage}% ${share.versionId.slice(0, 8)}`).join(', ')
93 return `traffic → ${after || 'empty'}`
94 }
95 if (event.kind === 'request') return `${event.payload.method} ${event.payload.status} ${textOrDash(event.payload.version)} ${event.payload.latencyMs}ms`
96 if (event.kind === 'annotation') return `${event.payload.note}: ${event.payload.reason}`
97 if (event.kind === 'policy') return `policy ${event.payload.sha256.slice(0, 12)}`
98 return event.payload.message
101function link(fromDir: string, file: string): string {
102 return relative(fromDir, file).split('\\').join('/')
105/** Informational: smoke ids telemetry never returned, per telemetry stage. Fails the run only when `exceeded`. */
106export function telemetryLossSection(events: readonly CdEvent[]): string[] {
107 const losses = events.map(measurement).filter((value): value is Measurement => value !== null && field(value, 'source') === 'telemetry-loss')
108 if (losses.length === 0) return []
109 const lines = ['## Telemetry loss', '', '| stage | missing | total | rate | max | exceeded |', '| --- | --- | --- | --- | --- | --- |']
110 for (const loss of losses) {
111 const rate = num(loss.rate)
112 const max = num(loss.maxLossRate)
113 lines.push(`| ${loss.live === true ? 'live' : 'pinned'} | ${numCell(loss.count)} | ${numCell(loss.total)} | ${rate === null ? '-' : `${(rate * 100).toFixed(1)}%`} | ${max === null ? '-' : `${(max * 100).toFixed(1)}%`} | ${loss.exceeded === true ? 'yes' : 'no'} |`)
114 }
115 lines.push('')
116 for (const loss of losses) {
117 const ids = Array.isArray(loss.ids) ? loss.ids : []
118 for (const item of ids) {
119 if (item === null || typeof item !== 'object') continue
120 const lost = item as Measurement
121 lines.push(`- ${loss.live === true ? 'live' : 'pinned'} ${String(lost.step)} \`${String(lost.id)}\` log ${lost.log === true ? 'missing' : 'ok'}, trace ${lost.trace === true ? 'missing' : 'ok'}`)
122 }
123 }
124 lines.push('')
125 return lines
128/** One point per state_change. The 0% canary is the version that was introduced at 0. */
129export function canarySplit(events: readonly CdEvent[]): { readonly percent: number; readonly seen: number }[] {
130 const changes = events.filter(event => event.kind === 'state_change')
131 let canary: string | null = null
132 for (const event of changes) {
133 if (event.kind !== 'state_change') continue
134 const zero = event.payload.after.find(share => share.percentage === 0)
135 if (zero) {
136 canary = zero.versionId
137 break
138 }
139 }
140 const seenAt = new Map<number, number>()
141 for (const step of rampSteps(events)) {
142 const percent = num(step.percent)
143 const seen = firstNum(step.routedNewShare, step.observedPercent)
144 if (percent !== null && seen !== null) seenAt.set(percent, seen)
145 }
146 return changes.flatMap(event => {
147 if (event.kind !== 'state_change') return []
148 const matched = canary === null ? null : findShare(event.payload.after, item => item.versionId === canary)
149 const other = findShare(event.payload.after, item => item.percentage !== 100)
150 const first = unwrapOr(atIndex(event.payload.after, 0), null)
151 const share = canary === null ? (other === null ? first : other) : matched
152 const percent = share === null ? 0 : share.percentage
153 return [{ percent, seen: unwrapOr(mapGet(seenAt, percent), 0) }]
154 })
157function jsonObject(value: unknown): { readonly [key: string]: unknown } | null {
158 if (value === null || typeof value !== 'object' || Array.isArray(value)) return null
159 return value as { readonly [key: string]: unknown }
162function policyBurn(events: readonly CdEvent[]): number {
163 for (let index = events.length - 1; index >= 0; index--) {
164 const event = events[index]
165 if (!event || event.kind !== 'policy') continue
166 const body = jsonObject(event.payload.body)
167 const burn = jsonObject(body === null ? null : field(body, 'burn'))
168 const fast = burn === null ? null : field(burn, 'fastBurn')
169 if (typeof fast === 'number') return fast
170 }
171 return FAST_BURN
174function latencyMode(events: readonly CdEvent[]): string | null {
175 for (let index = events.length - 1; index >= 0; index--) {
176 const event = events[index]
177 if (!event || event.kind !== 'policy') continue
178 const body = jsonObject(event.payload.body)
179 const gates = jsonObject(body === null ? null : field(body, 'gates'))
180 const latency = jsonObject(gates === null ? null : field(gates, 'latency'))
181 const mode = latency === null ? null : field(latency, 'mode')
182 return typeof mode === 'string' ? mode : null
183 }
184 return null
187function rampSteps(events: readonly CdEvent[]): Measurement[] {
188 return events.flatMap(event => {
189 const value = measurement(event)
190 return value !== null && field(value, 'source') === 'ramp-step' ? [value] : []
191 })
194/**
195 * Markdown plus three PNGs, written beside the run directory so the sealed run stays unchanged.
196 * Returns the markdown path.
197 */
198export async function writeDebrief(runDir: string, outDir = join(dirname(runDir), `${basename(runDir)}.debrief`)): Promise<string> {
199 const events = await readEvents(runDir)
200 await mkdir(outDir, { recursive: true })
201 const bySeq = new Map(events.map(event => [event.seq, event]))
202 const started = events.find(event => event.kind === 'lifecycle' && event.payload.event === 'run_started')
203 const finished = events.find(event => event.kind === 'lifecycle' && event.payload.event === 'run_finished')
204 const firstEvent = unwrapOr(atIndex(events, 0), null)
205 const lines: string[] = [`# Debrief ${firstEvent === null ? basename(runDir) : firstEvent.run_id}`, '']
206 if (started && started.kind === 'lifecycle' && started.payload.event === 'run_started') {
207 const payload = started.payload
208 const pair = payload.release ? ` Release \`${payload.release.ply}+${payload.release.web}\`.` : ''
209 lines.push(`${payload.host} ran ply \`${textOrDash(payload.plySha)}\` on ply-web \`${payload.plyWebSha}\`.${pair}`)
210 lines.push('')
211 lines.push(`Tools: node ${payload.tools.node}, ${payload.tools.cf}, ${payload.tools.git}.`)
212 lines.push('')
213 }
214 const policies = events.filter(event => event.kind === 'policy')
215 if (policies.length > 0) {
216 lines.push('## Policy', '')
217 for (const event of policies) {
218 if (event.kind !== 'policy') continue
219 const pair = event.payload.release
220 ? `ply \`${event.payload.release.ply}\` ply-web \`${event.payload.release.web}\``
221 : null
222 lines.push(`\`${event.payload.sha256}\``, '', event.payload.path, ...(pair ? ['', pair] : []), '', '```json', JSON.stringify(event.payload.body, null, 2), '```', '')
223 }
224 }
225 if (finished && finished.kind === 'lifecycle' && finished.payload.event === 'run_finished') {
226 const payload = finished.payload
227 lines.push(`Verdict **${payload.verdict}**${payload.reason ? `: ${payload.reason}` : ''}.`)
228 lines.push('')
229 lines.push(`Version ${textOrDash(payload.versionId)}. Rolled back: ${payload.rolledBack ? 'yes' : 'no'}${payload.rollbackReason ? ` (${payload.rollbackReason})` : ''}.`)
230 lines.push('')
231 lines.push(`Smoke ${payload.smoke.passed} passed, ${payload.smoke.failed} failed. Live at ${textOrDash(payload.liveAt)}.`)
232 lines.push('')
233 if (payload.plyMergedAt) lines.push(`ply merged at ${payload.plyMergedAt}.`, '')
234 }
235 lines.push('## Timeline', '', '| seq | time | stage | kind | what |', '| --- | --- | --- | --- | --- |')
236 for (const event of events) {
237 lines.push(`| ${event.seq} | ${event.ts} | ${event.stage} | ${event.kind} | ${summarize(event).replace(/\|/g, '/')} |`)
238 }
239 lines.push('', '## Decisions', '')
240 const decisions = events.filter(event => event.kind === 'decision')
241 if (decisions.length === 0) lines.push('No decisions were recorded.', '')
242 for (const event of decisions) {
243 if (event.kind !== 'decision') continue
244 lines.push(`### ${event.seq}. ${event.payload.outcome}`, '', event.payload.reason, '')
245 lines.push('Rules:')
246 for (const rule of event.payload.rules) lines.push(`- \`${rule.name}\` = ${rule.value}`)
247 lines.push('', 'Inputs:')
248 for (const input of event.payload.inputs) {
249 const source = bySeq.get(input)
250 const path = source && source.kind === 'observation' ? source.payload.responsePath : ''
251 lines.push(`- event ${input}${path ? ` ([${path}](${link(outDir, join(runDir, path))}))` : ''}: ${source ? summarize(source) : 'missing'}`)
252 }
253 lines.push('')
254 }
255 lines.push(...telemetryLossSection(events))
256 lines.push('## Traffic', '', '| seq | before | after | deployment |', '| --- | --- | --- | --- |')
257 const changes = events.filter(event => event.kind === 'state_change')
258 if (changes.length === 0) lines.push('| - | - | - | - |')
259 for (const event of changes) {
260 if (event.kind !== 'state_change') continue
261 const show = (shares: readonly { versionId: string; percentage: number }[]) => shares.map(share => `${share.percentage}% ${share.versionId}`).join(', ') || '-'
262 lines.push(`| ${event.seq} | ${show(event.payload.before)} | ${show(event.payload.after)} | ${textOrDash(event.payload.deploymentId)} |`)
263 }
264 const steps = rampSteps(events)
265 const labels = steps.map((step, index) => {
266 const percent = num(step.percent)
267 return String(percent === null ? index + 1 : percent)
268 })
269 const splitPoints = canarySplit(events)
270 const split: ChartSeries[] = splitPoints.length > 0
271 ? [
272 { name: 'cfg', rgb: [194, 65, 12], points: splitPoints.map(point => ({ x: String(point.percent), y: point.percent })) },
273 { name: 'seen', rgb: [15, 118, 110], points: splitPoints.map(point => ({ x: String(point.percent), y: point.seen })) },
274 ]
275 : [
276 { name: 'cfg', rgb: [194, 65, 12], points: steps.map((step, index) => ({ x: labelOf(labels, index), y: numOrZero(step.percent) })) },
277 { name: 'seen', rgb: [15, 118, 110], points: steps.map((step, index) => ({ x: labelOf(labels, index), y: numOrZero(step.routedNewShare, step.observedPercent) })) },
278 ]
279 const latency: ChartSeries[] = [
280 { name: 'new', rgb: [194, 65, 12], points: steps.map((step, index) => ({ x: labelOf(labels, index), y: numOrZero(step.nextWallP99) })) },
281 { name: 'old', rgb: [29, 78, 216], points: steps.map((step, index) => ({ x: labelOf(labels, index), y: numOrZero(step.previousWallP99) })) },
282 ]
283 const finishedSteps = finished && finished.kind === 'lifecycle' && finished.payload.event === 'run_finished' ? finished.payload.steps : []
284 const burnSource = finishedSteps.length ? finishedSteps : steps
285 const burnLabels = burnSource.map((step, index) => {
286 const percent = num(step.percent)
287 return String(percent === null ? index + 1 : percent)
288 })
289 const burnNames = ['availability', 'read_latency', 'write_latency', 'correctness'] as const
290 const burnColors = [[185, 28, 28], [194, 65, 12], [180, 83, 9], [21, 128, 61]] as const
291 const burn: ChartSeries[] = burnNames.map((name, index) => ({
292 name: name === 'read_latency' ? 'read' : name === 'write_latency' ? 'write' : name === 'availability' ? 'avail' : 'correct',
293 rgb: unwrapOr(atIndex(burnColors, index), BURN_FALLBACK),
294 points: burnSource.map((step, stepIndex) => ({
295 x: labelOf(burnLabels, stepIndex),
296 y: burnAt(step, name),
297 })),
298 }))
299 const fastBurn = policyBurn(events)
300 const mode = latencyMode(events)
301 await writeFile(join(outDir, 'split.png'), chartPng({ title: 'split percent', series: split }))
302 await writeFile(join(outDir, 'latency.png'), chartPng({ title: 'wall p99 ms', series: latency }))
303 await writeFile(join(outDir, 'burn.png'), chartPng({ title: 'burn rate', series: burn, hLine: { y: fastBurn, rgb: [185, 28, 28] } }))
304 lines.push('', '## Charts', '')
305 lines.push('Every state_change, including the 0% canary, against `routedNewShare`: the percent of telemetry invocations the new version served. The band around that share is `toleranceLow`..`toleranceHigh` on the ramp observation. An older run stored `observedPercent` from pinned probes; that field is the fallback. Seen is 0 when that change was not a ramp step.', '')
306 lines.push('![Configured and routed split](split.png)', '')
307 const latencyCaption = mode
308 ? `Wall-time p99 and CPU p99 are recorded on each ramp observation. Latency mode for this run is ${mode}.`
309 : 'Wall-time p99, new version and old version. Informational unless a policy event sets latency to gate.'
310 lines.push(`${latencyCaption} A carried old sample is the last step that still had one.`, '')
311 lines.push('![Latency by version](latency.png)', '')
312 lines.push(`Burn rate per SLO. The horizontal line is the fast-burn multiple ${fastBurn}. A null burn (no samples, or correctness on a ramp step) is drawn as 0.`, '')
313 lines.push('![Burn rate per step](burn.png)', '')
314 lines.push('## Raw files', '')
315 lines.push(`- [events.jsonl](${link(outDir, join(runDir, 'events.jsonl'))})`)
316 lines.push(`- [manifest.json](${link(outDir, join(runDir, 'manifest.json'))})`)
317 // Blobs are content-addressed, so many events cite one file. A clean pass drops them at seal; retention compacts old runs.
318 const cited = new Set<string>()
319 for (const event of events) {
320 if (event.kind === 'observation') cited.add(event.payload.responsePath)
321 if (event.kind === 'command') {
322 cited.add(event.payload.stdoutPath)
323 cited.add(event.payload.stderrPath)
324 }
325 }
326 let missing = 0
327 for (const path of cited) {
328 if (existsSync(join(runDir, path))) lines.push(`- [${path}](${link(outDir, join(runDir, path))})`)
329 else missing += 1
330 }
331 if (missing > 0) lines.push(`- ${missing} cited capture${missing === 1 ? '' : 's'} not kept (a clean pass drops its blobs; see manifest.json \`blobs\`)`)
332 lines.push('')
333 const markdownPath = join(outDir, 'debrief.md')
334 await writeFile(markdownPath, lines.join('\n'))
335 return markdownPath
Diagnostics4 git calls · 29 ms
CallStatusSizeTime029 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.9 KiB · hit23 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=23
git.response.bytes=4993
git.response.cache=HIT
git.response.duration_ms=23
git.fetch.wants=fbedc2fca790b30a2046d7e90032b655ba0d08f7
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=4993
git.pkt.payload.max=4972
git.sideband.band1.bytes=4971
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
a5e2e7e4dc2aecfa
Request
a02fed94…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format