main
1// One flags.eval span per resolution batch, plus a flags.resolve child per flag.
2// The unit id is a parent-span attribute only. The log lines are the low-cardinality projection the
3// observability script aggregates: cache status, revision, durations, and the resolved variant.
4import { chainGet, fromNullable } from '../absent.ts';
5import { type Option } from '../option.ts';
6import { roundMs } from './clock.ts';
7import { variantKind, variantValue, type CacheStatus, type FlagEvaluation } from './types.ts';
9export { CACHE_STATUSES } from './types.ts';
11export type ResolutionSample = {
12 readonly key: string;
13 readonly variantKind: string;
14 readonly variantValue: string;
15 readonly reason: FlagEvaluation['reason'];
16 readonly bucket: number;
17};
19export type EvalSample = {
20 readonly cacheStatus: CacheStatus;
21 readonly revision: string | null;
22 /** Pure evaluation. On Workers this stays 0: the clock does not move until the isolate yields. */
23 readonly evalMs: number;
24 /**
25 * Wall time of the awaited FlagsCache read that preceded evaluation.
26 * A hit is the cache lookup. A miss, stale, or revalidation includes the R2 read inside that await.
27 * This is the duration flags-o11y percentiles. It is not the pure hash.
28 */
29 readonly resolveMs: number;
30 readonly r2ReadMs: number | null;
31 readonly unitId: string | null;
32 readonly resolutions: readonly ResolutionSample[];
33};
35export type SpanLike = {
36 setAttribute?(key: string, value: string | number | boolean): void;
37 end?(): void;
38};
40export type TracingLike = {
41 /** The runtime's form (workerd `ctx.tracing.startSpan`): a child of the active span, open until `end()`. Preferred. */
42 startSpan?(name: string): SpanLike;
43 /**
44 * One-argument form, same as the viewer: the span stays open until `end()`.
45 * A callback form would close before an await, and the Workers clock would record 0.
46 */
47 enterSpan?(name: string): SpanLike;
48};
50/** Optional method call. A null receiver or a null method does not run. A present method keeps its receiver. */
51function callMethod(receiver: unknown, key: string, args: readonly unknown[]): void {
52 const host = fromNullable(receiver);
53 if (host.tag === 'none') return;
54 const method = chainGet(host.value, key);
55 if (method.tag === 'none') return;
56 const fn = method.value as (...params: unknown[]) => unknown;
57 fn.apply(host.value, [...args]);
58}
60function setAttribute(span: SpanLike | null, key: string, value: string | number | boolean): void {
61 callMethod(span, 'setAttribute', [key, value]);
62}
64function revisionText(revision: string | null): string {
65 return revision === null ? '' : revision;
66}
68export function openSpan(tracing: TracingLike | null, name: string): SpanLike | null {
69 if (tracing === null) return null;
70 // workerd's ctx.tracing: startSpan(name) stays open until end(). Its enterSpan takes a callback (enterSpan.length is 0
71 // there), so before startSpan was read here the runtime got no span at all.
72 const start = chainGet(tracing, 'startSpan');
73 if (start.tag === 'some' && typeof start.value === 'function') {
74 const span = (start.value as (spanName: string) => unknown).call(tracing, name);
75 return span ? span as SpanLike : null;
76 }
77 // The one-argument form stays open until end(). A platform enterSpan that requires a callback
78 // (workerd: parameter 2 must be a Function) is not this form; skip it instead of failing the request.
79 const enter = chainGet(tracing, 'enterSpan');
80 if (enter.tag === 'none' || typeof enter.value !== 'function' || enter.value.length !== 1) return null;
81 const enterFn = enter.value as (spanName: string) => unknown;
82 const span = enterFn.call(tracing, name);
83 return span ? span as SpanLike : null;
84}
86export function endSpan(span: SpanLike | null): void {
87 callMethod(span, 'end', []);
88}
90export function resolutionSample(evaluation: FlagEvaluation): ResolutionSample {
91 return {
92 key: evaluation.key,
93 variantKind: variantKind(evaluation.variant),
94 variantValue: variantValue(evaluation.variant),
95 reason: evaluation.reason,
96 bucket: evaluation.bucket,
97 };
98}
100function num(value: number): number {
101 return roundMs(value);
102}
104/** Log lines only. No unit id, so a query grouped by these fields stays low-cardinality. */
105export function evalLog(sample: EvalSample): string {
106 return JSON.stringify({
107 msg: 'flags.eval',
108 cache_status: sample.cacheStatus,
109 revision: sample.revision,
110 eval_ms: num(sample.evalMs),
111 resolve_ms: num(sample.resolveMs),
112 r2_read_ms: sample.r2ReadMs,
113 flag_count: sample.resolutions.length,
114 });
115}
117export function resolveLog(sample: EvalSample, resolution: ResolutionSample): string {
118 return JSON.stringify({
119 msg: 'flags.resolve',
120 key: resolution.key,
121 variant_kind: resolution.variantKind,
122 variant_value: resolution.variantValue,
123 reason: resolution.reason,
124 bucket: resolution.bucket,
125 revision: sample.revision,
126 cache_status: sample.cacheStatus,
127 resolve_ms: num(sample.resolveMs),
128 });
129}
131export function emitEval(
132 tracing: TracingLike | null,
133 sample: EvalSample,
134 log: (line: string) => void,
135 parent: Option<SpanLike | null>,
136): void {
137 const write = (span: SpanLike | null): void => {
138 setAttribute(span, 'flags.cache_status', sample.cacheStatus);
139 setAttribute(span, 'flags.revision', revisionText(sample.revision));
140 setAttribute(span, 'flags.eval_ms', num(sample.evalMs));
141 setAttribute(span, 'flags.resolve_ms', num(sample.resolveMs));
142 setAttribute(span, 'flags.count', sample.resolutions.length);
143 if (sample.r2ReadMs !== null) setAttribute(span, 'flags.r2_read_ms', sample.r2ReadMs);
144 if (sample.unitId !== null) setAttribute(span, 'flags.unit_id', sample.unitId);
145 log(evalLog(sample));
146 for (const resolution of sample.resolutions) {
147 const child = openSpan(tracing, 'flags.resolve');
148 try {
149 setAttribute(child, 'flags.key', resolution.key);
150 setAttribute(child, 'flags.variant_kind', resolution.variantKind);
151 setAttribute(child, 'flags.variant_value', resolution.variantValue);
152 setAttribute(child, 'flags.reason', resolution.reason);
153 setAttribute(child, 'flags.bucket', resolution.bucket);
154 setAttribute(child, 'flags.revision', revisionText(sample.revision));
155 setAttribute(child, 'flags.cache_status', sample.cacheStatus);
156 setAttribute(child, 'flags.resolve_ms', num(sample.resolveMs));
157 log(resolveLog(sample, resolution));
158 } finally {
159 endSpan(child);
160 }
161 }
162 };
163 // none: this call owns the eval span. some: the caller already opened it, including a null span.
164 if (parent.tag === 'some') {
165 write(parent.value);
166 return;
167 }
168 const span = openSpan(tracing, 'flags.eval');
169 try {
170 write(span);
171 } finally {
172 endSpan(span);
173 }
174}
Diagnostics4 git calls · 348 ms
CallStatusSizeTime0348 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 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 · hit2 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=2 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=61Open pack map
fetch2002.1 KiB343 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=343 git.response.bytes=2197 git.response.cache=MISS git.response.duration_ms=343 git.fetch.wants=a37058778930d8812e84d8c2a9008bcc4546b518 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=2197 git.pkt.payload.max=2176 git.sideband.band1.bytes=2175 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
- a5e2e56acfce2947
- Request
- 7f84250f…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format