Master Discovery Drill-Down API

Overview

The Master Discovery Drill-Down API provides a set of endpoints for retrieving detailed, aggregated information about a specific service discovered across the platform. Unlike endpoints that are scoped to a single gateway instance, this API aggregates data for a given service URI from all reporting sources, corresponding to a single row in the s2r_master_discovery table.

This API is used to power detailed views of a service's health and usage. It allows operators to investigate a service's traffic patterns, identify its consumers, analyze recent failures, and manage its associated alert rules from a centralized point.

The controller's main inputs are a master discovery row ID (rowId) and optional parameters to control the scope of data returned. It queries a repository for various data facets—such as traffic timelines, consumer lists, and failure logs—and aggregates them into a comprehensive JSON response.

How It Works

The API provides three endpoints, each of which begins by fetching a master discovery row by its unique rowId. If the row is not found, the API returns a 404 Not Found error. The serviceUri from this row is then used as the primary identifier for all subsequent data fetching.

A key aspect of the data aggregation logic is its ability to handle services observed by different types of gateways (e.g., F5 and other generic vendors). When fetching data like traffic timelines or failures, the system determines the appropriate gateway type to query against:

• If the master discovery row contains an f5InstanceId, it is considered an F5-observed service. Queries for generic gateway data will match the serviceUri across all vendors to include any dual-observed traffic.
• If the row does not have an f5InstanceId, it is considered a generic service. Queries are scoped to the specific vendor listed in the row to avoid mixing data from different generic gateway types.

The following diagram illustrates the data aggregation flow for the main drill-down endpoint:

sequenceDiagram
    participant C as API Consumer
    participant A as Admin API
    participant R as Data Repository

    C->>A: GET /.../rows/{rowId}/drill-down
    A->>R: loadRowById(rowId)
    R-->>A: Master Discovery Row
    A->>R: loadTimelineForServiceUri(serviceUri, from, to, gatewayType)
    R-->>A: Timeline Data
    A->>R: loadConsumersForRow(rowId)
    R-->>A: Consumer List
    A->>R: loadAlertRuleForServiceUri(serviceUri)
    R-->>A: Alert Rule
    A->>R: loadGoodExamplesForServiceUri(serviceUri, 50, source)
    R-->>A: Example Payloads
    A-->>C: 200 OK (Aggregated Drill-Down Data)

API Reference

Get Full Service Drill-Down

Retrieves a comprehensive set of details for a single master discovery row, including service information, traffic KPIs, a historical timeline, a list of consumers, and the associated alert rule.

GET /admin/v1/master-discovery/rows/{rowId}/drill-down

Path Parameters

Query Parameters

Response

On success, returns a 200 OK with a JSON object containing the aggregated data.

• row: The original master discovery row data.
• timeline: An array of objects representing hourly traffic metrics.
• timelineFrom: The start timestamp (UTC) for the timeline data.
• timelineTo: The end timestamp (UTC) for the timeline data.
• consumers: An array of objects, each representing a known consumer of the service.
• consumerCount: The total number of consumers.
• alertRule: An object containing the configuration of the alert rule for the service, or null if none exists.
• goodExamples: An array of up to 50 objects, each representing a successful request/response pair.

Get Recent Failures

Retrieves a list of recent failures for the service URI associated with a master discovery row, aggregated across all relevant gateway instances.

GET /admin/v1/master-discovery/rows/{rowId}/failures

Path Parameters

Query Parameters

Response

On success, returns a 200 OK with a JSON object containing the list of failures.

• serviceUri: The service URI for which failures were retrieved.
• failures: An array of objects, each representing a single failure event.
• count: The number of failure records returned.
• partial: A boolean flag. If true, the scan for failures was terminated before completion (e.g., due to a time limit), and the returned list represents only the most recent slice of failures, not the complete set within the search window.

Save Alert Rule

Creates or updates an alert rule for the service URI associated with a master discovery row. Alert rules are used to trigger notifications based on failure rates or traffic volume thresholds.

PUT /admin/v1/master-discovery/rows/{rowId}/alert

Path Parameters

Request Body

A JSON object specifying the alert rule configuration.

Example Request Body

{
  "enabled": true,
  "minCalls1h": 100,
  "failurePctThreshold": 5.0,
  "failureCountThreshold": 10
}

Response

On success, returns a 200 OK with a JSON object confirming the operation.

• status: A string with the value saved.
• serviceUri: The service URI for which the alert rule was saved.

Troubleshooting

See Also

• Master Discovery: The parent feature that aggregates services from multiple sources into a unified view.
• Instance-Scoped F5 Service Endpoints: For drilling down into service data from a single F5 instance, rather than an aggregation of all sources.

All SOAP-to-REST docs