controld-exporter

A third-party Prometheus Exporter for Control D.

Overview

This exporter allows a prometheus instance to scrape metrics from Control D, a cloud-based DNS service.

• 💚 Enables health checks for DNS, API, and proxy services
• ⚙️ Tracks changes in predefined and custom settings with trend visualization
• 📈 Provides short-term monitoring and long-term observability of costs, endpoints, and other statistics

Important

To access the Control D API, you must register with Control D and generate an access token.

• Please refer to the Control D - The official Getting Started Guide.

Quick Start

docker run -p 10034:10034 -e CTRLD_API_KEY ghcr.io/umatare5/controld-exporter

• -p: Maps container port 10034/tcp to host port 10034/tcp.
• -e: Passes the environment variable CTRLD_API_KEY into the container.

Tip

If you prefer using binaries, download them from the release page.

• Supported Platforms: linux_amd64, linux_arm64, darwin_amd64, darwin_arm64 and windows_amd64

Syntax

NAME:
   controld-exporter - A Prometheus exporter for metrics from the Control D

USAGE:
   controld-exporter [options...]

VERSION:
   v1.0.0

GLOBAL OPTIONS:
   --web.listen-address string             Address to bind the HTTP server to. (default: "0.0.0.0")
   --web.listen-port int                   Port number to bind the HTTP server to. (default: 10034)
   --web.telemetry-path string, -p string  Path for the metrics endpoint. (default: "/metrics")
   --controld.api-key string, -k string    API key for authenticating with the Control D API. [$CTRLD_API_KEY]
   --controld.business-mode                Enable the metrics collection available in the business subscription. (default: false)
   --log.level string                      Set the logging level. One of: [debug, info, warn, error] (default: "info")
   --help, -h                              show help
   --version, -v                           print the version

Tip

By default, the controld-exporter starts in personal mode. In this mode, the label orgId for each metric will be filled with 000000000. If you have the business subscription, please enable --controld.business-mode. This allows the exporter to collect organization-related metrics.

Configuration

This exporter supports following environment variables:

Environment Variable	Description
CTRLD_API_KEY	The API Key to be used for requests.

Metrics

This exporter returns following metrics:

Metric Name	Description	Type	Example
controld_billing_status	Billing status of the account.	Gauge	0 or 1
controld_billing_refunded_status	Refunded status of the account.	Gauge	0 or 1
controld_billing_subscription_amount_total	Amount of billing subscription in the specified currency.	Gauge	2
controld_billing_subscription_nextbill_timestamp	Unix time of the next billing date for a subscription.	Gauge	1744464600
controld_endpoint_clients_total	Number of clients for each endpoint.	Gauge	1
controld_network_health_code	Health status of the network by city and service type.	Gauge	-1
controld_profile_content_filters_total	Number of content filters in a profile.	Gauge	1
controld_profile_enabled_option_total	Number of enabled options in a profile.	Gauge	1
controld_profile_groups_total	Number of group filters in a profile.	Gauge	1
controld_profile_ip_filters_total	Number of IP filters in a profile.	Gauge	1
controld_profile_preset_filters_total	Number of preset filters in a profile.	Gauge	1
controld_profile_rules_total	Number of rule filters in a profile.	Gauge	1
controld_profile_services_total	Number of service filters in a profile.	Gauge	1
controld_service_categories_total	Number of service categories for each endpoint.	Gauge	1
controld_stats_last_queries_count	[Experimental] Count of DNS queries by type (redirect, success, blocked).	Counter	1
controld_organization_members_total	[Business] Number of members in an organization.	Gauge	1
controld_organization_profiles_total	[Business] Number of profiles in an organization.	Gauge	1
controld_organization_routers_total	[Business] Number of routers in an organization.	Gauge	1
controld_organization_sub_orgs_total	[Business] Number of sub-organizations in an organization.	Gauge	1
controld_organization_users_total	[Business] Number of users in an organization.	Gauge	1
controld_sub_organization_members_total	[Business] Number of members in a sub-organization.	Gauge	1
controld_sub_organization_profiles_total	[Business] Number of profiles in a sub-organization.	Gauge	1
controld_sub_organization_routers_total	[Business] Number of routers in a sub-organization.	Gauge	1
controld_sub_organization_users_total	[Business] Number of users in a sub-organization.	Gauge	1

Usage

Exporter

Visit http://localhost:10034/ to verify the exporter is running.

Using Docker

$ CTRLD_API_KEY="foobarbaz"
$ docker run -p 10034:10034 -e CTRLD_API_KEY ghcr.io/umatare5/controld-exporter
time="2025-04-13T18:50:54Z" level=info msg="Starting the personal mode exporter on port 10034."

Using Binary

$ CTRLD_API_KEY="foobarbaz"
$ ./controld-exporter
time="2025-04-13T18:50:54Z" level=info msg="Starting the personal mode exporter on port 10034."

Prometheus Configuration

This section describes how to configure Prometheus to scrape metrics from the controld-exporter.

1. Add the job config to your Prometheus YAML file using examples/prometheus.yml as a reference.
2. Set up alerting rules using examples/prometheus.alert_rules.yml as a reference.

Grafana Dashboard

A sample dashboard schema is available at examples/control-d-exporter-dashboard.json.

Development

Build

The repository includes a ready to use Dockerfile. To build a new Docker image:

make image

This creates an image named ghcr.io/$USER/controld-exporter and exposes 10034/tcp.

Release

To release a new version, follow these steps:

1. Update the version in the VERSION file.
2. Submit a pull request with the updated VERSION file.

Once the pull request is merged, the GitHub Workflow automatically creates and pushes a new tag, after which I manually publish a release using the [GitHub Actions release workflow]GitHub Actions: release workflow.

Acknowledgement

I launched this project with the help of GitHub Copilot Coding Assistant, and I am grateful to the global developer community for their contributions to open source projects and public repositories.

Licence

MIT

Author

umatare5