F5 Traffic Auto-Suggestion Repository

Overview

The F5TrafficAutoSuggestRepository is a read-only component that provides access to the F5 traffic log table (s2r_traffic_log). Its primary purpose is to support the "F5 traffic auto-suggestion" feature, which helps API publishers discover and map live traffic events to their service operations.

This repository is used by a higher-level service layer to fetch candidate traffic events that may correspond to a specific service. It does not modify the traffic log data; all writes to the log are handled by a separate ingestion pipeline.

The repository's queries are designed to be secure in a multi-tenant environment. All data access is strictly scoped to the tenant associated with the current request, preventing an API publisher from viewing traffic belonging to another tenant.

How It Works

The repository provides methods to query the traffic log based on service identifiers and time windows. The core logic revolves around fetching potential matches, validating user selections, and providing metadata for scoring and filtering.

flowchart TD
    subgraph "API Publisher"
        A[Triggers auto-suggestion for a service version]
    end

    subgraph "Service Layer"
        A --> B[Calls `findTrafficForService`]
    end

    subgraph "F5TrafficAutoSuggestRepository"
        B --> C{Query `s2r_traffic_log`};
        subgraph "SQL Query Logic"
            C -- "WHERE" --> D["`observed_at` within `sinceHours`"];
            C -- "AND" --> E["(`service_id` matches OR <br> `environment` + `service_key` match)"];
            C -- "AND" --> F["Tenant ID matches current session"];
            C -- "ORDER BY" --> G["`observed_at` DESC"];
            C -- "LIMIT" --> H["`hardLimit`"];
        end
    end

    C --> I[Returns `List<F5TrafficEventRow>`];
    
    subgraph "Service Layer"
        I --> J[Presents traffic candidates to publisher];
    end

Finding Traffic Candidates

The findTrafficForService method is the main entry point for discovering traffic. It constructs a query to find relevant log entries based on a combination of resolved and unresolved service identifiers.

The query searches the s2r_traffic_log table for rows that match either of the following conditions:

1. The service_id column in the log matches the ID of the target service. This finds traffic that was recorded after the log ingestion pipeline had already associated the traffic with a known service.
2. The environment and service_key columns in the log match the target service's attributes. This finds traffic that was not yet resolved to a specific service_id at the time of ingestion.

The search is constrained to a specific time window and a maximum number of results to protect system performance. The results are returned newest-first.

Confirming Traffic Candidates

Once an API publisher selects traffic events from the suggested candidates, a "confirm endpoint" in the service layer uses the findById and findByIds methods to retrieve the full details of those specific events. This step validates that the selected event IDs are legitimate and accessible to the current tenant before they are persisted as mapping evidence.

Idempotency Checks

To prevent duplicate mappings, the evidenceExistsForCorrelation method is used by the confirmation endpoint. It checks if a s2r_mapping_evidence record already exists for a given service version and a traffic event's correlation_id. This makes the confirmation process idempotent, meaning that confirming the same traffic event multiple times has no additional effect after the first time.

Tenant Scoping

Public Methods

This repository exposes several public methods for querying traffic log data.

findTrafficForService

Fetches a list of candidate F5 traffic events for a given service within a specified time window. The results are ordered from newest to oldest.

The service layer that calls this method may apply additional filtering, such as a per-operation cap, on the returned results.

Parameters

Returns

A List<F5TrafficEventRow> containing the matching traffic events, or an empty list if none are found.

findById

Fetches a single F5 traffic event by its unique ID. This is typically used to validate a candidate selected by a user.

Parameters

Returns

An Optional<F5TrafficEventRow> containing the event if found and accessible by the tenant, otherwise an empty Optional.

findByIds

Fetches a list of F5 traffic events for a given list of unique IDs in a single query.

Parameters

Returns

A List<F5TrafficEventRow> containing the events that were found and are accessible. The list is sorted by observed_at desc, not by the input order of IDs. Returns an empty list if the input ids list is null or empty.

findServiceScope

Looks up a service's environment, service_key, and direction. The service layer uses this information to construct the traffic query.

Parameters

Returns

An Optional<ServiceScope> containing the service's scope details, or an empty Optional if not found.

findOperationSignals

Returns the set of defined operations for a given service version. The service layer uses this information to bucket traffic candidates by operation and to calculate confidence scores.

Parameters

Returns

A List<OperationSignal> containing the details for each operation.

evidenceExistsForCorrelation

Checks if a mapping evidence record already exists for a given service version and correlation ID.

Parameters

Returns

true if evidence already exists, false otherwise.

Data Structures

The repository methods return data in the form of the following record types.

F5TrafficEventRow

Represents a single traffic event from the s2r_traffic_log table.

ServiceScope

Contains identifying attributes for a service.

OperationSignal

Contains identifying attributes for a single service operation.

Troubleshooting

Missing or Cross-Tenant Results

If a query for a specific id using findById or findByIds returns no results, it can mean one of two things:

1. The traffic event with the given ID does not exist.
2. The traffic event exists but belongs to a different tenant.

Due to the strict tenant scoping, the system intentionally returns an empty result in the second case to avoid leaking information that the object exists.

Input Parameter Clamping

The findTrafficForService method sanitizes its sinceHours and hardLimit parameters to protect system stability:

• sinceHours is clamped to the range [1, 720]. A value of 0 or less will be treated as 1. A value greater than 720 (30 days) will be treated as 720.
• hardLimit is clamped to the range [1, 5000]. A value of 0 or less will be treated as 1. A value greater than 5000 will be treated as 5000.

If you provide values outside these ranges, the query will execute with the clamped value, not the one you provided.

See Also

• Traffic Log Ingestion: This repository reads from a traffic log populated by a separate ingestion pipeline.
• Service and Operation Management: The service and operation identifiers used in this repository correspond to entities managed elsewhere in the platform.

All SOAP-to-REST docs