Agent

Edit online

API 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. The 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.

agent
When the agent is implemented and gets started, it initiates communication with API Control Plane at regular intervals. The agent developer specifies and configures this interval 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. It includes 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 makes sure 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.

Agent workflow

Prerequisite - 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 make sure the runtime type that the agent consumes is registered in API Control Plane. Registering a 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 - IBM webMethods API Gateway and IBM webMethods 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, IBM webMethods API Gateway runtime type can send performance metrics such as transaction events and latency, whereas these metrics are not applicable for IBM webMethods 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 needs 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

    Also, during registration, the developer can specify whether the agent needs to publish assets and synchronize assets and metrics with API Control Plane. This makes sure 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, WEBSOCKET, GRAPHQL, ASYNCAPI)
  • 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 use 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 uses the metrics to generate illustrating consumption trends and patterns that are observed across APIs and runtimes. Metrics are categorized into two main groups: consolidated metrics and metrics 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.
    API Control Plane collects the following metrics.
    • Transaction count
    • Average total latency
    • Average gateway latency
    • Average backend latency
    • Average response time
    • Average backend response time.
    These datasets are sent to API Control Plane at predetermined intervals, ensuring timely updates on system performance.
    Note: API Control Plane internally computes the error count based on the collected metrics that are categorized by status code.
  • Asset Synchronization. This process ensures that API Control Plane remains updated with the recent changes to runtime assets, maintaining synchronization and coherence between the runtime environment and API Control Plane. After all runtime assets get 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 that are made to the runtime assets and sends only the altered assets (as a delta) to API Control Plane. To accomplish this, the agent uses the timestamp of the last asset synchronization to retrieve all assets that are added, modified, or deleted since that time and sends this delta to API Control Plane.