Deployment Capacity and Demand Estimation

Overview

The Capacity Estimation Service provides a dynamic assessment of the platform's data plane capacity versus its observed traffic demand. This service powers the "deployment capacity vs. discovered demand" panel on the administrative dashboard, offering an at-a-glance verdict on whether the current deployment is sufficiently provisioned.

The service synthesizes two key perspectives:

• Capacity: The theoretical maximum load the system can handle. This is determined by a cloud-agnostic CapacityProvider, which can either discover resources and quotas live from the cloud environment or fall back to statically configured values.
• Demand: The actual load observed on the system. This is calculated by querying pre-computed aggregation tables in the database, summarizing traffic over a configurable time window.

The service's final output is a CapacityEstimateResponse object, which includes detailed breakdowns of both capacity and demand, along with a simple verdict: OK, OVER_CAPACITY, or UNKNOWN. This allows operators to quickly identify potential capacity shortfalls.

How it Works

The capacity estimation process runs when the estimate() method is called. It calculates the capacity and demand sides concurrently before comparing them to produce a verdict.

flowchart TD
    subgraph "Capacity Calculation"
        A[CapacityProvider] -->|Live data| B(Merge with Fallbacks)
        C[S2R_CAPACITY_* config] -->|Fallback values| B
        B --> D(CapacityMath.compute)
        D --> E[CapacitySide Response]
    end

    subgraph "Demand Calculation"
        F[DB: s2r_traffic_concurrency_hourly] -->|Measured peak| G{Read Demand Metrics}
        H[DB: s2r_agg_service_hourly] -->|Estimated peak, calls/day| G
        I[DB: s2r_master_discovery] -->|Service count| G
        G --> J[DemandSide Response]
    end

    K(estimate() call) --> A
    K --> G

    E --> L{Combine and Determine Verdict}
    J --> L

    L --> M[CapacityEstimateResponse]

Capacity Estimation

The capacity side of the estimate is determined through the following steps:

1. Select Provider: The service first resolves a CapacityProvider. If a cloud-specific implementation (e.g., for GCP) is available in the system, it is used. Otherwise, it defaults to a StaticCapacityProvider which relies solely on operator-configured environment variables.
2. Fetch Live Data: The selected provider's describeDataPlaneCapacity() method is called to get a DeploymentCapacity object containing details like instance counts, quotas, and network IP availability.
3. Merge with Fallbacks: The data from the provider is merged with static configuration values (S2R_CAPACITY_*). This makes the estimate more robust. If the live provider fails to determine a specific value (e.g., due to missing IAM permissions), the corresponding static configuration value is used as a fallback. A warning is added to the response indicating which values were supplied from configuration. A successful live read always takes precedence over a configured fallback.
4. Compute Maximums: The merged DeploymentCapacity is passed to the CapacityMath.compute() function. This function analyzes the various inputs to calculate the maxSimultaneousCalls the deployment can support and identifies the specific limitingFactor (e.g., CPU, IP addresses, regional quota).

Demand Estimation

The demand side is derived from historical traffic data stored in aggregated database tables.

1. callsPerDay: Calculated by summing the success_hits and failure_hits from the s2r_agg_service_hourly table over the last 24 hours.
2. discoveredServiceCount: Calculated by counting rows in s2r_master_discovery that have had traffic in the last 24 hours (hits_24h > 0). This aligns with the service count shown on the Master Discovery screen.
3. peakParallelCalls: This metric is determined using a two-tiered approach to find the highest number of concurrent calls within the configured demand-window-days:
   • Measured (Primary): The service first attempts to query the s2r_traffic_concurrency_hourly table. This table contains pre-calculated, sub-hour peak concurrency values. If a valid peak is found, it is used, and the resolution field in the response is set to "measured".
   • Estimated (Fallback): If no measured peak is available (e.g., the table does not exist or is empty), the service falls back to an hourly estimate based on Little's Law. It processes each hour in the s2r_agg_service_hourly table and calculates concurrency as (callsThisHour / 3600.0) * avgBackendLatencySeconds. The highest calculated value across all hours becomes the peakParallelCalls, and the resolution is set to "hourly-estimate". If latency data is not available for an hour, a default assumed-call-ms value is used.

Verdict Calculation

The final verdict is determined by comparing the capacity and demand estimates:

• UNKNOWN: If maxSimultaneousCalls could not be calculated due to missing capacity inputs.
• OVER_CAPACITY: If peakParallelCalls is known and exceeds maxSimultaneousCalls.
• OK: In all other cases.

API Reference

The CapacityEstimateService exposes an estimate() method that returns a CapacityEstimateResponse object. The source does not specify the exact HTTP endpoint that exposes this service method.

Example Response

The following is an example of the JSON response payload. This example shows an OVER_CAPACITY verdict where the discovered peak demand of 1250 concurrent calls exceeds the system's calculated capacity of 1000. It also includes a warning that the max-instances value was sourced from a configuration fallback.

{
  "capacity": {
    "provider": "GcpCapacityProvider",
    "region": "us-east1",
    "service": "s2r-runtime",
    "effectiveMaxInstances": 50,
    "concurrencyPerInstance": 20,
    "maxSimultaneousCalls": 1000,
    "limitingFactor": "Per-instance concurrency",
    "factorCeilings": {
      "CONFIGURED_MAX_INSTANCES": 50,
      "REGIONAL_INSTANCE_QUOTA": 200,
      "SUBNET_IP_CAPACITY": 409,
      "CONCURRENCY": 1000
    },
    "live": true,
    "warnings": [
      "Max-instances from configured fallback (S2R_CAPACITY_MAX_INSTANCES=50)."
    ]
  },
  "demand": {
    "peakParallelCalls": 1250,
    "peakObservedAt": "2023-10-27 14:00:00.0",
    "callsPerDay": 2150498,
    "discoveredServiceCount": 88,
    "windowDays": 30,
    "resolution": "measured",
    "warnings": []
  },
  "verdict": "OVER_CAPACITY"
}

Response Body Fields

The response object contains three top-level fields: capacity, demand, and verdict.

capacity Object

demand Object

Configuration

The service is configured through application properties, which can be supplied as environment variables.

Troubleshooting

Demand Metric is null

If a database query to fetch a demand metric (e.g., callsPerDay or peakParallelCalls) fails, the service will not fail. Instead, the corresponding field in the demand object of the response will be null, and a descriptive error message will be added to the demand.warnings array.

Capacity Warnings about Fallbacks

If the capacity.warnings array contains messages like "Max-instances from configured fallback...", it means the live CapacityProvider was unable to determine that value from the cloud environment. The service successfully used the corresponding S2R_CAPACITY_* environment variable as a substitute. While the estimate is still valid, this may indicate a problem with the service account permissions used for live discovery.

"UNKNOWN" Verdict

A verdict of UNKNOWN indicates that the service was unable to calculate maxSimultaneousCalls. This occurs when essential capacity inputs (like max instances, concurrency, or IP availability) are missing from both the live provider and the static configuration fallbacks. Check that the S2R_CAPACITY_* variables are set correctly if you are not using a live provider, or investigate the capacity.warnings for clues if you are.

See Also

• The Master Discovery screen, which provides a view of services that corresponds to the discoveredServiceCount metric.

All SOAP-to-REST docs