Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

5.0 KB
Raw Blame
import type { Attributes, Counter, Histogram } from '@opentelemetry/api';
import { getMeter, withSpan, withSpanSync } from './telemetry.ts';

export type IndexName = 'backlink' | 'tag' | 'local-target';

export type IndexRebuildMode = 'full' | 'reconcile';

export type IndexUpdateMode = 'source' | 'document-target' | 'file-target';

export type IndexPublicationMode = 'signal' | 'baseline';

let _rebuildCounter: Counter | null = null;
function rebuildCounter(): Counter {
  _rebuildCounter ||= getMeter().createCounter('ok.index.rebuild_total', {
    description:
      'Count of derived-index rebuild passes. Bounded labels: index.name ∈ {backlink, tag, local-target}, index.mode ∈ {full, reconcile}.',
  });
  return _rebuildCounter;
}

let _rebuildDurationHist: Histogram | null = null;
function rebuildDurationHist(): Histogram {
  _rebuildDurationHist ||= getMeter().createHistogram('ok.index.rebuild_duration_ms', {
    description:
      'Duration of derived-index rebuild passes in milliseconds. Same bounded label pair as ok.index.rebuild_total.',
    unit: 'ms',
  });
  return _rebuildDurationHist;
}

let _updateCounter: Counter | null = null;
function updateCounter(): Counter {
  _updateCounter ||= getMeter().createCounter('ok.index.update_total', {
    description:
      'Count of incremental derived-index updates. Bounded labels: index.name and index.mode.',
  });
  return _updateCounter;
}

let _updateDurationHist: Histogram | null = null;
function updateDurationHist(): Histogram {
  _updateDurationHist ||= getMeter().createHistogram('ok.index.update_duration_ms', {
    description: 'Duration of incremental derived-index updates in milliseconds.',
    unit: 'ms',
  });
  return _updateDurationHist;
}

let _occurrenceCountHist: Histogram | null = null;
function occurrenceCountHist(): Histogram {
  _occurrenceCountHist ||= getMeter().createHistogram('ok.index.occurrence_count', {
    description: 'Local-target occurrences processed by an index operation.',
    unit: '{occurrence}',
  });
  return _occurrenceCountHist;
}

let _affectedSourceCountHist: Histogram | null = null;
function affectedSourceCountHist(): Histogram {
  _affectedSourceCountHist ||= getMeter().createHistogram('ok.index.affected_source_count', {
    description: 'Source documents whose assessment changed during an index operation.',
    unit: '{source}',
  });
  return _affectedSourceCountHist;
}

let _generationLagHist: Histogram | null = null;
function generationLagHist(): Histogram {
  _generationLagHist ||= getMeter().createHistogram('ok.index.generation_lag', {
    description: 'Index generations accumulated between consumer publications.',
    unit: '{generation}',
  });
  return _generationLagHist;
}

function recordBoundedMeasurements(attrs: Attributes, labels: Attributes): void {
  const occurrences = attrs['index.occurrences'];
  if (typeof occurrences === 'number') occurrenceCountHist().record(occurrences, labels);
  const affectedSources = attrs['index.affected_sources'];
  if (typeof affectedSources === 'number') {
    affectedSourceCountHist().record(affectedSources, labels);
  }
}

export function recordIndexGenerationLag(
  name: IndexName,
  publication: IndexPublicationMode,
  lag: number,
): void {
  generationLagHist().record(lag, { 'index.name': name, 'index.publication': publication });
}

export async function instrumentIndexRebuild<T>(
  name: IndexName,
  mode: IndexRebuildMode,
  fn: () => Promise<T>,
  resultAttrs?: (result: T) => Attributes,
): Promise<T> {
  return withSpan(
    'ok.index.rebuild',
    { attributes: { 'index.name': name, 'index.mode': mode } },
    async (span) => {
      const start = performance.now();
      try {
        const result = await fn();
        if (resultAttrs) {
          const attrs = resultAttrs(result);
          span.setAttributes(attrs);
          recordBoundedMeasurements(attrs, { 'index.name': name, 'index.mode': mode });
        }
        return result;
      } finally {
        const attrs = { 'index.name': name, 'index.mode': mode };
        rebuildCounter().add(1, attrs);
        rebuildDurationHist().record(performance.now() - start, attrs);
      }
    },
  );
}

export function instrumentIndexUpdate<T>(
  name: IndexName,
  mode: IndexUpdateMode,
  fn: () => T,
  resultAttrs: (result: T) => Attributes,
): T {
  const labels = { 'index.name': name, 'index.mode': mode };
  return withSpanSync('ok.index.update', { attributes: labels }, (span) => {
    const start = performance.now();
    try {
      const result = fn();
      const attrs = resultAttrs(result);
      span.setAttributes(attrs);
      recordBoundedMeasurements(attrs, labels);
      return result;
    } finally {
      updateCounter().add(1, labels);
      updateDurationHist().record(performance.now() - start, labels);
    }
  });
}

export function __resetIndexTelemetryForTests(): void {
  _rebuildCounter = null;
  _rebuildDurationHist = null;
  _updateCounter = null;
  _updateDurationHist = null;
  _occurrenceCountHist = null;
  _affectedSourceCountHist = null;
  _generationLagHist = null;
}