Skip to content

Insights Framework

The insights framework provides automated analysis of API call patterns through a calculator-based architecture with orchestrated execution.

Insight Types

ServiceHop supports three insight types, executed in dependency order:

Type Order Description Depends On
PROFILE 1 Request/response semantic and non-semantic metadata analysis None
OVERVIEW 2 High-level service insights and patterns PROFILE
CACHEABILITY 3 Cache key recommendations with hit rate simulation PROFILE 
graph LR
    P[PROFILE] --> O[OVERVIEW]
    P --> C[CACHEABILITY]

Insight Status

Each insight has a status indicating its state:

Status Description
WORKING Calculation in progress
READY Successfully completed
ERROR Calculation failed
INVALID Result no longer valid
NO_DATA Insufficient data for analysis

InsightCalculator Architecture

Each insight type has a dedicated calculator implementing the base interface:

InsightCalculator<T extends BaseInsight>
├── type(): InsightType
├── calculate(CalculationParams): T
├── setWorking(): String (creates placeholder)
├── setError(): void (marks failure)
└── saveInsight(): void (persists result)

Concrete Calculators

ProfileCalculator

  • Extracts request/response field metadata
  • AI-powered importance classification
  • Generates cache key candidates
  • Tests key configurations on sample calls

OverviewCalculator

  • Aggregates service-level statistics
  • Identifies traffic patterns
  • Generates high-level recommendations

CacheabilityCalculator

  1. Simulation: Generates cache keys using request patterns
  2. Classification: Evaluates keys by hit rate vs response similarity
  3. Analysis: AI generates recommendations with scoring

Insight Orchestration

The InsightOrchestratorService manages when and what insights to calculate.

Orchestration Flow

sequenceDiagram
    participant O as Orchestrator
    participant DB as Database
    participant C as Calculator
    participant J as JobService

    O->>DB: Get data range per service
    O->>O: Calculate analysis window
    O->>O: Generate expected periods
    O->>DB: Get existing insights
    O->>O: Evaluate decisions

    loop For each EXECUTE decision
        O->>J: Create job
        O->>C: Execute async
        C->>DB: Save insight
        C->>J: Update job status
    end

Decision Logic

For each service, type, and period:

1. Find existing insight for period
2. If no insight exists → EXECUTE
3. If status = WORKING:
   - If age > staleThreshold → SKIP_STALE
   - Else → SKIP_WORKING
4. If status = ERROR → SKIP_ERROR
5. If data unchanged (hash match) → SKIP_READY
6. If data changed significantly → EXECUTE

Orchestration Actions

Action Meaning
EXECUTE No valid insight exists, generate one
SKIP_READY Insight up-to-date and valid
SKIP_WORKING Calculation currently in progress
SKIP_ERROR Insight has error, admin intervention needed
SKIP_STALE Insight stuck in WORKING (timeout exceeded)

Preview and Execute Pattern

The orchestrator supports a two-phase approach via the CLI:

Preview

servicehop-cli insight --preview

Returns a list of orchestration decisions with decision IDs. Use --pending-only to filter to EXECUTE decisions only.

Execute Decision

servicehop-cli insight --execute --decision-id d-abc12345

Executes a specific cached decision. Decisions are cached for 1 hour.

Full Orchestration

servicehop-cli insight --orchestrate

Runs all pending EXECUTE decisions at once.

This pattern allows inspection before execution and selective execution of specific decisions.

InsightHash

The InsightHash captures the data fingerprint for an insight:

Field Description
from Period start timestamp
to Period end timestamp
calls Number of calls in period

Hash change detection:

changeRatio = |newCalls - oldCalls| / oldCalls
if changeRatio > hashChangeThreshold (default 20%) → significant change

Async Execution

Insight calculation runs asynchronously via InsightAsyncExecutor:

1. Create WORKING placeholder insight
2. Create job record (PENDING)
3. Execute calculator.calculate()
4. On success: Update insight to READY, job to SUCCEEDED
5. On failure: Update insight to ERROR, job to FAILED

Configuration

Property Default Description
recurrence.PROFILE 1 week How often to recalculate PROFILE
recurrence.OVERVIEW 1 week How often to recalculate OVERVIEW
recurrence.CACHEABILITY 1 week How often to recalculate CACHEABILITY
timeframe.PROFILE 3 months Maximum lookback for PROFILE
stale-working-threshold 30 minutes When to consider WORKING as stale
hash-change-threshold 0.2 Sensitivity for data change detection

Facts, Findings, Analysis Pattern

For AI-enhanced insights (like Cacheability), the framework separates:

Layer Characteristics Example
Facts Deterministic, cacheable Hit rate: 0.75, Call count: 1000
Findings Computed with thresholds "High cacheability potential"
Analysis AI-generated "Recommend implementing TTL-based caching..."

This separation enables:

  • Reproducible facts without AI dependency
  • Clear audit trail for threshold-based findings
  • AI-generated recommendations with confidence scores