Skip to main content

What Are Monitoring Agents?

A Monitoring Agent is a containerized application provided by Generator Labs that acts as a front-end for certificate monitoring. Agents allow you to control where connections to your services originate from, enabling monitoring of internal networks, private IP space, and services not accessible from the public internet.

How Monitoring Agents Work​

By default, certificate monitoring connects to your services over the public internet from Generator Labs infrastructure. When you deploy and configure a monitoring agent in your environment, the system routes monitoring checks through your agent instead. This enables monitoring of services on private networks, behind firewalls, or in isolated environments.

Multiple monitoring agents can be configured and assigned to monitoring profiles. When multiple agents are assigned to a profile, the system load balances monitoring requests between them for improved reliability and failover. The agents list shows each agent's name, status, and the number of running instances.

Use Cases​

Monitoring agents are ideal for several use cases:

  • Monitoring services on private networks or internal IP ranges not accessible from the internet
  • Controlling geographic location of monitoring traffic for compliance or performance reasons
  • Accessing services behind firewalls or VPNs without opening external access
  • Providing redundancy with multiple agent deployments across different locations or availability zones

Deployment Options​

The monitoring agent is available as a container image from the Generator Labs GitHub repository. Deploy agents in the following environments:

  • Kubernetes clusters
  • AWS ECS (Elastic Container Service)
  • Docker or Docker Compose
  • Other container orchestration platforms

Each agent deployment requires authentication credentials provided by the portal. These environment variables identify the agent to the Generator Labs platform and authorize it to perform monitoring checks on your behalf.

Agent Management​

Create new agents through the Account ➡️ Agents section of the portal. Each agent requires a display name and optional timeout alert settings. After creation, the portal provides authentication environment variables for your container deployment. Agents appear as "Active" once they connect and check in with the platform. See installing monitoring agents for deployment instructions.

To use a monitoring agent, assign it to a profile in Certificate Monitoring ➡️ Manage ➡️ Profiles. Enable Use Internal Monitoring Agent(s) and select one or more agents. All monitors using that profile will then route checks through the selected agents instead of the public internet.

Timeout Alerting​

Each agent can be configured with a timeout threshold (between 5 and 900 minutes). When Alert on Timeout is enabled for an agent, the platform monitors each persistent instance's last check-in time and sends alerts if an instance goes silent beyond the threshold.

Alerts are only generated for persistent instances — those running in long-lived containers such as Kubernetes deployments or Docker Compose services. Single-run instances (used for scheduled tasks) are not monitored for timeouts since they are not expected to check in continuously.

When a persistent instance times out, the platform:

  • Sends an email notification to all active Owner, Administrator, and Developer members on the account.
  • Fires an agent.timeout webhook event to any webhooks on the account subscribed to that event type.

When the instance recovers and begins checking in again, the platform sends a corresponding resolve notification:

  • An email is sent to the same set of members confirming the instance is back online.
  • An agent.timeout.resolve webhook event is fired.

Each instance is evaluated independently, so an agent with multiple instances may have some instances alerting while others remain healthy.