telemetry off or local-only unless user opts in

{
  "telemetry": {
    "enabled": false,
    "mode": "local",
    "anonymousId": true,
    "collect": {
      "usage": true,
      "performance": true,
      "quality": true,
      "errors": true,
      "aiCost": true,
      "searchQueries": false,
      "pageFeedback": false
    },
    "privacy": {
      "sendFilePaths": false,
      "sendSourceContent": false,
      "sendPrompts": false,
      "sendModelOutputs": false,
      "redactSecrets": true
    }
  }
}

export type ObservabilitySignal =
  | LogRecord
  | MetricPoint
  | TraceSpan
  | ProductEvent
  | QualityEvent
  | AiEvent
  | WorkflowEvent
  | SecurityEvent;

export type LogRecord = {
  timestamp: string;
  level: "debug" | "info" | "warn" | "error";
  message: string;
  code?: string;
  command?: string;
  runId?: string;
  projectId?: string;
  fields?: Record<string, unknown>;
};

export type MetricPoint = {
  name: string;
  value: number;
  unit: "count" | "ms" | "bytes" | "ratio" | "usd";
  timestamp: string;
  tags?: Record<string, string>;
};

docforge.build.duration_ms
docforge.scan.files_count
docforge.cache.hit_ratio
docforge.mdx.compile.errors
docforge.ai.calls
docforge.ai.estimated_cost_usd
docforge.quality.broken_links
docforge.workflow.review_required
docforge.examples.pass_ratio

export type TraceSpan = {
  traceId: string;
  spanId: string;
  parentSpanId?: string;
  name: string;
  category: WorkCategory;
  startTime: string;
  endTime?: string;
  durationMs?: number;
  status: "ok" | "error" | "cancelled";
  attributes?: Record<string, string | number | boolean>;
};

build
  scan.filesystem 1.2s
  index.openapi 0.8s
  mdx.compile 3.4s
  render.static 2.1s
  search.index 1.7s
  llms.export 0.4s

export type ProductEvent = {
  type: string;
  timestamp: string;
  anonymousUserId?: string;
  projectFingerprint?: string;
  properties: Record<string, unknown>;
};

command.invoked
project.initialized
build.completed
update.dry_run.completed
update.apply.completed
mcp.started
llms.generated
plugin.enabled

projectId = config.projectId

projectFingerprint = sha256(normalizedProjectRootSalted)

export type TelemetryIdentity = {
  anonymousInstallationId: string;
  createdAt: string;
};

export type CommandUsageEvent = {
  command: string;
  flags: string[];
  durationMs: number;
  exitCode: number;
  mode?: "dev" | "ci" | "local";
};

{
  "command": "build",
  "flags": ["--strict", "--profile"],
  "durationMs": 18400,
  "exitCode": 0
}

{
  "out": "/Users/alice/private-client/docs-dist"
}

export type BuildObservabilityReport = {
  runId: string;
  command: "build";
  status: "success" | "warning" | "failed";
  durationMs: number;
  pages: number;
  virtualPages: number;
  diagnostics: DiagnosticSummary;
  cache: CacheSummary;
  performance: PerformanceReport;
  output: BuildOutputSummary;
};

Build completed with warnings

Pages: 482
Virtual API pages: 311
Duration: 18.4s
Cache hit rate: 81%
Warnings: 7
Output: dist/

export type DiagnosticSummary = {
  total: number;
  bySeverity: Record<DiagnosticSeverity, number>;
  byCode: Record<string, number>;
  topFiles?: Array<{ pathHash: string; count: number }>;
};

export type QualityAnalyticsSnapshot = {
  timestamp: string;
  pages: number;
  brokenInternalLinks: number;
  brokenExternalLinks: number;
  stalePublicPages: number;
  unsupportedGeneratedClaims: number;
  verifiedExamples: number;
  failedExamples: number;
  apiCoverageRatio: number;
  cliCoverageRatio: number;
  configCoverageRatio: number;
  searchMrr?: number;
  searchRecallAt5?: number;
};

Quality trend, last 7 runs:

Broken internal links:  4 -> 0
Stale public pages:     8 -> 1
Verified examples:      82% -> 94%
Search MRR:             0.76 -> 0.83

export type AiCallEvent = {
  jobId: string;
  role: "planner" | "writer" | "reviewer" | "repair" | "summarizer";
  provider: string;
  model: string;
  promptContractVersion: string;
  inputTokenEstimate?: number;
  outputTokenEstimate?: number;
  estimatedCostUsd?: number;
  durationMs: number;
  status: "success" | "schema_error" | "review_failed" | "provider_error";
  retries: number;
};

export type AiGenerationFunnel = {
  plannedPages: number;
  evidencePacksCreated: number;
  writerCalls: number;
  schemaValidOutputs: number;
  repairedOutputs: number;
  factCheckPasses: number;
  reviewApprovals: number;
  appliedPages: number;
};

export type AiCostReport = {
  runId: string;
  calls: number;
  inputTokens: number;
  outputTokens: number;
  estimatedCostUsd: number;
  byRole: Record<string, {
    calls: number;
    estimatedCostUsd: number;
  }>;
};

docforge generate --cost-report

AI cost estimate

Planner:   4 calls   $0.03
Writer:   12 calls   $0.42
Reviewer: 12 calls   $0.18
Repair:    2 calls   $0.04
Total:    30 calls   $0.67

export type WorkflowAnalyticsEvent = {
  mode: WorkflowMode;
  trigger: WorkflowTrigger["type"];
  changedFiles: number;
  semanticChanges: number;
  affectedPages: number;
  patchesGenerated: number;
  patchesApplied: number;
  reviewRequired: number;
  conflicts: number;
  durationMs: number;
};

export type ReviewDebtMetric = {
  openReviewArtifacts: number;
  highRiskItems: number;
  oldestAgeDays: number;
  byReason: Record<string, number>;
};

docforge workflow status

Review debt:
  open artifacts: 6
  high risk: 2
  oldest: 9 days

Top reasons:
  manual page stale: 3
  human-edited generated block: 2
  unsupported AI claim: 1

export type SearchTelemetryEvent = {
  queryHash?: string;
  normalizedQuery?: string;
  resultCount: number;
  clickedRoute?: RoutePath;
  clickedRank?: number;
  noResult: boolean;
  timestamp: string;
};

Search insights

No-result queries:
- "deploy cloudflare" 12 times
- "output folder" 9 times
- "mcp config" 7 times

Recommendations:
- Add alias "output folder" to build.outputDir.
- Create deployment guide for Cloudflare.

export type PageFeedbackEvent = {
  route: RoutePath;
  rating: "positive" | "negative";
  reason?: "outdated" | "unclear" | "missing" | "wrong" | "other";
  comment?: string;
};

export type CodeCopyEvent = {
  route: RoutePath;
  blockId: string;
  language: string;
  kind: CodeExampleKind;
  verified: boolean;
};

export type McpAnalyticsEvent = {
  tool: string;
  durationMs: number;
  status: "ok" | "error" | "denied";
  resultCount?: number;
  responseChars?: number;
  truncated?: boolean;
};

export type SecurityEvent = {
  type:
    | "secret_detected"
    | "unsafe_command_blocked"
    | "remote_ref_blocked"
    | "private_output_blocked"
    | "mcp_request_denied"
    | "plugin_denied";
  severity: "info" | "warning" | "error";
  timestamp: string;
  code: string;
  redacted: boolean;
};

Security summary

Secrets blocked: 2
Unsafe examples blocked: 3
Remote refs blocked: 1
Private pages excluded from public build: 4
MCP denied requests: 0

export type PluginTelemetryEvent = {
  pluginId: string;
  hook: string;
  durationMs: number;
  status: "success" | "failed" | "denied";
  diagnostics: number;
};

Plugin timings:
- @docforge/plugin-spring: 2.4s
- @acme/plugin-internal-api: 8.7s warning

export type DeploymentAnalyticsEvent = {
  adapter: string;
  target: "preview" | "production";
  filesUploaded: number;
  bytesUploaded: number;
  cacheHits?: number;
  durationMs: number;
  status: "success" | "failed";
};

.docforge/reports/
  build-report.json
  quality-report.json
  performance-report.json
  ai-cost-report.json
  workflow-report.json
  security-report.json

CREATE TABLE telemetry_events (
  id TEXT PRIMARY KEY,
  type TEXT NOT NULL,
  timestamp TEXT NOT NULL,
  payload_json TEXT NOT NULL
);

CREATE INDEX idx_telemetry_events_type_time ON telemetry_events(type, timestamp);

{
  "telemetry": {
    "localRetentionDays": 30
  }
}

export function prepareTelemetryEvent(
  event: ProductEvent,
  policy: TelemetryPrivacyPolicy
): ProductEvent | undefined {
  if (!policy.enabled) return undefined;

  const redacted = redactEvent(event, policy);
  const sampled = applySampling(redacted, policy);

  return sampled;
}

export function redactPath(path: string): string {
  return `<path:${sha256(path).slice(0, 8)}>`;
}

export type SamplingPolicy = {
  defaultRate: number;
  byEventType?: Record<string, number>;
};

export type TelemetryExporter = {
  name: string;
  export(events: ProductEvent[]): Promise<void>;
  flush(): Promise<void>;
};

docforge build --events ndjson

{"type":"command.started","command":"build"}
{"type":"build.stage.finished","stage":"mdx.compile","durationMs":3200}
{"type":"quality.finished","errors":0,"warnings":4}
{"type":"command.finished","exitCode":0,"durationMs":18400}

docforge analytics report

DocForge analytics, last 30 days

Commands:
  build: 182
  dev: 94
  update: 38
  check: 121

Quality:
  average broken links: 0.4
  stale public pages: 0 current
  example pass rate: 96%

Performance:
  median warm build: 8.2s
  p95 warm build: 21.4s

AI:
  calls: 412
  estimated cost: $9.82
  review rejection rate: 8%

init -> first dev -> first build -> search enabled -> openapi enabled -> update workflow -> GitHub integration -> llms/MCP enabled

export type ProductFunnelStage =
  | "projectInitialized"
  | "firstDevStarted"
  | "firstBuildSucceeded"
  | "searchEnabled"
  | "openApiConfigured"
  | "qualityGateConfigured"
  | "updateWorkflowUsed"
  | "githubIntegrationUsed"
  | "llmsGenerated"
  | "mcpStarted";

export type FeatureAdoptionSnapshot = {
  searchEnabled: boolean;
  openApiSpecsCount: number;
  aiEnabled: boolean;
  githubEnabled: boolean;
  llmsEnabled: boolean;
  mcpEnabled: boolean;
  pluginsCount: number;
  deploymentAdapter?: string;
};

export type AlertRule = {
  id: string;
  metric: string;
  condition: "above" | "below" | "equals";
  threshold: number;
  severity: "warning" | "critical";
};

.docforge/reports/
  ci-summary.md
  ci-docs-report.json
  performance-report.json
  quality-report.json

/__docforge/health
/__docforge/metrics
/__docforge/quality
/__docforge/performance

export type DocsSiteAnalyticsAdapter = {
  renderScript(config: unknown): string;
  trackEvent(event: DocumentationTelemetryEvent): void;
};

export type AnalyticsRecommendation = {
  id: string;
  category: "search" | "quality" | "performance" | "ai" | "workflow" | "content";
  severity: "info" | "warning" | "critical";
  message: string;
  evidence: string[];
  suggestedCommand?: string;
};

{
  "category": "search",
  "severity": "warning",
  "message": "Users search for 'output folder' but the expected config field is indexed as 'build.outputDir'.",
  "suggestedCommand": "docforge eval add-search-case"
}

export type TelemetryEnvelope = {
  schemaVersion: "telemetry-event/v1";
  eventType: string;
  eventVersion: string;
  timestamp: string;
  payload: unknown;
};

fixtures/telemetry/
  disabled/
  redacts-secrets/
  build-events/
  ai-cost-report/
  search-local-only/

it("emits no remote events when telemetry disabled", async () => {
  const exporter = new FakeTelemetryExporter();

  await runCommand("build", {
    telemetry: { enabled: false },
    exporter,
  });

  expect(exporter.events).toHaveLength(0);
});

it("redacts secret-like values before export", () => {
  const event = createDiagnosticEvent({
    message: "token sk_live_1234567890abcdef",
  });

  const prepared = prepareTelemetryEvent(event, privacyPolicy());

  expect(JSON.stringify(prepared)).not.toContain("sk_live_");
});

it("redacts absolute paths for remote telemetry", () => {
  const event = createBuildEvent({
    outputPath: "/Users/alice/acme/private-docs/dist",
  });

  const prepared = prepareTelemetryEvent(event, remotePrivacyPolicy());

  expect(JSON.stringify(prepared)).not.toContain("/Users/alice");
});

packages/observability/
  src/
    logs.ts
    metrics.ts
    traces.ts
    events.ts
    reporter.ts
    redaction.ts
    privacy.ts
    exporters/
      noop.ts
      local-jsonl.ts
      sqlite.ts
      ndjson.ts
      http.ts
    reports/
      build.ts
      quality.ts
      ai-cost.ts
      workflow.ts
      security.ts
      analytics.ts
    recommendations/
      search.ts
      performance.ts
      quality.ts
      ai.ts
    __tests__/
      redaction.test.ts
      telemetry-disabled.test.ts
      metrics.test.ts
      reports.test.ts

export type ObservabilityContext = {
  logger: Logger;
  metrics: MetricsSink;
  tracer: Tracer;
  events: EventSink;
};

export type PluginObservability = {
  log(level: LogRecord["level"], message: string, fields?: Record<string, unknown>): void;
  metric(name: string, value: number, tags?: Record<string, string>): void;
  span<T>(name: string, fn: () => Promise<T>): Promise<T>;
};

export async function shutdownObservability(ctx: ObservabilityContext): Promise<void> {
  await Promise.race([
    ctx.events.flush(),
    timeout(2000),
  ]);
}

warning telemetry.export.failed
Telemetry export failed. Build result is unaffected.

docforge analytics report
docforge analytics export
docforge analytics reset
docforge perf history
docforge ai cost-report
docforge telemetry status
docforge telemetry disable
docforge telemetry enable --local

Telemetry status

Mode: local
Remote export: disabled
Source content: not collected
Prompts: not collected
Model outputs: not collected
Retention: 30 days