Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): stop the idle file-existence sweep emitting a span per file (PRD-8281) (#3847)
Andrew Mikofalvyeba9121409d5
diff --git a/.changeset/idle-index-sweep-span-volume.md b/.changeset/idle-index-sweep-span-volume.mdnew file mode 100644index 000000000..c80c7b893--- /dev/null+++ b/.changeset/idle-index-sweep-span-volume.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++Diagnostic bundles now cover a useful window of time on projects with many linked files. The background sweep that repairs dropped file-watcher events re-checks every referenced file target every few seconds, and it was recording a telemetry span for each one even when nothing had changed. On a large project that is thousands of empty spans a minute, enough to fill the fixed-size local span buffer and recycle it while the user was still reproducing the problem, so a bug report often arrived carrying telemetry that no longer reached back to the failure being reported. Existence checks that find nothing to repair no longer record anything, so an idle project produces no index-update spans at all.diff --git a/packages/server/src/local-target-index-telemetry.test.ts b/packages/server/src/local-target-index-telemetry.test.tsnew file mode 100644index 000000000..5f5063590--- /dev/null+++ b/packages/server/src/local-target-index-telemetry.test.ts@@ -0,0 +1,163 @@+import { mkdirSync, mkdtempSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { dirname, join } from 'node:path';+import { context, metrics, trace } from '@opentelemetry/api';+import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';+import {+ BasicTracerProvider,+ InMemorySpanExporter,+ SimpleSpanProcessor,+} from '@opentelemetry/sdk-trace-base';+import { afterEach, beforeEach, describe, expect, test } from 'vitest';+import { createContentFilter } from './content-filter.ts';+import { __resetIndexTelemetryForTests } from './index-telemetry.ts';+import { LocalTargetIndex } from './local-target-index.ts';++let exporter: InMemorySpanExporter;+let provider: BasicTracerProvider;+const cleanups: Array<() => void> = [];++beforeEach(() => {+ exporter = new InMemorySpanExporter();+ provider = new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] });+ trace.setGlobalTracerProvider(provider);+ context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable());+ __resetIndexTelemetryForTests();+});++afterEach(async () => {+ for (const cleanup of cleanups.splice(0)) cleanup();+ await provider.shutdown();+ trace.disable();+ metrics.disable();+ context.disable();+ __resetIndexTelemetryForTests();+});++/** The `ok.index.update` spans finished since the last `exporter.reset()`. */+function updateSpans(): ReadonlyArray<{ attributes: Record<string, unknown> }> {+ return exporter+ .getFinishedSpans()+ .filter((span) => span.name === 'ok.index.update')+ .map((span) => ({ attributes: span.attributes as Record<string, unknown> }));+}++function createDiskRig(): {+ index: LocalTargetIndex;+ contentDir: string;+ write: (rel: string, body: string) => void;+} {+ const projectDir = mkdtempSync(join(tmpdir(), 'ok-lti-telemetry-'));+ const contentDir = join(projectDir, 'content');+ mkdirSync(contentDir, { recursive: true });+ const contentFilter = createContentFilter({ projectDir, contentDir });+ const index = new LocalTargetIndex({ contentDir, contentFilter });+ cleanups.push(() => {+ index.close();+ rmSync(projectDir, { recursive: true, force: true });+ });+ const write = (rel: string, body: string): void => {+ const filePath = join(contentDir, rel);+ mkdirSync(dirname(filePath), { recursive: true });+ writeFileSync(filePath, body);+ };+ return { index, contentDir, write };+}++describe('local-target index update telemetry is proportional to real work', () => {+ test('an idle dependent-file sweep emits no ok.index.update spans', async () => {+ const rig = createDiskRig();+ rig.write('source.md', 'See [a](assets/a.pdf), [b](assets/b.pdf), [c](assets/c.pdf).\n');+ for (const name of ['a', 'b', 'c']) rig.write(`assets/${name}.pdf`, '%PDF-1.4\n');+ await rig.index.rebuildFromDisk({+ documentTargets: ['source'],+ fileTargets: ['assets/a.pdf', 'assets/b.pdf', 'assets/c.pdf'],+ });++ // Steady state: disk agrees with the index, so the repair sweep has nothing+ // to repair. This is what an idle project does every few seconds, forever.+ exporter.reset();+ expect(await rig.index.reconcileDependentFileTargetsFromDisk()).toBe(0);+ expect(await rig.index.reconcileDependentFileTargetsFromDisk()).toBe(0);++ // One span per referenced target per sweep is what recycles the span ring+ // before a bug report's own evidence can reach it.+ expect(updateSpans()).toEqual([]);+ });++ test('a sweep that repairs a dropped watcher event still emits its span', async () => {+ const rig = createDiskRig();+ rig.write('source.md', 'Download [pdf](assets/report.pdf).\n');+ rig.write('assets/report.pdf', '%PDF-1.4\n');+ await rig.index.rebuildFromDisk({+ documentTargets: ['source'],+ fileTargets: ['assets/report.pdf'],+ });++ unlinkSync(join(rig.contentDir, 'assets/report.pdf'));+ exporter.reset();+ expect(await rig.index.reconcileDependentFileTargetsFromDisk()).toBe(1);++ expect(updateSpans()).toEqual([+ {+ attributes: {+ 'index.name': 'local-target',+ 'index.mode': 'file-target',+ 'index.occurrences': 1,+ 'index.affected_sources': 1,+ },+ },+ ]);+ });++ test('a sweep repairing two dropped events emits one span per repaired target', async () => {+ const rig = createDiskRig();+ rig.write('source.md', 'See [a](assets/a.pdf) and [b](assets/b.pdf).\n');+ for (const name of ['a', 'b']) rig.write(`assets/${name}.pdf`, '%PDF-1.4\n');+ await rig.index.rebuildFromDisk({+ documentTargets: ['source'],+ fileTargets: ['assets/a.pdf', 'assets/b.pdf'],+ });++ unlinkSync(join(rig.contentDir, 'assets/a.pdf'));+ unlinkSync(join(rig.contentDir, 'assets/b.pdf'));+ exporter.reset();+ expect(await rig.index.reconcileDependentFileTargetsFromDisk()).toBe(2);++ // One span per repaired target, not one per sweep: batching the loop into a+ // single span would still satisfy the zero-repair and one-repair cases above.+ expect(updateSpans()).toHaveLength(2);+ });++ test('setFileTarget spans the existence flip and nothing either side of it', () => {+ const index = new LocalTargetIndex({ contentDir: join(tmpdir(), 'ok-lti-telemetry-absent') });+ cleanups.push(() => index.close());+ index.setSource('source', 'Download [pdf](assets/report.pdf).\n');++ exporter.reset();+ expect(index.setFileTarget('assets/report.pdf', false)).toBe(0);+ expect(updateSpans()).toEqual([]);++ expect(index.setFileTarget('assets/report.pdf', true)).toBe(1);+ expect(updateSpans()).toHaveLength(1);++ exporter.reset();+ expect(index.setFileTarget('assets/report.pdf', true)).toBe(0);+ expect(updateSpans()).toEqual([]);+ });++ test('reconcileFileTargets spans a moved snapshot and not an identical one', () => {+ const index = new LocalTargetIndex({ contentDir: join(tmpdir(), 'ok-lti-telemetry-absent') });+ cleanups.push(() => index.close());+ index.setSource('source', 'Download [pdf](assets/report.pdf).\n');++ exporter.reset();+ expect(index.reconcileFileTargets(['assets/report.pdf'])).toBe(1);+ expect(updateSpans()).toHaveLength(1);++ // The watcher re-publishes the same inventory: no identity moved.+ exporter.reset();+ expect(index.reconcileFileTargets(['assets/report.pdf'])).toBe(0);+ expect(updateSpans()).toEqual([]);+ });+});diff --git a/packages/server/src/local-target-index.ts b/packages/server/src/local-target-index.tsindex 8178c7cb7..1452fb790 100644--- a/packages/server/src/local-target-index.ts+++ b/packages/server/src/local-target-index.ts@@ -484,12 +484,16 @@ export class LocalTargetIndex {* Returns the number of sources reassessed (bounded telemetry).*/setFileTarget(relativePath: string, exists: boolean): number {+ // Deliberately ahead of the span: the dependent-file repair sweep re-checks+ // every referenced target on a fixed interval, so instrumenting the unflipped+ // case bills one span per referenced file per sweep on a project that is+ // doing nothing. Left inside, that volume recycles the local span ring faster+ // than a user can file a report about anything else.+ if (this.files.has(relativePath) === exists) return 0;const update = instrumentIndexUpdate('local-target','file-target',() => {- const present = this.files.has(relativePath);- if (exists === present) return { affected: 0, occurrences: 0 };if (exists) this.files.add(relativePath);else this.files.delete(relativePath);const occurrences = this.countFileOccurrences(relativePath);@@ -571,18 +575,25 @@ export class LocalTargetIndex {/** Replace ordinary-file existence from an authoritative alias-complete snapshot. */reconcileFileTargets(fileTargets: Iterable<string>): number {+ const next = new Set(fileTargets);+ const changedIdentities = new Set<string>();+ for (const relativePath of this.files) {+ if (!next.has(relativePath)) changedIdentities.add(relativePath);+ }+ for (const relativePath of next) {+ if (!this.files.has(relativePath)) changedIdentities.add(relativePath);+ }+ // Same discipline as `setFileTarget`: a re-published identical inventory+ // moved no identity, so it is not an update and is not instrumented as one.+ // Deciding that ahead of the span also puts the diff outside the timed+ // region, so the duration histogram measures the reassessment tail rather+ // than the whole call. Read it that way — as full-call cost it under-reports.+ if (changedIdentities.size === 0) return 0;+return instrumentIndexUpdate('local-target','file-target',() => {- const next = new Set(fileTargets);- const changedIdentities = new Set<string>();- for (const relativePath of this.files) {- if (!next.has(relativePath)) changedIdentities.add(relativePath);- }- for (const relativePath of next) {- if (!this.files.has(relativePath)) changedIdentities.add(relativePath);- }const affected = new Set<string>();let occurrences = 0;for (const relativePath of changedIdentities) {