main
ply4 git calls34 ms44 KiB2 cachedprotocol v2
209 lines12 KiBRaw
1// src/edge-trace.ts and openSpan (src/flags/telemetry.ts) against a fake `ctx.tracing`. The runtime itself is exercised
2// by test/worker-spans.test.js (the cf bundle under workerd, through a streaming tail).
3import assert from 'node:assert/strict'
4import { AsyncLocalStorage } from 'node:async_hooks'
5import { test } from 'node:test'
6import { arrayExporter, Tracer } from 'ply'
7import { EDGE_ATTR, REQUEST_ATTR, cacheStatsOf, edgeTracingOf, plyTracer, requestStamp, routeStamp, spanList, stampRequestSpan } from '../src/edge-trace.ts'
8import { openSpan, type TracingLike } from '../src/flags/telemetry.ts'
10type Recorded = { name: string; parent: string | null; attrs: Record<string, unknown>; status: string | null; ended: boolean }
12/**
13 * A fake of workerd's ctx.tracing: the active span lives in the async context, and startActiveSpan makes the new span
14 * active for its callback (and what that callback captures), not after it returns.
15 */
16function fakeTracing() {
17 const spans: Recorded[] = []
18 const active = new AsyncLocalStorage<string>()
19 const tracing = {
20 startActiveSpan<T>(name: string, fn: (span: unknown) => T): T {
21 const parent = active.getStore()
22 const rec: Recorded = { name, parent: typeof parent === 'string' ? parent : null, attrs: {}, status: null, ended: false }
23 spans.push(rec)
24 return active.run(name, () => fn({
25 setAttribute(key: string, value: unknown) { rec.attrs[key] = value },
26 setStatus(status: { code: string }) { rec.status = status.code },
27 end() { rec.ended = true },
28 }))
29 },
30 }
31 return { tracing, spans }
34test('without ctx.tracing the request gets ply\'s plain Tracer', () => {
35 for (const ctx of [null, {}, { tracing: null }, { tracing: { enterSpan() {} } }]) {
36 assert.equal(edgeTracingOf(ctx), null)
37 assert.equal(Object.getPrototypeOf(plyTracer(ctx, {})), Tracer.prototype)
38 }
39})
41test('each ply span is a platform span, closed with ply\'s attributes, ids and error status; the exporter still gets it', async () => {
42 const { tracing, spans } = fakeTracing()
43 const exporter = arrayExporter()
44 const tracer = plyTracer({ tracing }, { exporter })
45 const root = tracer.start('git.edit', { attrs: { 'git.edit.path': 'a.txt' } })
46 await tracer.span('git.edit.blob', { parent: root }, async span => {
47 span.set({ 'git.edit.blob.delta.bytes': 9, 'git.edit.blob.ops': ['copy', 'insert'] })
48 })
49 root.error(Object.assign(new Error('stale'), { code: 'cas_conflict' }))
50 root.end()
51 assert.equal(exporter.lines.length, 2)
52 assert.deepEqual(spans.map(s => s.name), ['git.edit', 'git.edit.blob'])
53 const [edit, blob] = spans
54 assert.ok(edit && blob)
55 assert.equal(edit.parent, null)
56 assert.equal(blob.parent, 'git.edit', 'nested as ply nests it, though git.edit was never the active span')
57 assert.ok(edit.ended && blob.ended)
58 assert.equal(edit.attrs['git.edit.path'], 'a.txt')
59 assert.equal(edit.status, 'error')
60 assert.equal(blob.attrs['git.edit.blob.delta.bytes'], 9)
61 assert.equal(blob.attrs['git.edit.blob.ops'], '["copy","insert"]')
62 assert.equal(blob.attrs[EDGE_ATTR.parentSpanId], edit.attrs[EDGE_ATTR.spanId])
63 assert.equal(typeof blob.attrs[EDGE_ATTR.durationMs], 'number')
64 assert.equal(blob.status, null)
65})
67/** The fake with workerd's `setAttributes`: every call is recorded, so the test counts platform calls per span. */
68function bulkTracing() {
69 const spans: (Recorded & { calls: string[] })[] = []
70 const active = new AsyncLocalStorage<string>()
71 const tracing = {
72 startActiveSpan<T>(name: string, fn: (span: unknown) => T): T {
73 const parent = active.getStore()
74 const rec = { name, parent: typeof parent === 'string' ? parent : null, attrs: {} as Record<string, unknown>, status: null as string | null, ended: false, calls: [] as string[] }
75 spans.push(rec)
76 return active.run(name, () => fn({
77 setAttribute(key: string, value: unknown) { rec.calls.push('setAttribute'); rec.attrs[key] = value },
78 // workerd joins an array with commas (measured: workerd 1.20261018.1); the JSON in the second call replaces it
79 setAttributes(attrs: Record<string, unknown>) { rec.calls.push('setAttributes'); for (const [k, v] of Object.entries(attrs)) rec.attrs[k] = Array.isArray(v) ? v.join(',') : v },
80 setStatus(status: { code: string }) { rec.calls.push('setStatus'); rec.status = status.code },
81 end() { rec.calls.push('end'); rec.ended = true },
82 }))
83 },
84 }
85 return { tracing, spans }
88test('with setAttributes a span costs two attribute calls, and lands the same attributes as one call each', async () => {
89 const run = async (fake: { tracing: unknown; spans: Recorded[] }) => {
90 const kept = spanList()
91 const tracer = plyTracer({ tracing: fake.tracing }, { onEnd: kept.onEnd }, routeStamp('GET /v1/tree', 'v-9'))
92 const root = tracer.start('git.read', { attrs: { 'git.read.path': 'a.txt', 'git.read.bytes': 12n, 'git.read.none': null } })
93 const wire = tracer.start('git.upload-pack fetch', { parent: root, attrs: { 'git.fetch.wants': ['a', 'b'], 'git.fetch.filter': 'tree:0', 'git.fetch.done': true, 'git.response.duration_ms': 1.5 } })
94 wire.end()
95 root.end()
96 const follower = tracer.start('git.read.blob', { follows: root })
97 follower.error(Object.assign(new Error('cut'), { code: 'http' }))
98 follower.end()
99 return { kept, spans: fake.spans }
100 }
101 const bulk = await run(bulkTracing())
102 const each = await run(fakeTracing())
103 assert.equal(bulk.kept.spans.length, 3, 'the caller\'s onEnd still gets every span')
104 assert.deepEqual(bulk.spans.map(s => s.name), ['git.read', 'git.upload-pack fetch', 'git.read.blob'])
105 for (const s of bulk.spans as (Recorded & { calls: string[] })[]) assert.deepEqual(s.calls.filter(c => c.startsWith('setAttribute')), ['setAttributes', 'setAttributes'], s.name)
106 const strip = (attrs: Record<string, unknown>) => Object.fromEntries(Object.entries(attrs).filter(([k]) => k !== EDGE_ATTR.spanId && k !== EDGE_ATTR.traceId && k !== EDGE_ATTR.parentSpanId && k !== EDGE_ATTR.followsSpanId && k !== EDGE_ATTR.durationMs && !k.startsWith('ply.isolate.')))
107 bulk.spans.forEach((s, i) => assert.deepEqual(strip(s.attrs), strip(each.spans[i]!.attrs), s.name))
108 const [read, wire, blob] = bulk.spans
109 assert.ok(read && wire && blob)
110 assert.equal(wire.attrs['git.fetch.wants'], '["a","b"]', 'an array is JSON, as before')
111 assert.equal(read.attrs['git.read.bytes'], 12)
112 assert.equal(read.attrs['git.read.none'], '')
113 assert.equal(wire.attrs[EDGE_ATTR.route], 'GET /v1/tree')
114 assert.equal(wire.attrs[EDGE_ATTR.version], 'v-9')
115 assert.equal(wire.attrs[EDGE_ATTR.parentSpanId], read.attrs[EDGE_ATTR.spanId])
116 assert.equal(wire.attrs[EDGE_ATTR.traceId], read.attrs[EDGE_ATTR.traceId])
117 assert.equal(blob.attrs[EDGE_ATTR.followsSpanId], read.attrs[EDGE_ATTR.spanId])
118 assert.equal(blob.status, 'error')
119 assert.equal(blob.attrs['error.type'], 'http')
120 assert.equal(typeof wire.attrs[EDGE_ATTR.durationMs], 'number')
121 assert.ok(bulk.spans.every(s => s.ended))
122 assert.equal(JSON.stringify(bulk.kept.spans.map(s => s.attrs)).includes(EDGE_ATTR.route), false, 'the kept spans are not stamped')
123})
125test('a runtime that throws on span calls does not fail the request', async () => {
126 const tracer = plyTracer({ tracing: { startActiveSpan() { throw new Error('no tracing here') } } }, { exporter: arrayExporter() })
127 assert.equal(await tracer.span('git.head', {}, async () => 7), 7)
128})
130test('openSpan uses the runtime\'s startSpan, with its receiver', () => {
131 const opened: string[] = []
132 const tracing = {
133 marker: 'ctx.tracing',
134 startSpan(this: { marker: string }, name: string) { opened.push(`${this.marker}:${name}`); return { end() {} } },
135 // workerd's enterSpan takes a callback; it must not be called with one argument.
136 enterSpan(name: string, fn: () => unknown) { opened.push(`enter:${name}`); return fn() },
137 }
138 assert.ok(openSpan(tracing as unknown as TracingLike, 'ply.viewer'))
139 assert.deepEqual(opened, ['ctx.tracing:ply.viewer'])
140})
142test('the route and version stamp is on every platform span, and not in ply\'s own export', async () => {
143 const { tracing, spans } = fakeTracing()
144 const exporter = arrayExporter()
145 const tracer = plyTracer({ tracing }, { exporter }, routeStamp('GET /v1/tree', 'v-123'))
146 await tracer.span('git.ls_tree', {}, async span => {
147 span.set({ 'git.ls_tree.entries': 12 })
148 await tracer.span('git.upload-pack fetch', { parent: span }, async () => {})
149 })
150 assert.deepEqual(spans.map(s => [s.name, s.attrs[EDGE_ATTR.route], s.attrs[EDGE_ATTR.version]]), [
151 ['git.ls_tree', 'GET /v1/tree', 'v-123'],
152 ['git.upload-pack fetch', 'GET /v1/tree', 'v-123'],
153 ])
154 assert.equal(spans[0].attrs['git.ls_tree.entries'], 12)
155 assert.equal(JSON.stringify(exporter.lines).includes(EDGE_ATTR.route), false)
156 // No version id (local dev): the key is left out, not filled with a placeholder.
157 assert.deepEqual(routeStamp('viewer', null), { [EDGE_ATTR.route]: 'viewer' })
158 assert.deepEqual(routeStamp('viewer', ''), { [EDGE_ATTR.route]: 'viewer' })
159})
161test('stampRequestSpan sets attributes on the runtime\'s active span, and never throws', () => {
162 const attrs: Record<string, unknown> = {}
163 const active = { setAttribute(key: string, value: unknown) { attrs[key] = value } }
164 assert.equal(stampRequestSpan({ tracing: { startActiveSpan() {}, getActiveSpan: () => active } }, { 'ply.route': 'GET /v1/refs' }), true)
165 assert.deepEqual(attrs, { 'ply.route': 'GET /v1/refs' })
166 for (const ctx of [null, {}, { tracing: {} }, { tracing: { getActiveSpan: () => null } }, { tracing: { getActiveSpan: () => ({}) } }, { tracing: { getActiveSpan() { throw new Error('no') } } }]) {
167 assert.equal(stampRequestSpan(ctx, { a: 1 }), false)
168 }
169 const refusing = { setAttribute() { throw new Error('closed') } }
170 assert.equal(stampRequestSpan({ tracing: { getActiveSpan: () => refusing } }, { a: 1 }), false)
171})
173test('requestStamp copies the route, version, status, error and ply\'s counts from the request log', () => {
174 assert.deepEqual(requestStamp({ route: 'POST /v1/edit', version: 'v1', surface: 'api', status: 409, log: { code: 'cas_conflict', spans: 7, rtt: 3, wide: 0, cache_hits: 1, cache_misses: 2 } }), {
175 [REQUEST_ATTR.route]: 'POST /v1/edit',
176 [REQUEST_ATTR.version]: 'v1',
177 [REQUEST_ATTR.surface]: 'api',
178 [REQUEST_ATTR.status]: 409,
179 [REQUEST_ATTR.errorCode]: 'cas_conflict',
180 [REQUEST_ATTR.spans]: 7,
181 [REQUEST_ATTR.roundTrips]: 3,
182 [REQUEST_ATTR.wide]: 0,
183 [REQUEST_ATTR.cacheHits]: 1,
184 [REQUEST_ATTR.cacheMisses]: 2,
185 })
186 const unexpected = requestStamp({ route: 'unmatched', version: null, surface: 'api', status: 500, log: { code: 'internal', error_kind: 'unexpected', spans: Number.NaN, viewer: 1 } })
187 assert.deepEqual(unexpected, { 'ply.route': 'unmatched', 'ply.surface': 'api', 'http.response.status_code': 500, 'ply.error.code': 'internal', 'ply.error.kind': 'unexpected' })
188})
190test('cacheStatsOf counts pack-cache child outcomes (HIT/MISS), ignores empty/NONE', () => {
191 const spans = [
192 { name: 'git.upload-pack fetch', attrs: { 'git.pack.cache': 'HIT', 'git.response.cache': 'HIT' } },
193 { name: 'git.upload-pack fetch', attrs: { 'git.pack.cache': 'MISS' } },
194 { name: 'git.upload-pack fetch', attrs: { 'git.response.cache': '', 'git.pack.cache': '' } },
195 { name: 'git.upload-pack fetch', attrs: { 'git.pack.cache': 'NONE' } },
196 { name: 'git.upload-pack fetch', attrs: { 'http.response.headers.from_cache': true } },
197 { name: 'git.upload-pack ls-refs', attrs: { 'git.pack.cache': 'BUST' } },
198 { name: 'git.read', attrs: { 'git.fetch.filter.fallback': true } },
199 ]
200 assert.deepEqual(cacheStatsOf(spans as never), {
201 spans: 7,
202 rtt: 6,
203 wide: 1,
204 cache_hits: 2,
205 cache_misses: 2,
206 })
207 // empty response.cache falls through to pack.cache
208 assert.equal(cacheStatsOf([{ name: 'git.upload-pack fetch', attrs: { 'git.response.cache': '', 'git.pack.cache': 'HIT' } }] as never).cache_hits, 1)
209})
Diagnostics4 git calls · 34 ms
CallStatusSizeTime034 ms
discover200152 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
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 B2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=145
git.response.cache=UPDATING
git.response.duration_ms=2
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 · hit6 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=41349
git.response.cache=HIT
git.response.duration_ms=6
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
fetch2003.5 KiB · hit26 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=26
git.response.bytes=3598
git.response.cache=HIT
git.response.duration_ms=26
git.fetch.wants=9caf387ba9cdef28336369d3fbbd13a9ba189f96
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=3598
git.pkt.payload.max=3577
git.sideband.band1.bytes=3576
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
a5e2e8094857ecfa
Request
c7014aff…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format