Agent overview

Agent is the intermediary component responsible for retrieving information from a runtime within your API management landscape and sending it to federated API management.

federated API management is a centralized control and monitoring system that oversees and manages multiple runtimes such as API Connect subsystems (DataPower API Gateway and DataPower Nano Gateway, CMS Portal, webMethods API Gateway, Developer Portal) as well as third-party gateways like AWS API Gateway and Azure API Management Service. The developer implements an agent to establish communication between federated API management and runtime. Each type of runtime requires its own agent implementation.

When the agent is implemented and gets started, it initiates communication with federated API management at regular intervals. The agent developer specifies and configures this interval during agent implementation. The agent is implemented to send the following information to federated API management.
  • Runtime registration. Enables the registration of runtimes within federated API management, enabling it to recognize and interact with the runtime. Without registering runtime, federated API management 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, federated API management 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 federated API management, the agent starts sending data to v with the information received from each runtime. You can use federated API management to monitor and manage the overall landscape from the data that is populated in federated API management. The agent makes sure that federated API management 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.

Prerequisite - Register runtime type. Among other tasks, the agent's responsibilities include registering runtimes in federated API management. One of the attributes of a runtime is its type, which must be registered in federated API management before the runtime itself can be registered. Hence, it is essential to make sure the runtime type that the agent consumes is registered in federated API management. Registering a runtime type is one-time activity where a new runtime type intended for monitoring through federated API management is registered. By default, the runtime types - DataPower API Gateway and DataPower Nano Gateway, CMS Portal, webMethods API Gateway, Developer Portal are already registered within federated API management. The runtime type helps federated API management to identify the types of operations it supports. For instance, webMethods 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 federated API management.

federated API management expects the following information from agent in accordance with the workflow diagram.

  • Register runtime. Registering the runtime is crucial to ensure that federated API management can manage and interact with the runtime effectively. federated API management must recognize the runtime for seamless integration, which needs that the agent registers the runtime. For registration, federated API management 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 federated API management. This makes sure that the agent's responsibilities are clearly defined and aligned with the operational requirements of federated API management.

  • Publish assets. After runtime registration, publishing asset allows federated API management 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, federated API management 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 federated API management to receive regular health check status updates on the runtime's uptime to accurately assess its availability and status. Within federated API management 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 federated API management. 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. federated API management 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. federated API management 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.
    federated API management 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 federated API management at predetermined intervals, ensuring timely updates on system performance.
    Note: federated API management internally computes the error count based on the collected metrics that are categorized by status code.
  • Asset Synchronization. The process ensures that federated API management remains updated with the recent changes to runtime assets, maintaining synchronization and coherence between the runtime environment and federated API management. After all runtime assets get published to federated API management, 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 federated API management. 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 federated API management.