Capacity Counting Evaluator

Overview

The CapacityCountingEvaluator is an internal system component that periodically calculates two key service capacity metrics: Converted Services and Discovered Services.

It solves the problem of computing these values efficiently and consistently. By pre-calculating the metrics on a defined schedule, it ensures that other components, such as the SpecariaHeartbeatClient, can access up-to-date capacity counts without performing expensive queries on the fly. This guarantees that the metrics used for platform reporting are always consistent with the canonical capacity rules.

The evaluator's inputs are service discovery and runtime traffic data stored in the platform's database. Its outputs are three key-value pairs persisted to the s2r_system_setting table, which represent the latest capacity counts and the time of evaluation.

How it Works

The CapacityCountingEvaluator runs automatically on a recurring schedule. It also performs an immediate, one-time evaluation upon application startup to ensure capacity data is available without waiting for the first scheduled run.

The evaluation process follows these steps:

1. Trigger: The process is initiated either by an ApplicationStartedEvent at system startup or by a scheduled cron trigger, which runs daily by default.
2. Read Previous State: The evaluator first reads the previously stored values for the converted and discovered service counts from the s2r_system_setting table. This is used later for logging the change (delta) between runs.
3. Compute Metrics: The evaluator executes two separate database queries to calculate the current capacity counts.
   • computeConverted(): Calculates the number of "converted services" based on recent API traffic.
   • computeDiscovered(): Calculates the total number of "discovered services".
4. Persist Results: The new counts, along with a current timestamp, are written to the s2r_system_setting table using an UPSERT operation. This overwrites the previous values.
5. Log Outcome: A log entry is created at the INFO level, recording the new counts, the change from the previous counts, the traffic threshold used, and the evaluation timestamp.

If any step fails, the operation is "fail-soft". The error is logged as a WARN, and the process terminates gracefully for that run, to be retried on the next scheduled execution.

Data Flow

flowchart TD
    subgraph Triggers
        A[Application Startup]
        B[Scheduled Cron Job]
    end

    subgraph "CapacityCountingEvaluator"
        C{evaluate()}
        D[1. Read Previous Counts<br/>from s2r_system_setting]
        E[2. Compute Metrics]
        F[3. Persist New Counts<br/>to s2r_system_setting]
        G[4. Log Results]
    end

    subgraph "Database"
        H[s2r_runtime_agg_service_hourly]
        I[s2r_master_discovery]
        J[s2r_system_setting]
    end

    A --> C
    B --> C
    C --> D
    D -- Reads --> J
    D --> E

    E -- Calls computeConverted() --> H
    E -- Calls computeDiscovered() --> I

    H -- Returns count --> E
    I -- Returns count --> E

    E --> F
    F -- UPSERTs --> J
    F --> G

Metric Definitions

The evaluator calculates two distinct metrics, each with a specific definition.

Converted Services

A service is counted as "converted" if it has processed strictly more than 300 API calls within any rolling 7-day window.

• Source Data: The calculation is based on the request_count column in the s2r_runtime_agg_service_hourly table.
• Decay: A service is no longer included in the count if its total traffic over the preceding 7 days falls to 300 calls or fewer.
• Uniqueness: Services are counted distinctly based on the combination of their service_key and direction (PUBLISH or CONSUME). This means that the publish and consume aspects of a single logical service are treated as two separate items for capacity counting.
• Threshold: The traffic threshold is fixed at 300.

Discovered Services

A service is counted as "discovered" if it has a corresponding entry in the s2r_master_discovery table.

• Source Data: The calculation is a direct row count (COUNT(*)) of the s2r_master_discovery table.
• Decay: This count is monotonic; it only increases over time as new services are discovered. There is no decay mechanism.

Configuration

The evaluator's schedule can be configured via a single system property.

Stored System Settings

The evaluator persists its results as key-value pairs in the s2r_system_setting table. These values are intended for consumption by other internal components.

Introspection API

The CapacityCountingEvaluator exposes several methods that allow other system components to read the last computed capacity values.

• int convertedServicesCount() Returns the last persisted count of converted services. If the value is not set or is invalid, it returns 0.

• int discoveredServicesCount() Returns the last persisted count of discovered services. If the value is not set or is invalid, it returns 0.

• String lastEvaluatedAt() Returns the ISO-8601 timestamp of the last evaluation as a string. If an evaluation has never occurred, it returns null.

Troubleshooting

The evaluator is designed to be resilient and operate in a "fail-soft" manner to avoid disrupting the platform.

• Evaluation Failures: If the evaluate() method fails during either the startup or a scheduled run (e.g., due to a temporary database connection issue), a WARN message is logged with the exception details. The application will not crash, and the evaluation will be re-attempted on the next scheduled run.

• Metric Calculation Failures: If a specific query within computeConverted() or computeDiscovered() fails, a WARN message is logged, and the method returns 0 for that metric. This may cause the reported capacity count to temporarily drop to zero until the next successful run.

• Data Persistence Failures: If the upsertSetting() operation fails to write the results to the database, a WARN message is logged. The newly computed values will not be saved, and components reading the data will continue to see the stale values from the last successful run.

See Also

• Heartbeat Client: The SpecariaHeartbeatClient is the primary consumer of the capacity metrics produced by this evaluator. It reads the pre-computed values from s2r_system_setting to build its daily heartbeat payload.

All SOAP-to-REST docs