Module uses 

Local uses and insights (privacy-respecting behavioral capture)

This module provides anonymous usage pattern collection that stays entirely local. All data uses strongly-typed enums - no arbitrary strings can leak. Users can disable via config, environment, or by building without the feature. Local uses and insights module

This module provides privacy-respecting behavioral capture for sqry, enabling users to understand their own usage patterns and share anonymous insights if they choose to.

Architecture

sqry operations ──▶ UsesCollector ──▶ Daily JSONL files
                      (fire-and-forget)     │
                                            ▼
                    DiagnosticsAggregator ◀─┘
                             │
                             ▼
                    Weekly summaries + Insights reports

Privacy Guarantees

All data is local-first:

• Events capture behavioral patterns, never code content
• All fields are strongly-typed enums (no arbitrary strings)
• Sharing is always explicit and requires confirmation
• Users can disable entirely via config or environment

Feature Gating

This module is gated behind the uses feature flag. The hierarchy is:

• uses: Local uses recording
• insights: Local summaries and reports (requires uses)
• troubleshoot: Support bundle generation (requires insights)

Build with --no-default-features to produce a binary with no collection code.

Usage

use sqry_core::uses::{UseEvent, UseEventType, QueryKind, DiagnosticsAggregator};

// Record an event (fire-and-forget)
let event = UseEvent::new(UseEventType::QueryExecuted {
    kind: QueryKind::CallChain,
    result_count: 42,
});
collector.record(event);

// Get weekly insights
let aggregator = DiagnosticsAggregator::new(&uses_dir);
let summary = aggregator.summarize_week("2025-W50")?;

Structs

AutoSummarizeConfig

Configuration for automatic summarization

CollectorTimedUse

RAII timer for collector - records event with duration on drop

ContextualFeedbackConfig

Configuration for contextual feedback prompts

DiagnosticsAggregator

Diagnostics aggregator - transforms raw events into weekly summaries

DiagnosticsSummary

Weekly diagnostics summary - aggregated from daily event logs

GraphAbandonRate

Per-graph-kind abandonment rate for detailed insights

IsoWeekPeriod

Newtype for ISO week periods - validated format only

SanitizedConfig

Sanitized config for troubleshoot bundles - no paths, no secrets

ShareSnapshot

Share snapshot - self-contained payload for sqry insights --share

SqryVersion

Newtype for sqry version - validated semver format only

StructuredError

Structured error - no arbitrary strings, no paths

SystemInfo

System information - enum-only, no version strings

TimedUse

RAII timer for recording event duration on drop

TopWorkflow

Workflow count entry for diagnostics summary

TroubleshootBundle

Troubleshoot bundle - structured data for issue reporting

UseEvent

A single use event captured by sqry

UsesCollector

Global uses collector - fire-and-forget event capture

UsesConfig

Configuration for local uses and insights

UsesStorage

Storage operations for reading and managing use event files

UsesWriter

Background writer that receives events from the collector channel and writes them to daily JSONL files.

WorkflowTrace

Workflow trace - strictly typed enum steps (opt-in via –include-trace)

Enums

AggregatorError

Errors that can occur during aggregation

ArchKind

Architecture kinds

BuildKind

Build type kinds

ConfigLoadError

Errors that can occur when loading configuration

ConfigSaveError

Errors that can occur when saving configuration

ErrorCategory

Error categories for troubleshoot bundles

ErrorKind

Error kinds for troubleshoot bundles

ExportFormat

Supported export formats

FeedbackContext

Context in which feedback was requested

FeedbackResponse

User feedback response options

GraphKind

Types of graphs that can be expanded

OsKind

Operating system kinds

PromptFrequency

Frequency of feedback prompts

QueryKind

Types of queries that can be executed

UseEventType

Sum enum with data variants - uses internally tagged serialization.

ViewKind

Types of views that can be displayed

WorkflowStep

Workflow step enum - tagged serialization like UseEventType

Functions

generate_bundle

Generate a troubleshoot bundle from usage data.