main
ply4 git calls30 ms46 KiB3 cachedprotocol v2
320 lines14 KiBRaw
1// ply's spans in Workers tracing (Workers Observability), live, nested under the request span as ply nests them.
2//
3// ply records every span on its own Tracer (ply-web keeps the ended spans of a request, `spanList()`; src/rays.ts,
4// ?trace=1 and the viewer's trace read them). Nothing there reaches
5// the platform. Workers Observability shows a custom span only when the Worker opens it on `ctx.tracing`, the runtime's
6// user-tracing API (.cloudflare/types/index.d.ts `interface Tracing`, workerd `workerd::api::Tracing`): a span opened
7// there is a child of the span active in the current async context (the request span when none is), its start and end
8// are the runtime's clock, and `end()` closes it.
9//
10// `plyTracer(ctx, options)` is the one Tracer the /v1 API (src/index.js) and the viewer (src/viewer/app.tsx) construct.
11// With `ctx.tracing` it mirrors each ply span onto a platform span when ply opens it, and closes that span with ply's
12// attributes, status, and ids when ply ends it: ply hands over the ended span as plain values (Tracer `onEnd`, an
13// EndedSpan; no OTLP is built), and the platform span takes all of ply's attributes in one `setAttributes` call and the
14// stamp, ids and duration in a second. (Until 2026-11-06 this rebuilt an OTLP document per span, flattened it back and
15// made one setAttribute call per attribute: about 7% of the Worker's CPU on 59f39490.) Parentage is ply's, not whatever happens to be active: each platform span
16// is opened with `startActiveSpan`, and the async context inside that callback (where it is the active span) is kept with
17// `AsyncLocalStorage.snapshot()`. A ply child is opened inside its parent's snapshot, so the runtime makes it that span's
18// child. A ply root (`git.edit`, a bare wire span) is opened in the caller's context: a child of the request span. A span
19// that follows another (`git.read.blob` after `git.read`) nests under it while it is open.
20// Without `ctx.tracing` (node tests, a runtime without user tracing) it is ply's plain Tracer.
21import { AsyncLocalStorage } from 'node:async_hooks'
22import { Tracer } from 'ply'
23import type { EndedSpan, SpanSink } from 'ply'
24import { chainGet } from './absent.ts'
26type PlySpan = ReturnType<Tracer['start']>
27type TracerOptions = ConstructorParameters<typeof Tracer>[0]
28type StartOptions = Parameters<Tracer['start']>[1]
30/** Attribute values the platform span takes. */
31type EdgeValue = string | number | boolean
32type EdgeAttrs = Readonly<Record<string, EdgeValue>>
34/**
35 * The platform span: what `ctx.tracing.startActiveSpan` hands its callback. The runtime's span also has
36 * `setAttributes(record)` (one call for many attributes); closeEdge uses it when it is there.
37 */
38export type EdgeSpan = {
39 setAttribute(key: string, value: EdgeValue): unknown
40 setStatus(status: { code: 'ok' | 'error'; message: string }): unknown
41 end(): void
44/** `ctx.tracing`, the one method this module calls. */
45export type EdgeTracing = {
46 startActiveSpan<T>(name: string, fn: (span: EdgeSpan) => T): T
49/** Attribute keys this module adds beside ply's own. */
50export const EDGE_ATTR = {
51 spanId: 'ply.span_id',
52 traceId: 'ply.trace_id',
53 parentSpanId: 'ply.parent_span_id',
54 followsSpanId: 'ply.follows_span_id',
55 durationMs: 'ply.duration_ms',
56 /** The route the span ran under (`GET /v1/tree`, `viewer`): telemetry groups input distributions by it (#73). */
57 route: 'ply.route',
58 /** The Workers version id (`env.VERSION.id`), so a distribution is per version without a join to the request span. */
59 version: 'ply.script_version',
60} as const
62/**
63 * Attribute keys stamped on the request span (the runtime's root span for the invocation). With the route and version
64 * these are the per-request inputs scripts/calibrate reads: outcome, error, and the shape of the ply work it did.
65 */
66export const REQUEST_ATTR = {
67 route: EDGE_ATTR.route,
68 version: EDGE_ATTR.version,
69 surface: 'ply.surface',
70 status: 'http.response.status_code',
71 errorCode: 'ply.error.code',
72 errorKind: 'ply.error.kind',
73 spans: 'ply.spans',
74 roundTrips: 'ply.round_trips',
75 wide: 'ply.wide_fetches',
76 cacheHits: 'ply.cache_hits',
77 cacheMisses: 'ply.cache_misses',
78} as const
80/** Attributes every platform span of one request carries beside ply's own. */
81export type EdgeStamp = Readonly<Record<string, string | number | boolean>>
83const OTLP_ERROR = 2
84const FOLLOWS_FROM = 'follows_from'
86/** `ctx.tracing` when it can open a span, else null. A missing context is null. */
87export function edgeTracingOf(ctx: unknown): EdgeTracing | null {
88 const found = chainGet(ctx, 'tracing')
89 if (found.tag === 'none') return null
90 const start = chainGet(found.value, 'startActiveSpan')
91 if (start.tag === 'none' || typeof start.value !== 'function') return null
92 return found.value as EdgeTracing
95/** `ctx.tracing.getActiveSpan()` when the runtime has it (the request span outside any user span), else null. */
96function activeSpanOf(ctx: unknown): EdgeSpan | null {
97 const found = chainGet(ctx, 'tracing')
98 if (found.tag === 'none' || found.value === null || typeof found.value !== 'object') return null
99 const get = chainGet(found.value, 'getActiveSpan')
100 if (get.tag === 'none' || typeof get.value !== 'function') return null
101 try {
102 const span: unknown = (get.value as () => unknown).call(found.value)
103 const set = chainGet(span, 'setAttribute')
104 return set.tag === 'some' && typeof set.value === 'function' ? span as EdgeSpan : null
105 } catch {
106 return null
107 }
110/**
111 * Stamp attributes on the span active in the caller's context: the request span when called from the fetch handler.
112 * Without `ctx.tracing` (node tests) or with a runtime that refuses, nothing happens and the request goes on.
113 * Returns whether a span took the attributes.
114 */
115export function stampRequestSpan(ctx: unknown, attrs: EdgeStamp): boolean {
116 const span = activeSpanOf(ctx)
117 if (span === null) return false
118 let stamped = true
119 for (const [key, value] of Object.entries(attrs)) {
120 try { span.setAttribute(key, value) } catch { stamped = false }
121 }
122 return stamped
125/** Platform calls never fail a request: a span the runtime refuses is a span not recorded. */
126function quietly(fn: () => void): void {
127 try { fn() } catch { /* the runtime refused the span call; the request goes on */ }
130/**
131 * What the platform span takes beside ply's attributes: each array attribute as JSON (the runtime would join an array
132 * with commas; this record is set second, so its JSON replaces that), the stamp, ply's ids, the span it follows, and
133 * the duration.
134 */
135function extraAttrs(ended: EndedSpan, stamp: EdgeStamp): EdgeAttrs {
136 const out: Record<string, EdgeValue> = { ...stamp }
137 const attrs = ended.attrs
138 for (const key in attrs) {
139 const value = attrs[key]
140 if (typeof value === 'object') out[key] = JSON.stringify(value)
141 }
142 out[EDGE_ATTR.spanId] = ended.spanId
143 out[EDGE_ATTR.traceId] = ended.traceId
144 if (ended.parentSpanId !== null) out[EDGE_ATTR.parentSpanId] = ended.parentSpanId
145 const follows = ended.links.find(link => link.attrs['ply.link'] === FOLLOWS_FROM)
146 if (follows) out[EDGE_ATTR.followsSpanId] = follows.spanId
147 out[EDGE_ATTR.durationMs] = Math.round(ended.durationMs * 1000) / 1000
148 return out
151/** A runtime without `setAttributes`: one call per attribute, arrays as JSON. */
152function setEach(edge: EdgeSpan, attrs: Readonly<Record<string, unknown>>): void {
153 for (const key in attrs) {
154 const value = attrs[key]
155 edge.setAttribute(key, typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' ? value : JSON.stringify(value))
156 }
159/** ply's ended span onto the platform span: every attribute, ply's ids and duration, and an error status. */
160function closeEdge(edge: EdgeSpan, ended: EndedSpan, stamp: EdgeStamp): void {
161 quietly(() => {
162 const extra = extraAttrs(ended, stamp)
163 const bulk = chainGet(edge, 'setAttributes')
164 if (bulk.tag === 'some' && typeof bulk.value === 'function') {
165 const setAll = bulk.value as (attrs: Readonly<Record<string, unknown>>) => unknown
166 setAll.call(edge, ended.attrs)
167 setAll.call(edge, extra)
168 } else {
169 setEach(edge, ended.attrs)
170 setEach(edge, extra)
171 }
172 if (ended.status.code === OTLP_ERROR) edge.setStatus({ code: 'error', message: ended.status.message })
173 })
174 quietly(() => edge.end())
177/** A platform span, and a runner for code that must see it as the active span. */
178type Opened = {
179 readonly edge: EdgeSpan
180 readonly within: <R>(fn: () => R) => R
183/** The ply span this one nests under: its parent, else the span it follows. Null for a root. */
184function hostId(span: PlySpan): string | null {
185 if (span.parentSpanId !== null) return span.parentSpanId
186 const follows = span.links.find(link => link.attributes.some(kv => kv.key === 'ply.link' && 'stringValue' in kv.value && kv.value.stringValue === FOLLOWS_FROM))
187 return follows ? follows.spanId : null
190class EdgeTracer extends Tracer {
191 readonly #tracing: EdgeTracing
192 /** Platform spans of ply spans still open, by ply span id. */
193 readonly #open = new Map<string, Opened>()
195 constructor(options: TracerOptions, tracing: EdgeTracing, stamp: EdgeStamp) {
196 super(options)
197 this.#tracing = tracing
198 // ply calls onEnd as each span ends: close its platform span, then hand the span to the caller's onEnd.
199 const given = this.onEnd
200 const close: SpanSink = ended => {
201 const opened = this.#open.get(ended.spanId)
202 if (opened) {
203 this.#open.delete(ended.spanId)
204 closeEdge(opened.edge, ended, stamp)
205 }
206 if (given !== null) given(ended)
207 }
208 this.onEnd = close
209 }
211 override start(name: string, options: StartOptions): PlySpan {
212 const span = super.start(name, options)
213 const id = hostId(span)
214 const host = id === null ? null : this.#open.get(id)
215 const open = (): Opened | null => {
216 try {
217 return this.#tracing.startActiveSpan(name, edge => ({ edge, within: AsyncLocalStorage.snapshot() }))
218 } catch {
219 return null
220 }
221 }
222 const opened = host ? host.within(open) : open()
223 if (opened !== null) this.#open.set(span.spanId, opened)
224 return span
225 }
228/**
229 * The Tracer for one Worker request. Every span it records goes to `options.onEnd` (and to `options.exporter`, when
230 * one is given); with `ctx.tracing` each one is also a platform span under the request span (see the top of this
231 * file), carrying `stamp` (the route and version, EDGE_ATTR) beside ply's attributes. The spans ply-web keeps for
232 * itself (rays, ?trace=1, the viewer's trace) are not stamped.
233 */
234export function plyTracer(ctx: unknown, options: TracerOptions, stamp: EdgeStamp = {}): Tracer {
235 const tracing = edgeTracingOf(ctx)
236 return tracing === null ? new Tracer(options) : new EdgeTracer(options, tracing, stamp)
239/** The spans one request keeps (its stats, ?trace=1, the rays join, the viewer's trace), as ply ended them. */
240export type SpanList = { readonly spans: EndedSpan[]; readonly onEnd: SpanSink }
242/** A fresh SpanList: pass `onEnd` to the request's Tracer. Each span is ply's plain-value form; no OTLP is built. */
243export function spanList(): SpanList {
244 const spans: EndedSpan[] = []
245 return { spans, onEnd: ended => { spans.push(ended) } }
248/** Pack-cache outcome on a ply span: `git.response.cache` / `git.pack.cache` (x-ply-pack-cache), or the from_cache flag. */
249export type CacheStats = {
250 readonly spans: number
251 readonly rtt: number
252 readonly wide: number
253 readonly cache_hits: number
254 readonly cache_misses: number
257function packCacheStatus(attrs: Readonly<Record<string, unknown>>): string {
258 // Prefer a non-empty stamp: '' / missing falls through (same as the prior || chain in index.js).
259 for (const key of ['git.response.cache', 'git.pack.cache'] as const) {
260 const raw = attrs[key]
261 if (typeof raw === 'string' && raw !== '') return raw
262 }
263 return ''
266/**
267 * Aggregate ply span outcomes into the request-span counters. Hits/misses come from child pack-cache
268 * spans (`git.pack.cache` / `git.response.cache`), not from an empty CF cache status on the parent.
269 * `NONE` and `''` are unstamped and ignored; `http.response.headers.from_cache` counts as a hit.
270 */
271export function cacheStatsOf(spans: readonly EndedSpan[]): CacheStats {
272 let hits = 0
273 let misses = 0
274 for (const span of spans) {
275 const attrs = span.attrs
276 const status = packCacheStatus(attrs)
277 if (status === 'HIT' || attrs['http.response.headers.from_cache'] === true) hits += 1
278 else if (status === 'MISS' || status === 'EXPIRED' || status === 'BYPASS' || status === 'BUST') misses += 1
279 }
280 return {
281 spans: spans.length,
282 rtt: spans.filter(x => /^git\.(upload-pack|receive-pack)/.test(x.name)).length,
283 wide: spans.filter(x => Boolean(x.attrs['git.fetch.filter.fallback'])).length,
284 cache_hits: hits,
285 cache_misses: misses,
286 }
289/** The route and version stamp for one request. A missing version id (local dev, tests) is left out, not faked. */
290export function routeStamp(route: string, version: string | null): EdgeStamp {
291 return version === null || version === '' ? { [EDGE_ATTR.route]: route } : { [EDGE_ATTR.route]: route, [EDGE_ATTR.version]: version }
294/** What the request log line already carries (src/index.js `done`): the code on a failure, and ply's span counts. */
295type RequestLog = Readonly<Record<string, unknown>>
297const LOGGED_COUNTS = [
298 ['spans', REQUEST_ATTR.spans],
299 ['rtt', REQUEST_ATTR.roundTrips],
300 ['wide', REQUEST_ATTR.wide],
301 ['cache_hits', REQUEST_ATTR.cacheHits],
302 ['cache_misses', REQUEST_ATTR.cacheMisses],
303] as const
305/**
306 * The request span's attributes: route, version, surface, status, and from the log line the error code and kind and
307 * ply's counts. Only finite numbers and non-empty strings are copied; a field the log does not have is left out.
308 */
309export function requestStamp(input: { readonly route: string; readonly version: string | null; readonly surface: string; readonly status: number; readonly log: RequestLog }): EdgeStamp {
310 const out: Record<string, string | number | boolean> = { ...routeStamp(input.route, input.version), [REQUEST_ATTR.surface]: input.surface, [REQUEST_ATTR.status]: input.status }
311 const code = input.log.code
312 if (typeof code === 'string' && code !== '') out[REQUEST_ATTR.errorCode] = code
313 const kind = input.log.error_kind
314 if (typeof kind === 'string' && kind !== '') out[REQUEST_ATTR.errorKind] = kind
315 for (const [from, to] of LOGGED_COUNTS) {
316 const value = input.log[from]
317 if (typeof value === 'number' && Number.isFinite(value)) out[to] = value
318 }
319 return out
Diagnostics4 git calls · 30 ms
CallStatusSizeTime030 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 · hit4 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=4
git.response.bytes=145
git.response.cache=HIT
git.response.duration_ms=4
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=2
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
fetch2005.0 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=5075
git.response.cache=HIT
git.response.duration_ms=23
git.fetch.wants=5bb815e879035304ba3c5ff3b4e71312789d3ff4
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=5075
git.pkt.payload.max=5054
git.sideband.band1.bytes=5053
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
a5e2e9fb8fe44bc2
Request
dc4df6f1…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format