Skip to content

Call Model

ServiceHop models API interactions as Calls organized by Services.

Calls

A Call represents a single API request-response interaction. Each call captures:

Attribute Description
ID Unique identifier for the call
Timestamp When the call occurred
Service The service that handled the call
Duration Execution time in milliseconds
Result HTTP status code
Result Type SUCCESS, ERROR, or UNKNOWN
Request Request payload (body)
Response Response payload (body)

Call Storage

Calls are stored in a partitioned table (sh_call_master) for efficient querying by date range.

Payload Handling:

  • Small payloads (< 3KB) are stored inline in the database
  • Large payloads (≥ 3KB) are stored as external files
  • Both storage methods are transparent to users

Ingesting Calls

Calls are ingested via the CLI ingest command:

servicehop-cli ingest --input calls.json

JSON format for call records:

{
  "id": "call-123",
  "timestamp": "2024-01-15T10:30:00Z",
  "service": "user-service",
  "duration": 150,
  "result": 200,
  "request": { "userId": "abc123" },
  "response": { "name": "John Doe", "email": "john@example.com" }
}

Services

A Service is a logical grouping of related calls. Services are identified by name.

Service Lifecycle

Services are created automatically when the first call referencing that service is ingested. No explicit service registration is required.

Example:

  1. Ingest a call with service: "payment-service"
  2. ServiceHop automatically creates the "payment-service" entry
  3. Subsequent calls to "payment-service" are associated with it

Service Insights

Each service accumulates three types of insights:

Insight Description
PROFILE Request/response field metadata and patterns
OVERVIEW High-level statistics and traffic patterns
CACHEABILITY Cache key recommendations and hit rate simulations

See Insights Framework for details on how insights are generated.

Data Flow

Call Data → Ingest → Storage → Aggregation → Insights
  1. Ingest: CLI sends call records to the Core API
  2. Storage: Calls are written to partitioned storage
  3. Aggregation: Background jobs compute hourly and daily rollups
  4. Insights: Orchestrator triggers insight calculations based on available data

Querying Calls

Use the CLI to query stored calls:

List calls: 

servicehop-cli call --list --service user-service

View a specific call: 

servicehop-cli call --show call-123 --with-payload

Get sample calls: 

servicehop-cli call --samples --service user-service --sample-count 10