Understanding the Agent
Agent Implementation ApproachesJAVA-based ImplementationREST API-based ImplementationAgent Deployment ModesStand-alone modeEmbedded modeAPI Control Plane is a centralized control and monitoring system that oversees and manages multiple runtimes such as API Gateway, Developer Portal, Microgateway, and third-party gateways. Developer implements an agent to establish communication between API Control Plane and runtime. Each type of runtime requires its own agent implementation. These agents act as the intermediary component responsible for retrieving information from a runtime within your API management landscape and sending it to API Control Plane.
When the agent is implemented and gets started, it initiates communication with API Control Plane at regular intervals specified and configured for the agent by the developer; this interval is defined during agent implementation. The agent is implemented to send the following information to API Control Plane:
Runtime registration. Enables the registration of runtimes within API Control Plane, enabling it to recognize and interact with the runtime. Without registering runtime, API Control Plane cannot process any information from the runtime. Hence, it is the first and most crucial step in the agent implementation.
Health check status. Reports on the health status of the runtime, whether it is operational and running smoothly. The health status is commonly referred to as the heartbeat.
Asset information. Includes details about the assets in the runtime. Currently, API Control Plane supports API assets exclusively, with plans to expand support to other asset types in future releases.
Runtime metrics. Provides performance insights at both the API and runtime levels, including transaction count, error count, average latency, average response time, and average backend response time.
As the runtimes establish connectivity with API Control Plane, the agent starts sending data to API Control Plane with the information received from each runtime. You can use API Control Plane to monitor and manage the overall landscape from the data that is populated in API Control Plane. The agent ensures that API Control Plane stays up to date with the current state of the runtimes and their associated assets, enabling effective monitoring, and troubleshooting.
The following workflow outlines the sequence of the agent functionalities:
Pre-requisite: Register runtime type. Among other tasks, the agent’s responsibilities include, registering runtimes in API Control Plane. One of the attributes of a runtime is its type, which must be registered in API Control Plane before the runtime itself can be registered. Hence, it is essential to ensure the runtime type that the agent consumes is registered in API Control Plane. Registering runtime type is one time activity where a new runtime type intended for monitoring through API Control Plane is registered. By default, the runtime types - webMethods.io API Gateway and webMethods.io Developer Portal are already registered within API Control Plane. The runtime type helps API Control Plane to identify the types of operations it supports. For instance, webMethods.io API Gateway runtime type can send performance metrics such as transaction events and latency, whereas these metrics are not applicable for Developer Portal runtime type. If you want to implement an agent for a third-party gateway like Amazon API Gateway, you need to register Amazon API Gateway as a runtime type in API Control Plane.
API Control Plane expects the following information from agent in accordance with the workflow diagram:
Register runtime. Registering the runtime is crucial to ensure that API Control Plane can manage and interact with the runtime effectively. API Control Plane must recognize the runtime for seamless integration, which necessitates that the agent registers the runtime. For registration, API Control Plane must have the following mandatory runtime details, without which registration cannot be completed:
- Runtime ID
- Runtime name
- Runtime type
- Deployment type
Additionally, during registration, the developer can specify whether the agent needs to publish assets and synchronize assets and metrics with API Control Plane. This ensures that the agent’s responsibilities are clearly defined and aligned with the operational requirements of API Control Plane.
Publish assets. After runtime registration, publishing asset allows API Control Plane to maintain a complete and up-to-date inventory of all APIs within the runtime. This visibility is crucial for effective management and operational oversight. For publish assets, API Control Plane must have the following mandatory API details, without which assets cannot be published:
- API ID
- API name
- API type (REST, SOAP, ODATA)
Heartbeat Synchronization. It is essential for API Control Plane to receive regular health check status updates on the runtime’s uptime to accurately assess its availability and status. Within API Control Plane terminology, these health check statuses are commonly referred as heartbeats. If the runtime offers REST APIs for querying its current health and status, the agent can utilize this functionality to collect and transmit the data as heartbeats to API Control Plane. However, if the runtime lacks a direct REST API for accessing current health status information, it is the developer’s responsibility to find alternative methods to determine the runtime’s present status.
Metrics Synchronization. API Control Plane utilizes the metrics to generate visualizations illustrating consumption trends and patterns observed across APIs and runtimes. Metrics are categorized into two main groups: consolidated metrics and those segmented by status codes. API Control Plane is equipped to handle metrics categorized by specific status code categories, such as 2xx, 3xx, 4xx, and 5xx. This flexibility enables runtimes to provide detailed insights into performance across various response scenarios, facilitating more detailed analysis. The following metrics are collected by API Control Plane:
- Transaction count
- Average total latency
- Average gateway latency
- Average backend latency
- Average response time
- Average backend response time.
These data sets are sent to API Control Plane at predetermined intervals, ensuring timely updates on system performance.
- Asset Synchronization. This process ensures that API Control Plane remains updated with the latest changes to runtime assets, thereby maintaining synchronization and coherence between the runtime environment and API Control Plane. After all runtime assets have been published to API Control Plane, as outlined in Step 2 - Publish Assets, the agent can optionally be set up to conduct additional checks for periodic updates to these assets. In this optional phase, the agent identifies any modifications made to the runtime assets and sends only the altered assets (as a delta) to API Control Plane. To accomplish this, the agent utilizes the timestamp of the last asset synchronization to retrieve all assets that have been added, modified, or deleted since that time and sends this delta to API Control Plane.
Agent Implementation Approaches
Developer can implement an agent using the following approaches:
JAVA-based Implementation. Developers can use the JAVA based SDK (Software Development Kit) offered by Software AG to implement an agent for each runtime in the API management environment.
REST APIs-based Implementation. Developers can utilize the REST APIs offered by API Control Plane to implement an agent for each runtime in the API management environment using their preferred programming language.
JAVA-based Implementation
What is Agent SDK?
The developer can utilize the Agent SDK to develop an agent for each runtime in your API management environment. The Agent SDK includes libraries, JAVA documentation, and implementation samples to assist developers in creating an agent.
Developer can implement the Agent SDK using either of the following approaches provided in the SDK:
- Manual
- Managed
The main difference between these two approaches lies in the level of abstraction, implementation control, and ease of use when implementing the Agent SDK.
Comparison between Manual and Managed Approach
The following table lists the differences between the managed and manual approaches:
Key points | Manual approach | Managed approach |
---|---|---|
When to use which approach | Use this approach in the following scenarios: |
Pre-requisites: The runtime must expose the necessary REST APIs to retrieve APIs, health check status, and metrics. Note
If the runtime does not expose any of the above mentioned REST APIs then the developer must opt for manual approach.
Use this approach in the following scenarios: |
Connection establishment | The developer must explicitly implement code to establish a connection to the runtime. | The developer must configure the REST API or URL to establish the connection to the runtime and the authentication information. The SDK takes care of managing the connection and authentication. |
Asset retrieval | The developer must also implement code to retrieve the assets from the runtime. | The Agent SDK automatically handles the retrieval of assets from the REST APIs specified by the developer and stores them in an in-memory cache of the agent for asset synchronization. |
Asset synchronization | The developer must implement code to identify the updates made to the assets and synchronize those assets with API Control Plane. | The developer does not need to implement code to identify the updates made to the assets, as this process is automatically managed by the SDK. Instead, the developer’s responsibility lies to implement parsing logic to convert the runtime’s asset into the asset model compatible with API Control Plane. |
Benefits | This approach offers more flexibility and control to the developer but requires more coding effort and customization. | This approach abstracts away many of the lower-level details of connection management and data retrieval, providing a more streamlined experience for the developer. |
Interface utilization | For this approach, developer must use the AgentSDKContextManual interface. For sample, download the API Control Plane 3rd Party Agent SDK zip file from Empower and open the agent-sdk-manual-implementation sample at samples\implementation. |
For this approach, developer must use the AgentSDKContextManaged interface. For sample, download the API Control Plane 3rd Party Agent SDK zip file from Empower and open the agent-sdk-managed-implementation sample at samples\implementation. |
REST API-based Implementation
When the developers does not want to make use of the Agent SDK, they can leverage the REST APIs provided by API Control Plane to implement an agent using their preferred programming language or tool. To view the complete Open API Specifications of the REST APIs exposed by API Control Plane, see webMethods-api-control-plane Git Hub repository.
The following workflow outlines the sequence in which the REST APIs must be utilized to register the runtime for the first time:
Agent Deployment Modes
The agent offers two distinct deployment modes:
Stand-alone mode
In stand-alone mode, the agent operates as a separate component alongside the runtime. Consequently, the agent continues to function independently even if the runtime shuts down.
This mode is relevant when developers do not have access to the runtime’s source code. For instance, if developer wants to connect AWS gateway to API Control Plane, the stand-alone mode would be the appropriate choice as the developer does not have access to the source code of AWS gateway.
Pros | Cons |
---|---|
Independent from runtime. Offers flexibility and resilience, as the agent can continue to run even if the runtime is down or undergoing maintenance. | Increased complexity. Introduces additional complexity in terms of deployment, configuration, and management. It requires coordination between the agent and runtime components. |
Modular deployment. Simplifies management and allows easier updates and scaling. | Potential resource overhead. Incurs additional resource overhead compared to embedded mode. |
Embedded mode
In embedded mode, the agent implementation becomes integrated within the runtime source code. Upon initiating the runtime application, the Agent initializes alongside it. This tight coupling ensures that the agent operates while the runtime is active and becomes inactive when the runtime shuts down.
This mode is only relevant when developers have access to the runtime’s source code, and when the runtime’s source code is developed in JAVA, as the agent SDK code is also written in JAVA.
Pros | Cons |
---|---|
Tight integration. Reduces the operational complexity. | Limited flexibility. Changes to the agent may require modifications to the runtime code, leading to operational complexities and dependencies. |
Ease of deployment. Eliminates the need for separate deployment or configuration steps. | Possible resource utilization. Excessive consumption by the agent may overkill the runtime performance and operation. |
Resource efficiency. Consumes fewer resources compared to stand-alone mode as it operates within the same runtime environment. | Potential runtime instability. Any issues or instability in the agent may affect the overall runtime performance and stability. |
Use Agent SDK
How to Access the Agent SDK?Agent SDK Classes, Interfaces, and MethodsClassesInterfacesMethodsHow to Implement an Agent using SDK?Step 1: Open Visual Studio Code editor.Step 2: Open agent-sdk-managed-implementation sample folder in Visual Studio Code editor.Step 3: Include Agent SDK (api, core, and model) Jars into the application.Step 4: Specify the configurations required to connect the runtime with API Control Plane.Step 5: Register the runtime with API Control Plane.Step 6: Publish the APIs from the runtime to API Control Plane.Step 7: Synchronize the metrics from the runtime to API Control Plane.How to Build the Gradle Project and Run the Jar?How to Deploy and Run the Agent in Docker?Step 1: Build the Docker image.Step 2: Run the Docker image.This section details how to access the Agent SDK, implement the agent using the Managed approach, build and run the Gradle project, and deploy and run the agent in Docker.
How to Access the Agent SDK?
Pre-requisites
Ensure that you have:
- Empower portal login credentials to download jars.
- Installed Java Development Kit (JDK) version 17 or above.
- Access to an API Control Plane instance.
To access Agent SDK
Logon to the Empower portal.
Click Products & Documentation > Download components.
Download the API Control Plane 3rd Party Agent SDK zip file.
The zip file contains the following:
- javadocs folder. Includes extracted javadocs for api, core, and model Jars. Access index.html to view the javadocs of the Agent SDK.
- libs folder. Contains Agent SDK (api, core, and model) Jars and its respective javadocs.
- samples folder. Includes a deployment folder (containing the docker compose files) and implementation folder (containing the Agent SDK Jar information and sample Gradle projects for Managed and Manual implementation).
- readme.md file. Explains the content in the folders that are comprised within the agent-sdk-
-with-implementation-samples zip file.
Extract the agent-sdk-
-with-implementation-samples file at the preferred location in your system.
Agent SDK Classes, Interfaces, and Methods
SDK interfaces and classes help to build runtime-specific agents. Following are the list of classes located inside api Jar in SDK:
Classes
Config: The parent class configuration file, which includes the following classes, each responsible for different aspects of API Control Plane and runtime configurations.
Classes | Description |
---|---|
AuthConfig | Class for providing API Control Plane authentication configurations such as Basic auth, Token-based auth, and so on. |
ControlPlaneConfig | Class for providing the following API Control Plane configurations to which the runtime establishes connectivity: Control Plane URL, Control Plane username, and so on. |
RuntimeConfig | Class for providing the following runtime configurations that you want to administer from API Control Plane: Runtime ID, Name , Description, Type, and so on. |
SdkConfig | The top-level configuration class, which takes the inputs of Runtime configurations, Control Plane configurations, and asset sync intervals. |
TlsConfig | Class for providing the Keystore and Truststore configurations such as keystorePath, truststorePath, keystorePassword, keyAlias, and so on. |
HttpConnectionConfig | Class for providing the HTTP connection specific configurations such as maxConnections, connectionTimeout, maxRetries, and so on. |
Interfaces
Following are the list of interfaces located inside api Jar in SDK:
Interfaces | Description |
---|---|
AgentSdkContextManual | Interface for implementing an agent using Manual approach. For details, see Comparison between Manual and Managed Approach in JAVA-based Implementation. |
AgentSDKContextManaged | Interface for implementing an agent using Managed approach. For details, see Comparison between Manual and Managed Approach in JAVA-based Implementation. |
SdkLogger | Interface for customizing the logging functionality. The SDK offers the following options to capture the logs: |
SdkHttpClient | Interface for customizing the HTTP client. The SDK offers the following options to implement the HTTP client: |
Methods
Following are the methods within the classes and interfaces:
AgentSdkContextManual Interface Methods
Methods | Description |
---|---|
SdkConfig() | The developer must implement this method to return API Control Plane specific and runtime specific configuration objects. |
getLogger() | The developer must implement this method to return the logger object. |
getHttpClient() | The developer must implement this method to return HTTP client object, which establishes communication from the agent to the external entities (runtime and API Control Plane). |
getHeartbeat() | The developer must implement this method to return the heartbeat (health status) object. |
getAPIs() | The developer must implement this method to return the list of APIs object. |
getMetrics() | The developer must implement this method to return the list of metrics object for the transactions performed during the specified synchronization interval. |
getAssetSyncActions() | The developer must implement this method to return the list of asset sync action objects for the specified synchronization interval. |
AgentSdkContextManaged Interface Methods
Methods | Description |
---|---|
SdkConfig() | The developer must implement this method to return API Control Plane specific and runtime specific configuration objects. |
getLogger() | The developer must implement this method to return the logger object. |
getHttpClient() | The developer must implement this method to return HTTP client object, which establishes communication from the agent to the external entities (runtime and API Control Plane). |
getRequestBuilders() | The developer must implement this method to return the list of RequestBuilders object for fetching APIs, Heartbeats, and Metrics individually. The SDK utilizes these implementations to construct SdkRequests and sends them to the runtime. |
getRuntimeResponseParserFactory() | The developer must implement this method to return the ResponseParserFactory object for parsing the response received from the runtime to API Control Plane compatible model. The following methods build and return the parser:
|
Classes: Authconfig, TlsConfig, SdkConfig, ControlPlaneConfig, RuntimeConfig, HttpConnectionConfig
Common Methods in all Classes
Methods | Description |
---|---|
Builder | Creates an object with the mandatory fields required for the class. |
build() | Returns an object built from the values passed through the Builder class. This method is used to create a new instance of the class with the required information. Let’s take Authconfig class as an example and understand the methods within the class: AuthConfig.Builder(agentConfiguration.controlPlaneUsername, agentConfiguration.controlPlanePassword) // Creates a Builder class with the following mandatory fields, controlPlaneUsername and controlPlanePassword .build(); // Creates an Authconfig object with controlPlaneUsername and controlPlanePassword |
SdkLogger Interface Methods
Methods | Description |
---|---|
trace() | The developer must implement this method to log the message at the trace level. |
debug() | The developer must implement this method to log the message at the debug level. |
info() | The developer must implement this method to log the message at the info level. |
error() | The developer must implement this method to log the message at the error level along with an exception object (if available). |
logError(String msg, Throwable t) | The developer must implement this method to log the errors without any message formatting along with an exception object (if available). |
SdkHttpClient Interface Methods
Methods | Description |
---|---|
execute() | SDK has a default implementation for the execute() method, which facilitates the protocol specific SdkHttpRequest to external party and returns the corresponding SdkHttpResponse. |
executeDelete() | The developer must implement this method to execute the SdkHttpRequest for an external party using the DELETE HTTP protocol and return the corresponding SdkHttpResponse. |
executeGet() | The developer must implement this method to execute the SdkHttpRequest for an external party using the GET HTTP protocol and return the corresponding SdkHttpResponse. |
executePost() | The developer must implement this method to execute the SdkHttpRequest for an external party using the POST HTTP protocol and return the corresponding SdkHttpResponse. |
executePut() | The developer must implement this method to execute the SdkHttpRequest for an external party using the PUT HTTP protocol and return the corresponding SdkHttpResponse. |
How to Implement an Agent using SDK?
This tutorial demonstrates how to implement an agent using the Managed sample provided in the agent-sdk-version-with-implementation-samples zip file, using Visual Studio Code editor.
Pre-requisites
Ensure that you have:
- Extracted the agent-sdk-version-with-implementation-samples zip file to your preferred location.
- Installed the Java plugin for Visual Studio Code editor.
- Verified if the runtime and API Control Plane for which you want to establish connectivity using the agent are up and running. This step is crucial for registering the runtime with API Control Plane.
- Created the runtime type in API Control Plane for your third-party runtime.
The REST APIs to retrieve the heartbeats(status), APIs, and metrics from the runtime. However, if the runtime lacks a direct REST API for accessing the heartbeats, APIs, and metrics, use alternate endpoints to retrieve the same. Ensure that these REST APIs or endpoints retrieve the required information completely to construct API Control Plane compatible heartbeats, APIs, and metrics.
If no REST API or endpoint is available to retrieve the heartbeats(status), APIs, and metrics from the runtime, use the Manual implementation approach, where you can implement a custom solution to check and retrieve the heartbeats, APIs, and metrics.
To implement an agent using the Managed sample
Step 1: Open Visual Studio Code editor.
Step 2: Open agent-sdk-managed-implementation sample folder in Visual Studio Code editor.
Go to File > Open Folder and select agent-sdk-version-with-implementation-samples\samples\implementation\agent-sdk-managed-implementation.
The agent-sdk-managed-implementation sample opens in Visual Studio Code.
Step 3: Include Agent SDK (api, core, and model) Jars into the application.
Select build.gradle in your agent-sdk-managed-implementation folder.
Optional. Specify the location of api, core, and model Jars under dependencies in the application code.
Note: This step applies only if you have moved the Agent SDK Jars from the libs folder outside the extracted, agent-sdk-version-with-implementation-samples folder.
For example, If you have moved the Agent SDK Jars from the extracted (libs) folder to C:\Users\test\Control Plane\libs, specify the path of the location under dependencies in the application code as follows
dependencies { implementation(files("C:\\Users\\test\\Control Plane\\libs\\controlplane-agentsdk-api-<version>.jar")) implementation(files("C:\\Users\\test\\Control Plane\\libs\\controlplane-agentsdk-core-<version>.jar")) implementation(files("C:\\Users\\test\\Control Plane\\libs\\controlplane-agentsdk-model-<version>.jar"))
Ignore this step if the Agent SDK Jars are within the extracted folder. The following code reads the location of the Jars from the extracted folder.
Verify if the Jars are included properly in the application.
a. Click Terminal > New Terminal. b. Run the following command from the agent-sdk-managed-implementation location:
gradle build (if you have installed Gradle globally) (or) ./gradlew build
Build Successful message appears only when the Jars are included properly, and the application compiles successfully.
Troubleshooting Tips: For permission denied issues, perform the following steps:
1.Verify if the Gradle has execution permissions.
2.Run
gradle build
(or)./gradlew build
3.If the issue persists, run sh
./gradlew build
(or)bash ./gradlew build
Step 4: Specify the configurations required to connect the runtime with API Control Plane.
Open application.properties located at src\main\resources.
The application.properties file contains properties related to the runtime, agent, and API Control Plane that are required to establish connection between the runtime and API Control Plane.
Specify the value for each property.
Properties Description asset.sync.interval The duration in seconds in which the agent must synchronize the changes made to the assets to API Control Plane.
Default: 900 seconds
Min: 60 seconds
Max: 21600 seconds (6 hours)heartbeat.interval The duration in seconds in which the agent must send health check status to API Control Plane.
Default: 30 seconds
Min: 15 seconds
Max: 900 seconds (15 minutes)metrics.send.interval The duration in seconds in which the runtime must send metrics to API Control Plane.
Default: 900 seconds
Min: 60 seconds
Max: 7200 seconds (2 hours)control.plane.password Mandatory. Password of the corresponding username, which is used for logging into API Control Plane. control.plane.url Mandatory. The valid URL that is used to access API Control Plane.
For example: https://localhost:8080control.plane.username Mandatory. Username that is used to log in to API Control Plane. is.tls.enabled Optional. The SSL certification of API Control Plane.
Possible values: true (or) falsetls.trust.store.password Optional. Password required to access the truststore file.
If is.tls.enabled property is set to true, you must specify a value for this property.tls.trust.store.path Optional. Location of the truststore file.
If is.tls.enabled property is set to true, you must specify a value for this property.tls.trust.store.type Optional. Type of truststore.
If is.tls.enabled property is set to true, you must specify a value for this property.log.level Optional. The level of logs to be captured.
Possible values: trace, debug, info, and error.runtime.description Optional. The runtime description.
Description must not exceed 300 characters.runtime.id Mandatory. The runtime ID.
ID field accepts alphanumeric characters, underscore(_), and hiphen(-)runtime.location Optional. The location where the runtime is deployed.
Example: DENVER
Location name cannot be empty and must not exceed 50 characters.runtime.name Mandatory. The runtime name. This property defines how you want to identify the runtime in API Control Plane.
Name must not exceed 50 characters.runtime.region Mandatory. The region name where the runtime is hosted.
Example: EAST US
Region name must not exceed 50 characters.runtime.type Mandatory. The Id of the runtime type.
Example: Azure_GW
Pre-defined types: WEBMETHODS_DEVELOPER_PORTAL, WEBMETHODS_API_GATEWAY
Note:Ensure to verify if the runtime type exists in API Control Plane. If it does not exist, use the following Runtime Type Management Service REST API to add the runtime type:
POST /api/assetcatalog/v1/runtimes/types
Example: POST https://localhost:8080/api/assetcatalog/v1/runtimes/types
Content-Type: application/json{
“id”:“Azure”, // ID of the runtime type
“name”:“azure_runtime” // Name of the runtime type
}
For details, see Runtime Type Management REST API.runtime.url Mandatory. The host name of the runtime.
Example: http://demo.apigw-aw-us.webmethods.in
This URL appears in the Runtime details page in the API Control Plane application. API Control Plane utilizes the runtime URL to open the Gateway from the API Control Plane application through the Open in Gateway option in the Manage API’s page.runtime.heartbeat.url Mandatory. A valid REST API that retrieves the heartbeats (status) of the runtime.
Agent SDK retrieves the heartbeat (status) of the runtime using the REST API specified in this property.
Example: https://localhost:5555/health
The implementation logic for retrieving the heartbeats using this REST API is available in HeartbeatManager interface located at src\main\java\manager. For details, see Step 5: Register the runtime with API Control Plane.runtime.heartbeat.url.auth Mandatory. The value of the Authorization header for the REST API, specified in the runtime.heartbeat.url property.
Example: “Basic dXNlcm5hbWU6cGFzc3dvcmQ=”
For this tutorial, you can specify the Authorization header value in the application.properties file. However, since this is sensitive information, it is recommended to use a secret store to securely store and access this data from your deployments.
The implementation logic is available in the HeartbeatManager interface located at src\main\java\manager. For details, see Step 5: Register the runtime with API Control Plane.runtime.metrics.url Mandatory. A valid REST API that retrieves the metrics completely from the runtime to construct API Control Plane compatible metrics. For details on the metrics supported by API Control Plane, see Understanding the Agent section.
Agent SDK retrieves the metrics from the runtime using the REST API specified in this property.
Example: https://localhost:5555/metrics
The implementation logic for retrieving the metrics using this REST API is available in MetricsManager interface located at src\main\java\manager. For details, see Step 7: Synchronize the metrics from the runtime to API Control Plane.runtime.metrics.url.auth Mandatory. The value of the Authorization header for the REST API, specified in the runtime.metrics.url property.
Example: “Basic dXNlcm5hbWU6cGFzc3dvcmQ=”
For this tutorial, you can specify the Authorization header value in the application.properties file. However, since this is sensitive information, it is recommended to use a secret store to securely store and access this data from your deployments.
The implementation logic for retrieving the metrics using this REST API is available in MetricsManager interface located at src\main\java\manager. For details, see Step 7: Synchronize the metrics from the runtime to API Control Plane.runtime.api.url Mandatory. A valid REST API that retrieves all APIs from the runtime completely.
The Agent SDK retrieves the APIs from the runtime using the REST API specified in this property.
Example: https://localhost:5555/apis
The implementation logic for retrieving the APIs using this REST API is available in APIManager interface located at src\main\java\manager. For details, see Step 6: Publish the APIs from the runtime to API Control Plane.runtime.api.url.auth Mandatory. The value of the Authorization header for the REST API, specified in the runtime.api.url property.
Example: “Basic dXNlcm5hbWU6cGFzc3dvcmQ=”
For this tutorial, you can specify the Authorization header value in the application.properties file. However, since this is sensitive information, it is recommended to use a secret store to securely store and access this data from your deployments.
The implementation logic for retrieving the APIs using this REST API is available in APIManager interface located at src\main\java\manager. For details, see Step 6: Publish the APIs from the runtime to API Control Plane.should.publish.assets Enable or disable the publishing of assets to API Control Plane.
Possible values: true (or) false
Agent SDK publishes the APIs from the runtime to API Control Plane whenever the agent starts, provided that should.publish.assets is set to true. For details, see Step 6: Publish the APIs from the runtime to API Control Plane.should.send.metrics Enable or disable sending API metrics to API Control Plane.
Possible values: true (or) false
Agent SDK synchronizes the metrics from the runtime to API Control Plane only if you set should.send.metrics to true. For details, see Step 7: Synchronize the metrics from the runtime to API Control Plane.should.sync.assets Enable or disable syncing of assets to API Control Plane.
Possible values: true (or) false
Agent SDK synchronizes the APIs periodically with API Control Plane according to the value specified in asset.sync.interval. Within each synchronization interval, Agent SDK synchronizes only the assets that are newly created, updated, or deleted with API Control Plane. For details, see Step 6: Publish the APIs from the runtime to API Control Plane.
Step 5: Register the runtime with API Control Plane.
Open HeartbeatManager interface located at src\main\java\manager.
Construct the getHeartbeatRestRequestBuilder() method in the HeartbeatManager interface to retrieve the heartbeats (status) of the runtime.
This step is essential for retrieving and sending the heartbeats (status) of the runtime to the API Control Plane periodically. To accomplish this, you must instruct the Agent SDK on how to retrieve the heartbeats from the runtime using the REST API. This involves implementing the getHeartbeatRestRequestBuilder() method in the HeartbeatManager interface to return a RequestBuilder object.
Let’s take the following REST API call as an example and construct a RequestBuilder for retrieving heartbeats (status) from the runtime.
// REST API call GET /health HTTP/1.1 // REST API (specified in the runtime.heartbeat.url property)to retrieve the heartbeats of the runtime using POST method in HTTP protocol. Host: localhost:5555 //Runtime URL (specified in the runtime.url property) Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U= // Text highlighted in bold is the AuthHeader value of the REST API (specified in the runtime.heartbeat.url.auth property)
For the REST API call mentioned above, the RequestBuilder code must be as follows. Copy and paste the following code into the build() method within getHeartbeatRestRequestBuilder() method. This code is also available as a comment in the HeartbeatManager class, which you can uncomment and use. Ensure to remove return null in the line number 57 if you uncomment and use the code from the HeartbeatManager class.
Note: The following getHeartbeatRestRequestBuilder() code is only for constructing the request for the API call mentioned above. You can modify it based on your API request.
// To add Auth header for the health endpoint as the API above has a header with authentication. HashMap<String,String> headers=new HashMap<>(); headers.put(HttpHeaders.AUTHORIZATION,agentConfiguration. heartbeatURLAuthHeader); return new SdkHttpRequest.Builder(agentConfiguration.heartbeatURL,HttpMethod.GET) // agentConfiguration.heartbeatURL returns the Heartbeat URL (/health) using the GET method. .headers(headers) //To add the Headers constructed above .maxRetries(3) //The maximum number of times the HTTP client must re-establish the connection in case of HTTP connection failure. .retryInterval(300) //The duration in seconds in which the HTTP client must re-establish the connection in case of HTTP connection failure. .build();
After implementing the code to send a request to the runtime for heartbeats, the next step is to parse the received response(heartbeats) into an API Control Plane compatible heartbeat model.
Construct the getHeartbeatResponseParser() method to parse the response(heartbeats) received from the runtime to API Control Plane compatible heartbeat model. For details on the Heartbeat model, see com.softwareag.controlplane.agentsdk.model package > Heartbeat in the javadocs.
Assume the following response (heartbeats) is sent from the runtime to the agent when the REST API mentioned in the Step 2 is invoked.
{ "status":true }
The agent must send this response to API Control Plane, which requires the heartbeats to be in the following API Control Plane compatible model:
{ "created": 1710858635000, "runtimeId": "35ea9d8c-2b93-4517-9d97-269921009cf5", "active":1 }
Here, active: 0 indicates that the runtime is down or inactive and active: 1 indicates that the runtime is up or active.
To achieve this, you must implement code to parse the response. Copy and paste the following code into the getHeartbeatResponseParser() method in the HeartbeatManager interface:
Note: The following getHeartbeatResponseParser() code is only for parsing the response mentioned above. You can modify it based on your API response.
// To get the current timestamp long timestamp=System.currentTimeMillis(); // To construct ObjectMapper object ObjectMapper objectMapper=new ObjectMapper().configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES,false); // To convert the response to SDK Http response SdkHttpResponse responseParsed=(SdkHttpResponse) response; try{ // To get the response body as string String body =(String) responseParsed.getBody(); // To create a health object to capture the response (heartbeats) of the runtime and convert the health object to a API Control Plane compatible heartbeat object. Health health=objectMapper.readValue(body, Health.class); // To construct the heartbeat object based on the received health object Heartbeat heartbeat=new Heartbeat.Builder(agentConfiguration.runtimeId) .active((health.getStatus())?Heartbeat.Status.ACTIVE:Heartbeat.Status.INACTIVE) .created(timestamp) .build(); // Returns the heartbeat return heartbeat; }catch(Exception e) { e.printStackTrace(); }
The next step is to build and run the agent application to verify if the runtime is registered with API Control Plane.
To build the Jar, run the following command from agent-sdk-managed-implementation location in the Terminal:
gradle build (if you have configured Gradle globally in your system) (or) ./gradlew build
Build Successful message appears and a sample-managed-sdk-version.jar is created at build\libs
To run the Jar, run the following command from agent-sdk-managed-implementation location in the Terminal:
java -jar ./build/libs/sample-managed-sdk-<version>.jar
where, /build/libs/sample-managed-sdk-
.jar is the path where the Jar is created.The agent application starts.
Verify if the runtime is registered with API Control Plane and if the heartbeats (status) are sent to API Control Plane successfully.
a. Open the API Control Plane application.
b. Click on the Runtimes tab.
c. Check if the runtime (specified in the application.properties is listed in the Manage Runtimes page.
If the runtime is listed, it indicates that the runtime is successfully registered with API Control Plane.d. Check the status of that corresponding runtime in the Status column.
The status appears green only if the runtime is up and the heartbeats (status) are received successfully by the API Control Plane.You can also click the icon under the Action column corresponding to the runtime in the Manage Runtimes page to monitor the status of the runtime for a specific time interval.
Note: When the agent application starts, it reads the runtime configurations from the application.properties file and registers with API Control Plane. As a result, the runtime appears on the Runtimes page in API Control Plane immediately after registration. However, to check the runtime’s heartbeat (status) in API Control Plane, you must wait for the synchronization interval specified in the application.properties file to elapse.
You have successfully registered your runtime with API Control Plane and API Control Plane started receiving the status of the runtime. Now, you can stop the agent connection and implement code for publishing the APIs from the runtime to API Control Plane.
Step 6: Publish the APIs from the runtime to API Control Plane.
Agent SDK performs this step only if you have specified should.publish.assets or should.sync.assets to true in application.properties file.
Open APIManager interface located at src\main\java\manager.
Construct the getAPIRestRequestBuilder() method in the APIManager interface to retrieve the APIs from the runtime.
This step is essential for retrieving and sending the APIs from the runtime to API Control Plane. To accomplish this, you must instruct the Agent SDK on how to retrieve the APIs from the runtime using the REST API. This involves implementing the getAPIRestRequestBuilder() method in the APIManager interface to return a RequestBuilder object.
Let’s take the following REST API call as an example and construct a RequestBuilder for retrieving the APIs from the runtime.
POST /apis HTTP/1.1 // REST API(specified in the runtime.api.url property) to retrieve the Apis of the runtime using POST method in HTTP protocol. Host: localhost:5555 // Runtime URL (specified in the runtime.url property) Content-Type: application/json // The request body in json format Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U= // Text highlighted in bold is the AuthHeader value of the REST API (specified in the runtime.api.url.auth property) //Sample request body to retrieve the APIs in the specified time period in the interval of 60 seconds. { "from":1704430169000, "to":1715316569000, "interval":60 }
Copy and paste the following code into the getAPIRestRequestBuilder() method. This code is also available as a comment in the APIManager interface, which you can uncomment and use.
Note: The following getAPIRestRequestBuilder() code is only for constructing the request for the API above. You can modify it based on your API request.
// To add Auth header for the health endpoint as the API above has a header with authentication. HashMap<String,String> headers=new HashMap<>(); headers.put(HttpHeaders.AUTHORIZATION,agentConfiguration.apisURLAuthHeader); // To add the content type and the request body format. headers.put(HttpHeaders.CONTENT_TYPE, "application/json"); // To construct your request body. The context is available for the getAPIRestRequestBuilder() method as a parameter. String requestBody="{'from':"+context.getFromTimestamp()+",'to':"+context.getToTimestamp()+",'interval':"+context.getInterval()+"}"; // To retrieve the APIs according to the request body above return new SdkHttpRequest.Builder(agentConfiguration.apisURL,HttpMethod.POST) // agentConfiguration.apisURL returns the API URL (/apis) using the POST method. .body(requestBody) .headers(headers) // To add the Headers constructed above. .maxRetries(3) // The maximum number of times the HTTP client must re-establish the connection in case of HTTP connection failure. .retryInterval(300) // The duration in seconds in which the HTTP client must re-establish the connection in case of HTTP connection failure. .build();
After implementing the code to send a request to the runtime for APIs, the next step is to parse the received response (APIs) into an API Control Plane-compatible API model.
Construct the getAPIResponseParser() method to parse the response(APIs) received from the runtime to API Control Plane compatible API model. For details on the API model supported by API Control Plane, see com.softwareag.controlplane.agentsdk.model package > API in the javadocs. Implement the getAPIRestRequestBuilder() method to parse the response you receive from the runtime to API Control Plane compatible API model as specified in the javadocs.
Note: Ensure to place your code into the parseList() method within getAPIRestRequestBuilder() method in the APIManager interface.
After you implement the code, the next step is to build and run the agent application to verify if the APIs are published from the runtime to API Control Plane.
To build the Jar, run the following command from agent-sdk-managed-implementation location in the Terminal:
gradle build (if you have configured Gradle globally in your system) (or) ./gradlew build
Build Successful message appears and a sample-managed-sdk-version.jar is created at build\libs
To run the Jar, run the following command from agent-sdk-managed-implementation location in the Terminal:
java -jar ./build/libs/sample-managed-sdk-<version>.jar
where, /build/libs/sample-managed-sdk-
.jar is the path where the Jar is created.The agent application starts.
Verify if the APIs are published from the runtime to API Control Plane successfully.
a. Open the API Control Plane application.
b. Click on the Runtimes tab.
Check if the runtime (specified in the application.properties is listed in the Manage Runtimes page.c. Click Action menu > Details of the corresponding runtime for which, you want to verify if its APIs are published to API Control Plane.
d. Click APIs tab.
A list of all the APIs associated with the runtime appears. You can also view the runtimes and its associated APIs in the Manage APIs page.You have successfully published your APIs from the runtime to API Control Plane. Now, you can stop the agent connection and implement code for synchronizing the API metrics from the runtime to API Control Plane.
Step 7: Synchronize the metrics from the runtime to API Control Plane.
Agent SDK performs this step only if you have specified should.send.metrics to true in the application.properties file.
Open MetricsManager interface located at src\main\java\manager.
Construct the getMetricsRequestBuilder() method in the MetricsManager interface to retrieve the metrics from the runtime.
This step is essential for retrieving and sending the metrics from the runtime to API Control Plane. To accomplish this, you must instruct the Agent SDK on how to retrieve the metrics from the runtime using the REST API. This involves implementing the getMetricsRequestBuilder() method in the MetricsManager interface to return a RequestBuilder object.
Let’s take the following REST API call as an example and construct a RequestBuilder for retrieving the metrics from the runtime.
POST /metrics HTTP/1.1 // REST API(specified in the runtime.metrics.url property) to retrieve the metrics of the runtime using POST method in HTTP protocol. Host: localhost:5555 // Runtime URL (specified in the runtime.url property) Content-Type: application/json // The request body in json format Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U= // Text highlighted in bold is the AuthHeader value of the REST API (specified in the runtime.metrics.url.auth property) //Sample request body to retrieve the metrics in the specified time period in the interval of 60 seconds. { "from":1704430169000, "to":1715316569000, "interval":60 }
Copy and paste the following code into the getMetricsRequestBuilder() method. This code is also available as a comment in the MetricsManager interface, which you can uncomment and use.
Note: The following getMetricsRequestBuilder() code is only for constructing the request for the API above. You can modify it based on your API request.
// To add Auth header for the health endpoint as the API above has a header with authentication. HashMap<String,String> headers=new HashMap<>(); headers.put(HttpHeaders.AUTHORIZATION,agentConfiguration.metricsURLAuthHeader); // To add the content type and the request body format. headers.put(HttpHeaders.CONTENT_TYPE, "application/json"); // To construct your request body. The context is available for the getAPIRestRequestBuilder() method as a parameter. String requestBody="{'from':"+context.getFromTimestamp()+",'to':"+context.getToTimestamp()+",'interval':"+context.getInterval()+"}"; // To retrieve the metrics according to the request body above return new SdkHttpRequest.Builder(agentConfiguration.metricsURL,HttpMethod.POST) // agentConfiguration.metricsURL returns the metrics URL (/metrics) using the POST method. .body(requestBody) .headers(headers) // To add the Headers constructed above. .maxRetries(3) // The maximum number of times the HTTP client must re-establish the connection in case of HTTP connection failure. .retryInterval(300) // The duration in seconds in which the HTTP client must re-establish the connection in case of HTTP connection failure. .build();
After implementing the code to send a request to the runtime for metrics, the next step is to parse the received response (metrics) into an API Control Plane-compatible API model.
Construct the getMetricsResponseParser() method to parse the response (metrics) received from the runtime to API Control Plane compatible metrics model. For details on the API model supported by API Control Plane, see com.softwareag.controlplane.agentsdk.model package > Metrics in the javadocs. Implement the getMetricsResponseParser() method to parse the response you receive from the runtime to API Control Plane compatible metrics model as specified in the javadocs.
Note: Ensure to place your code into the parseList() method within getMetricsResponseParser() method in the MetricsManager interface.
After you implement the code, the next step is to build and run the agent application to verify if the metrics are published from the runtime to API Control Plane.
To build the Jar, run the following command from agent-sdk-managed-implementation location in the Terminal:
gradle build (if you have configured Gradle globally in your system) (or) ./gradlew build
Build Successful message appears and a sample-managed-sdk-version.jar is created at build\libs
To run the Jar, run the following command from agent-sdk-managed-implementation location in the Terminal:
java -jar ./build/libs/sample-managed-sdk-<version>.jar
where, /build/libs/sample-managed-sdk-
.jar is the path where the Jar is created.The agent application starts.
Verify if the API metrics are published from the runtime to API Control Plane successfully.
a. Open the API Control Plane application.
b. Click on the Runtimes tab.
c. Check if the runtime (specified in the application.properties is listed in the Manage Runtimes page.
d. Click the icon under the Action column corresponding runtime for which, you want to verify if its metrics are published to API Control Plane.
The Runtime specific monitor page renders the metrics of that runtime pertaining to a specified time interval. It lists the metrics such as Transactions, Error rate, Availability, Response time, and so on. For details, see Monitor Runtimes page.
You have successfully synchronized your metrics from the runtime to API Control Plane. In this procedure, you learned how to implement code that instructs the Agent SDK to perform its core functions and how to build and test each use case individually. The next procedure explains how to build and test the entire package (Jar). You can skip the next procedure if you have built the Jar and the agent application is running.
How to Build the Gradle Project and Run the Jar?
Let’s look at a sample scenario through which you can build the entire Gradle project (Jar) and run the Jar using Visual Studio Code editor.
To build the Gradle project and run the Jar
Open AgentApplication located at src\main\java\manager\model in the Visual Studio Code editor.
Run the following command from agent-sdk-managed-implementation location in the Terminal:
gradle build (if you have configured Gradle globally in your system) (or) ./gradlew build
Build Successful message appears and a sample-managed-sdk-
.jar is created at build\libsUse the following command from agent-sdk-managed-implementation location in the Terminal to run the Jar directly:
java -jar ./build/libs/sample-managed-sdk<version>.jar
where, /build/libs/sample-managed-sdk-
.jar is the path where the Jar is created.The agent application starts. You can verify if the runtime name specified in the application.properties file is listed in the Manage Runtimes page in API Control Plane application.
You can either run the Jar directly or deploy it in Docker and run to start the agent application.
How to Deploy and Run the Agent in Docker?
Let’s look at a sample scenario through which you can deploy and run the agent in Docker using Visual Studio Code editor.
Pre-requisites
Ensure that you have started the Docker client.
The default docker image tag specified in the build.gradle file is agent-managed-sdk:latest.
Step 1: Build the Docker image.
Run the following command from agent-sdk-managed-implementation location in the Terminal:
gradle buildDockerImage (if you have configured Gradle globally in your system) (or) ./gradlew buildDockerImage
buildDockerImage builds a Docker image with the default image tag name.
The docker image, agent-managed-sdk:latest is built.
Verify if the agent-managed-sdk:latest image is listed in the Docker client or run the following command to verify if the image is listed in the docker images:
docker images
To rename the tag, specify the following command from agent-sdk-managed- implementation location in theTerminal:
gradle buildDockerImage -Ptag=<new_tag_name> (or) ./gradlew buildDockerImage -Ptag=<new_tag_name>
The new image tag is created with the specified name.
Step 2: Run the Docker image.
Go to docker-compose located at agent-sdk-version-with-implementation-samples\samples\deployment in Visual Studio Code editor.
The .env and docker-compose.yml files include properties outlined in the application.properties file.
Specify the value for each property. For details about the properties, see application.properties.
Ensure to update the DOCKER_IMAGE property with the new image tag name, if you have replaced the default name.
Run the following command from the deployment location in the Terminal:
docker-compose up -d
The output displays as follows:
The agent application starts. You can verify if the runtime name specified in the .env file is listed in the Manage Runtimes page in API Control Plane application.
Agent SDK Implementation Samples
Agent SDK Implementation SamplesAmazon API GatewayAzure API Management ServiceAgent SDK Implementation Samples
Amazon API Gateway
An agent implementation utilizing the API Control Plane Agent SDK is developed for the Amazon API Gateway integration and is available at https://github.com/SoftwareAG/webmethods-api-control-plane-agent-aws. Using this implementation project, Amazon API Gateway can now integrate with API Control Plane as a runtime.
Azure API Management Service
An agent implementation utilizing the API Control Plane Agent SDK is developed for the Azure API Management Service integration and is available at https://github.com/SoftwareAG/webmethods-api-control-plane-agent-azure. Using this implementation project, Azure API Management Service can now integrate with API Control Plane as a runtime.