Master Discovery Drill-Down API

API endpoints for detailed analysis of aggregated service discovery data, including traffic timelines, consumers, failures, and alert configuration.

Overview

The Master Discovery Drill-Down API provides endpoints for in-depth analysis of individual services identified by the master discovery process. Whereas some API platform endpoints are scoped to a single gateway instance, these endpoints aggregate data across all reporting sources for a given service URI. This provides a unified, cross-platform view of a service's health, traffic, and configuration.

API consumers use these endpoints to retrieve detailed operational data for a specific row from the s2r_master_discovery table. This includes:

Traffic and performance KPIs over time.
A list of API consumers invoking the service.
Recent transaction failures.
Associated alerting rules.
Examples of successful requests.

The controller's primary input is a master discovery row ID (rowId), and its output is a rich JSON object containing the aggregated details for the service represented by that row.

How it Works

When a request is made to a drill-down endpoint, the system performs the following sequence of operations:

Load Master Row: The system first retrieves the specified master discovery row from the data store using the provided {rowId}. If no row is found, the API returns a 404 Not Found error.
Extract Service URI: The serviceUri is extracted from the master discovery row. This URI serves as the primary identifier for fetching all related data across different data sources and gateway instances.
Aggregate Data: The system then queries the data store for several distinct datasets associated with the serviceUri:
- Traffic Timeline: A history of hourly traffic metrics. The time window is adjustable but is constrained to a maximum of 30 days.
- Consumers: A list of clients that have called the service.
- Alert Rule: The currently configured alert rule for the service.
- Good Examples: A list of recent, successful transaction examples.
- Failures: A list of recent transaction failures.
Handle Multi-Vendor Data: The system intelligently scopes queries based on the service's origin.
- If the master discovery row originated from an F5 instance (i.e., it has an f5InstanceId), queries for related generic gateway data (like timelines and failures) are performed across all vendors to merge information for services observed by multiple gateway types.
- If the row originated from a non-F5 generic gateway, queries are scoped to that specific vendor (e.g., datapower).
Assemble Response: The collected data is assembled into a single JSON response and returned to the API consumer.

The diagram below illustrates the data retrieval flow for the primary drill-down endpoint.

sequenceDiagram
    participant C as API Consumer
    participant A as Drill-Down API
    participant D as Data Store

    C->>A: GET /.../rows/{rowId}/drill-down
    A->>D: Load master discovery row by ID
    D-->>A: Return row data (incl. serviceUri)

    alt Row found
        A->>D: Load traffic timeline for serviceUri
        D-->>A: Timeline data
        A->>D: Load consumers for rowId
        D-->>A: Consumer list
        A->>D: Load alert rule for serviceUri
        D-->>A: Alert rule data
        A->>D: Load good examples for serviceUri
        D-->>A: Example list
        A-->>C: 200 OK (Aggregated data)
    else Row not found
        A-->>C: 404 Not Found
    end

API Endpoints

Get Service Drill-Down Details

Retrieves a comprehensive set of details for a single master discovery row, including service info, traffic KPIs, a 7-day hourly timeline, consumers, and the associated alert rule.

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

Parameters

Name	In	Type	Required	Description
`rowId`	Path	long	Yes	The unique identifier of the row from the `s2r_master_discovery` table.
`timelineDays`	Query	int	No	The number of past days to include in the traffic timeline. The value is sanitized to be between 1 and 30. Default: 7.
`source`	Query	string	No	The source for transaction examples. Valid values are `f5`, `generic`, or `all`. Invalid values default to `f5`. Default: "f5".

Responses

200 OK: The request was successful. The body contains the aggregated drill-down data.

{
  "row": {
    "id": 12345,
    "serviceUri": "/example/service/v1",
    "f5InstanceId": 1,
    "vendor": "f5",
    "serviceUriCanonical": "/example/service/v1"
  },
  "timeline": [
    { "hour": "2023-10-27T10:00:00Z", "calls": 150, "errors": 5 },
    { "hour": "2023-10-27T11:00:00Z", "calls": 165, "errors": 2 }
  ],
  "timelineFrom": "2023-10-20T12:00:00.000000Z",
  "timelineTo": "2023-10-27T12:00:00.000000Z",
  "consumers": [
    { "consumerName": "app-A", "totalCalls": 5000 },
    { "consumerName": "app-B", "totalCalls": 1200 }
  ],
  "consumerCount": 2,
  "alertRule": {
    "enabled": true,
    "min_calls_1h": 20,
    "failure_pct_threshold": 10.0
  },
  "goodExamples": [
    { "traceId": "abc-123", "requestPayload": "...", "responsePayload": "..." }
  ]
}

The response body contains the following fields:

Field	Type	Description
`row`	Object	The original master discovery row data.
`timeline`	Array	An array of objects, each representing hourly traffic metrics.
`timelineFrom`	String	The UTC start time of the timeline data window (ISO 8601 format).
`timelineTo`	String	The UTC end time of the timeline data window (ISO 8601 format).
`consumers`	Array	An array of objects, each representing a consumer of the service.
`consumerCount`	Integer	The total number of unique consumers.
`alertRule`	Object	The alert rule configuration for this service. May be `null` if no rule is defined.
`goodExamples`	Array	A list of up to 50 recent successful transaction examples.

404 Not Found: The specified rowId does not exist.

{
  "error": {
    "code": "S2R-DISC-0404",
    "message": "Master discovery row not found"
  }
}

Get Recent Service Failures

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

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

Parameters

Name	In	Type	Required	Description
`rowId`	Path	long	Yes	The unique identifier of the row from the `s2r_master_discovery` table.
`limit`	Query	int	No	The maximum number of failure records to return. Default: 20.

Responses

200 OK: The request was successful. The body contains the list of failures.

{
  "serviceUri": "/example/service/v1",
  "failures": [
    {
      "timestamp": "2023-10-27T11:30:05Z",
      "statusCode": 500,
      "traceId": "xyz-789"
    }
  ],
  "count": 1,
  "partial": false
}

The response body contains the following fields:

Field	Type	Description
`serviceUri`	String	The service URI for which failures were retrieved.
`failures`	Array	An array of objects, each representing a single transaction failure.
`count`	Integer	The number of failure records returned in the `failures` array.
`partial`	Boolean	If `true`, the failure scan did not complete within its allotted time budget. The returned `failures` represent the most recent slice of data, not the complete set within the search window.

404 Not Found: The specified rowId does not exist.

{
  "error": {
    "code": "S2R-DISC-0404",
    "message": "Master discovery row not found"
  }
}

Create or Update Service Alert Rule

Creates or updates an alert rule for the service URI associated with a master discovery row. The rule is stored in the s2r_f5_service_alert_rule table.

IMPORTANT

This operation requires the master discovery row to have an associated f5InstanceId. An alert cannot be saved for a service that is not associated with an F5 instance.

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

Parameters

Name	In	Type	Required	Description
`rowId`	Path	long	Yes	The unique identifier of the row from the `s2r_master_discovery` table.

Request Body

The request body is a JSON object specifying the alert rule configuration.

Field	Type	Required	Default	Description
`enabled`	boolean	No	`false`	If `true`, the alert rule is active.
`minCalls1h`	integer	No	`20`	The minimum number of calls that must occur in a 1-hour window for the alert to be considered for firing.
`failurePctThreshold`	number	No	`10.0`	The percentage of failures (e.g., `10.0` for 10%) in a 1-hour window that will trigger an alert, provided `minCalls1h` is met.
`failureCountThreshold`	integer	No	`5`	The absolute number of failures in a 1-hour window that will trigger an alert, provided `minCalls1h` is met. This condition is evaluated independently of `failurePctThreshold`.

Example Request

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

Responses

200 OK: The alert rule was successfully saved or updated.

{
  "status": "saved",
  "serviceUri": "/example/service/v1"
}

400 Bad Request: The master discovery row does not have an f5InstanceId, so an alert rule cannot be saved.

{
  "error": {
    "code": "S2R-DISC-0400",
    "message": "Row has no F5 instance — cannot save alert"
  }
}

404 Not Found: The specified rowId does not exist.

{
  "error": {
    "code": "S2R-DISC-0404",
    "message": "Master discovery row not found"
  }
}

Troubleshooting

Error Code	HTTP Status	Trigger	Meaning
`S2R-DISC-0404`	`404 Not Found`	The `rowId` provided in the path does not correspond to any existing row in the `s2r_master_discovery` table.	The requested resource could not be found. Verify the `rowId` is correct.

S2R-DISC-0400 | 400 Bad Request | An attempt was made to save an alert rule (PUT .../alert) for a master discovery row that does not have an f5InstanceId value. | Alert rules can only be attached to services associated with an F5 instance. This error indicates the target service is from a generic gateway source that does not support this alerting mechanism. |

Tagsreference

All SOAP-to-REST docs

Loading…