This exporter allows a Prometheus instance to monitor service health, profiles, billing on Control D.
- 💚 Service Health: Watch the health status for DNS, API, and proxy services.
- 💰️ Billing Visibility: Watch the billing status, refund status and the next billing instant.
- ⚙️ Configuration Audit: Track changes in predefined and custom settings with trend visualization.
- 🏢 Organization Support: Fetch members, profiles, routers and users for the organization and sub-orgs.
Note
Control D is a subscription service, so this exporter needs a token from a paid account once the free trial ends. For the plans and their limits, refer to Control D - Personal Plans and Control D - Business Pricing.
This exporter supports container images and OS-specific binaries.
docker pull ghcr.io/umatare5/controld-exporterOr, download the binaries from Releases. (linux|darwin)_(amd64|arm64) and windows_amd64 are supported.
This exporter needs an API key. See Control D Getting Started Guide to get an API key first.
export CTRLD_API_KEY="your-control-d-api-token"docker run -p 10034:10034 -e CTRLD_API_KEY ghcr.io/umatare5/controld-exporter:v1.3.1curl http://localhost:10034/metricsTip
See Metrics for the complete metrics, and Prometheus Configuration for scrape jobs and alerting rules.
This exporter uses command-line flags for all configuration.
The exporter supports the following command-line flags:
NAME:
controld-exporter - A Prometheus exporter for metrics from the Control D
USAGE:
controld-exporter [options...]
VERSION:
1.3.1
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.
--log.level string Set the logging level. One of: [debug, info, warn, error] (default: "info")
--help, -h show help
--version, -v print the version
The exporter exposes these endpoints. See Endpoints for what each status code means.
| Path | Description |
|---|---|
/ |
Landing page, confirming the exporter is up |
/metrics |
Metrics endpoint, set by --web.telemetry-path |
This exporter exposes metrics for the Control D API state.
The following table lists the metrics this exporter publishes. See Appendix below the table for more details.
| Metric | Type | Description |
|---|---|---|
controld_billing_status |
Gauge | Transaction status of one payment |
controld_billing_refunded |
Gauge | Refund status of one payment |
controld_billing_subscription_amount_total |
Gauge | Amount of one payment, per currency |
controld_billing_subscription_nextbill_timestamp |
Gauge | Next billing instant, in Unix seconds |
controld_endpoint_clients_total |
Gauge | Clients counted against one device |
controld_network_health_code |
Gauge | Service status of one point of presence |
controld_profile_preset_filters_total |
Gauge | Preset filters on one profile |
controld_profile_content_filters_total |
Gauge | Content filters on one profile |
controld_profile_ip_filters_total |
Gauge | IP filters on one profile |
controld_profile_rules_total |
Gauge | Rules on one profile |
controld_profile_services_total |
Gauge | Service filters on one profile |
controld_profile_groups_total |
Gauge | Group filters on one profile |
controld_profile_enabled_option_total |
Gauge | Enabled options on one profile |
controld_service_categories_total |
Gauge | Services in one category |
controld_organization_members_total |
Gauge | Members of the organization (*1) |
controld_organization_profiles_total |
Gauge | Profiles of the organization (*1) |
controld_organization_users_total |
Gauge | Users of the organization (*1) |
controld_organization_routers_total |
Gauge | Routers of the organization (*1) |
controld_organization_sub_orgs_total |
Gauge | Sub-organizations beneath it (*1) |
controld_sub_organization_members_total |
Gauge | Members of one sub-organization (*1) |
controld_sub_organization_profiles_total |
Gauge | Profiles of one sub-organization (*1) |
controld_sub_organization_users_total |
Gauge | Users of one sub-organization (*1) |
controld_sub_organization_routers_total |
Gauge | Routers of one sub-organization (*1) |
*1 The controld_organization_* and controld_sub_organization_* need --controld.business-mode.
Appendix - Collector Metrics Details
the four controld_billing_* series: they read the account's own payment history, which the organization endpoints do not scope. Business mode therefore publishes them under the payment's id alone, with no orgId to separate them by.
controld_endpoint_clients_total: it counts the clients Control D attributes to one device, keyed by the device's name. A device renamed in the dashboard ends one series and opens another with the count carried over.
controld_network_health_code: the value is the api, dns and pxy integer each node publishes, passed through without interpretation. A code this exporter has never seen reaches Prometheus as readily as a familiar one.
the seven controld_profile_* series: they count what each profile has configured rather than what it matched, so they move when an operator edits a profile and stay flat under any amount of traffic.
the nine controld_organization_* and controld_sub_organization_* series: they need --controld.business-mode and an API key belonging to an organization. Neither is published in personal mode, so a personal-mode dashboard shows no data rather than zeros.
| Label | Description |
|---|---|
id |
The payment's or subscription's Control D primary key |
currency |
The ISO code the amount beside it is denominated in |
name |
The object's own name, or the category's key on service |
orgId |
The account scope the series was read under |
city_name/country_name |
Where Control D places the point of presence |
iata_code |
The airport code Control D identifies that node by |
service_name |
api, dns or proxy, one series each per node |
name: The field is fixed per family rather than chosen per series. The device, profile and organization families carry the name an operator gave the object, so renaming one in the Control D dashboard ends the old series and opens a new one. controld_service_categories_total carries the category's primary key instead, although the endpoint supplies a name beside it.
orgId: Personal mode fills it with 000000000, a value no Control D organization holds, so a dashboard written against it survives being pointed at a business account. Business mode fills it with the organization's own primary key on the series read for the account, and with a sub-organization's key on the series read for that sub-organization. It never carries the API key, which travels in the Authorization header alone.
The exporter publishes no series about itself, so a failed scrape shows as missing series.
There are several operational examples below.
The two patterns below cover the common use cases.
Personal Pattern: By default, the exporter reads the account the API key belongs to.
CTRLD_API_KEY="your-control-d-api-token" ./controld-exporterBusiness Pattern: Set the --controld.business-mode flag when running the exporter.
CTRLD_API_KEY="your-control-d-api-token" ./controld-exporter --controld.business-modeSee the following Prometheus configuration examples:
- Example Job: Add from
examples/prometheus.ymlto your Prometheus. - Example Alerting Rules: Add from
examples/prometheus_alert_rules.ymlto your Prometheus.
Import examples/control-d-exporter-dashboard.json and visualize the metrics.
The following pages detail additional information.
- Architecture – the scrape path, the absence rules and others.
See CONTRIBUTING.md for development setup, test conventions and others.
MIT. The binary statically links Apache-2.0, MIT and BSD 3-Clause dependencies. Their notices are reproduced in NOTICE and shipped alongside LICENSE in every release archive and container image.