Custom Integrations Using Metering Beacons

This guide documents how to write custom integrations to Revenium Metering Beacons.

Before investigating a custom integration, we recommend you review our Linux & container-native metering solution here, which works in a variety of environments and is configurable with only a few lines of additional code.

Introduction

Revenium Metering Beacons act as bulkheads or “shock absorbers” to collect API transaction telemetry. The telemetry data is buffered in the Metering Beacon’s cache and periodically synchronized to the Revenium Transaction Engine.

Under normal circumstances you should not need to implement custom integrations to the Metering Beacons. Revenium offers out-of-the-box connectivity to most common API Gateways and API platforms, including MuleSoft, Kong, Apigee, Istio, Envoy, Spring Boot and others.

The Revenium Metering Beacon presents a very simple REST API that allows downstream applications, such as API gateway plugins or agents, to send API transaction telemetry via an HTTP POST operation with a JSON payload.

Metering Beacon Architecture

In addition to the REST API Revenium also provides a pre-packaged JVM SDK to simplify integration with JVM based applications (Java, Scala, Clojure, Kotlin, etc.)

The Revenium Metering SDK can be obtained from your Revenium Account Team.

Using the Metering Beacon API

The full Metering Beacon API documentation is located here: https://revenium.readme.io/reference/meter

Metering Beacon Data Types

The Metering Beacon API uses the following JSON data types

MeteringRequestDTO

MeteringRequestDTO represents the result of a metered HTTP API transaction. MeteringRequestDTOs are created after the response has been received from a metered API. Use MeteringRequestDTO when you need to meter an API transaction after it has completed. This is used to synchronously meter an API transaction.

Field	Description
api	The Revenium API ID of the metered API
productKey	The Revenium ProductKey ID of the subscriber being billed
method	The HTTP method being called
url	The URL of the API being called

ApiEventDTO

ApiEventDTO represents either the request or response of an HTTP API transaction of a metered API request. ApiEventDTOs are created when the HTTP request is received and when the API response has been completed. This is used to asynchronously meter an API transaction.

Field	Description
requestId	A UUID used to correlate request and response API events
eventType	The type of event, can be either _“REQUEST” _or “RESPONSE”
api	The Revenium API ID of the metered API
productKey	The Revenium ProductKey ID of the subscriber being billed
method	The HTTP method being called
currentMillis	Epoch timestamp of the event in milliseconds
uri	The URL/URI of the API being called
elapsedTime	The elapsed time (in milliseconds) of the event

Metering Beacon Endpoints

The Revenium Beacon API exposes the following endpoints:

Endpoint	Method	Type	Description
/metering/v1/api/meter	POST	MeteringRequestDTO	Insert an API Metering Transaction. This method is used to capture an atomic API request / response in a single class. Use this endpoint when metering API transactions after they’ve completed.
/metering/v1/api/meter	GET	LineItemDTO	Return currently buffered API Metering Requests
/metering/v1/api/event	POST	ApiEventDTO	Insert an API Metering Event. This is used to record API requests and responses independently. Use this endpoint to meter API requests and responses separately. The Metering Beacon will correlate the independent events using the requestId

Revenium uses the /metering/v1/api/meter endpoint to implement metering policies / plugins for traditional API Gateway implementations such as MuleSoft, Kong and Apigee. We use the /metering/v1/api/event to implement metering policies / plugins for cloud API Gateway implementations like AWS and Azure which rely on serverless functionality.

Examples

CURL

The detailed example on this page shows how to use CURL to send metering requests via the command line.

Kotlin

This example demonstrates a metering request sent via Kotlin using the Revenium JVM SDK.

val dto = MeteringDTO(apiId, request.getHeader(X-REVENIUM-PRODUCT-KEY), req.method, req.requestURL.toString())

val jsonRequest = mapper.writeValueAsString(dto)

val meteringResponse = client.post().uri(uri!!)
          .body(BodyInserters.fromValue(jsonRequest))
                    .exchange().block()
if (!meteringResponse!!.statusCode().is2xxSuccessful) {
    logger.warn("Failure POSTing metering data to $meteringUrl (${meteringResponse.statusCode()}):" +
                                " ${meteringResponse.bodyToMono<String>()}\n" + jsonRequest)
        }
}

Lua

This example demonstrates a metering request sent via Lua using the REST API.

function envoy_on_response(response_handle)
    local api_client = response_handle:streamInfo():dynamicMetadata():get("revenium")["api_client"]
    local status = tonumber(response_handle:headers():get(":status"))
    if (api_client ~= nil and (status >= 200 and status <= 299)) then
        local method = response_handle:streamInfo():dynamicMetadata():get("revenium")["method"]
        local path = response_handle:streamInfo():dynamicMetadata():get("revenium")["path"]
        local scheme = response_handle:streamInfo():dynamicMetadata():get("revenium")["scheme"]
        local api = response_handle:metadata():get("revenium")
        local body = "api=" .. api .. "&productKey=" .. api_client .. "&method=" .. method .. "&url=" .. path
        local headers, response_body = response_handle:httpCall("revenium",
            {
                [":method"] = "POST",
                [":path"] = "/",
                [":authority"] = "revenium",
            },
            body, 5000)
        local ps_status = tonumber(headers[":status"])
        if (ps_status > 200 or ps_status > 299) then
            response_handle:logError("Could not post body to metering beacon: " .. body)
        else
            response_handle:logDebug("Successfully posted body to metering beacon: " .. body)
        end
    end
end