Consul

​

Supported telemetry types

​

Prerequisites

• Make each Consul agent HTTP API reachable from the Collector tier that scrapes it (node-local agents on the node Collector; static targets on the cluster Collector).
• When Consul access control lists are enabled, provide a token with read access to the agent, catalog, and health endpoints.

​

Configure

1. Choose how the CXDOT Collector discovers Consul agents:
   • For agents that expose the HTTP API on port 8500, add the app: consul label to the pod template. HashiCorp’s official chart sets this label.
   • For agents that need a different URL, ACL token, or TLS settings, use discovery annotations on the Pod or Service. For more information, see autodiscovery.
   The CXDOT Collector creates and enables an unnamed Consul instance that uses discovery by default.
2. Optional: To use static targets instead of discovery, list dialable host:port values or full URLs in endpoints. A nonempty list disables discovery for that instance; the Collector scrapes only those agents. When ACLs are enabled, set acl_token. For example:
   config:
     integrations:
       consul:
         acl_token: "${env:CONSUL_HTTP_TOKEN}"
         endpoints:
           - endpoint: consul.example.com:8500
   
3. Optional: To combine discovery and static targets, configure separate instances. The unnamed instance uses discovery, and the named instance scrapes the static targets:
   config:
     integrations:
       consul: {}
       consul/static:
         acl_token: "${env:CONSUL_HTTP_TOKEN}"
         endpoints:
           - endpoint: consul.example.com:8500
   

​

Validate

1. In the Live Telemetry Analyzer, add the following label filters:
   • Set Label to __name__ and Value to cxdot.integration.target.health.
   • Set Label to cxdot.integration.name and Value to consul.
   Group the results by cxdot.integration.target, and confirm that the metric reports 1 for each target.
2. In Metrics Explorer, run the following query:
   count by ("server.address", "server.port", "consul.mode") ({"consul.peers"})
   
   Confirm that each agent you expect appears. Only agents where consul.mode="leader" also emit catalog metrics for the datacenter.

​

Troubleshooting

• Consul metrics do not appear and Collector logs report HTTP 403 responses: Confirm that the ACL token has read access to the agent, catalog, and health endpoints.
• Catalog metrics are missing for an agent, but consul.peers appears: Only the Raft leader for a datacenter reports catalog metrics; other agents report peer count only.

​

Disable the Consul integration

config:
  integrations:
    consul:
      enabled: false

​

Configuration reference

​

Optional settings

• enabled Type: boolean. Optional. Default: true. Whether to enable this Consul integration instance. If true, the Collector runs the instance. If false, the Collector doesn’t run it.
• endpoints Type: array of object. Optional. Default: []. Static Consul targets. A nonempty list disables automatic discovery for this integration instance, and the Collector collects metrics from only the listed targets. Specify a target as host:port to use HTTP. Specify a full HTTP or HTTPS URL to control the scheme.
• endpoints[].endpoint Type: string. Required. Consul target as either host:port or a full HTTP or HTTPS URL.
• acl_token Type: string. Optional. Consul access control list token sent in the X-Consul-Token header. Provide a token with read access to the agent, catalog, and health endpoints when access control lists are enabled. The Collector masks this sensitive value in diagnostic output, logs, and errors. Discovery annotations can provide a target-specific token.
• collection_interval Type: duration. Optional. Default: 15s. How often the Collector collects metrics from each Consul target.
• timeout Type: duration. Optional. Default: 15s. Maximum time allowed to collect metrics from one Consul target. The value must not exceed collection_interval.
• max_services Type: integer. Optional. Default: 50. Minimum: 1. Cap on how many catalog services one collection interrogates. Each service costs one health-endpoint request, so an unbounded catalog would turn a single collection into thousands of requests against the agent. Services are taken in name order once the catalog exceeds the cap, so the truncated set stays the same between collections rather than shifting with the agent’s response ordering.
• tls Type: object. Optional. Transport layer security (TLS) settings for static HTTPS targets. Certificate verification is enabled unless insecure_skip_verify is true. These settings don’t apply to HTTP targets. Discovery annotations can provide target-specific TLS settings.
• tls.ca_file Type: string. Optional. Path to the CA cert. For a client this verifies the server certificate. For a server this verifies client certificates. If empty uses system root CA. (optional)
• tls.ca_pem Type: string. Optional. In memory PEM encoded cert. (optional)
• tls.cert_file Type: string. Optional. Path to the TLS cert to use for TLS required connections. (optional)
• tls.cert_pem Type: string. Optional. In memory PEM encoded TLS cert to use for TLS required connections. (optional)
• tls.cipher_suites Type: array of string. Optional. CipherSuites is a list of TLS cipher suites that the TLS transport can use. If left blank, a safe default list is used. See https://go.dev/src/crypto/tls/cipher_suites.go for a list of supported cipher suites.
• tls.curve_preferences Type: array of string. Optional. contains the elliptic curves that will be used in an ECDHE handshake, in preference order Defaults to empty list and “crypto/tls” defaults are used, internally.
• tls.include_system_ca_certs_pool Type: boolean. Optional. If true, load system CA certificates pool in addition to the certificates configured in this struct.
• tls.insecure Type: boolean. Optional. In gRPC and HTTP when set to true, this is used to disable the client transport security. See https://godoc.org/google.golang.org/grpc#WithInsecure for gRPC. Please refer to https://godoc.org/crypto/tls#Config for more information. (optional, default false)
• tls.insecure_skip_verify Type: boolean. Optional. InsecureSkipVerify will enable TLS but not verify the certificate.
• tls.key_file Type: string. Optional. Path to the TLS key to use for TLS required connections. (optional)
• tls.key_pem Type: string. Optional. In memory PEM encoded TLS key to use for TLS required connections. (optional)
• tls.max_version Type: string. Optional. MaxVersion sets the maximum TLS version that is acceptable. If not set, refer to crypto/tls for defaults. (optional)
• tls.min_version Type: string. Optional. MinVersion sets the minimum TLS version that is acceptable. If not set, TLS 1.2 will be used. (optional)
• tls.reload_interval Type: duration. Optional. ReloadInterval specifies the duration after which the certificate will be reloaded If not set, it will never be reloaded (optional)
• tls.server_name_override Type: string. Optional. ServerName requested by client for virtual hosting. This sets the ServerName in the TLSConfig. Please refer to https://godoc.org/crypto/tls#Config for more information. (optional)
• tls.tpm Type: object. Optional. Trusted platform module configuration
• tls.tpm.auth Type: string. Optional. Authorization value for the trusted platform module key.
• tls.tpm.enabled Type: boolean. Optional. Whether to use a trusted platform module for the TLS private key. If true, the Collector loads the key from the configured device or socket. If false, the Collector uses the configured key file or in-memory key.
• tls.tpm.owner_auth Type: string. Optional. Owner authorization value for the trusted platform module.
• tls.tpm.path Type: string. Optional. The path to the TPM device or Unix domain socket. For instance /dev/tpm0 or /dev/tpmrm0.