Monitoring Consul (HashiCorp)

The Consul (HashiCorp) sensor is automatically deployed and installed after you install the Instana agent.

Supported versions

Currently supported versions are from 0.7.5 to 1.9.x


The Instana agent automatically detects the running Consul agent and will parse -client and -http-port commandline arguments in case you are overriding the default settings. The agent can figure out most of the configuration values it needs to connect to Consul.

The Instana agent accesses Consul via its Agent HTTP API. In a vanilla Consul installation, this interface is accessible without credentials. In this case, the Instana Consul sensor does not need any special configuration.

If, on the other hand, you have set the Consul HTTP access policy acl_default_policy to deny, you need to provide a token to the Instana agent. This can be done by configuring them in the agent's configuration file <agent_install_dir>/etc/instana/configuration.yaml.

As a first step you need to configure the following ACL settings for Consul, as described in the ACL Guide, and create an access token with read permissions:

  • For versions prior to Consul 1.6.1:
    agent "" {
      policy = "read"
    health "" {
      policy = "read"
  • For version Consul 1.6.1 and newer:
    agent_prefix "" {
      policy = "read"
    health "" {
      policy = "read"

In the next step you need to configure the token in the Instana Agent <agent_install_dir>/etc/instana/configuration.yaml. Here are all possible configuration values for Consul monitoring:

  enabled: true
  client: ''   
  httpPort: 8500
  token: ''
  • enabled: enable/disable Consul sensor, enabled by default
  • client: agent hostname, by default sensor will parse -client parameter or use localhost
  • httpPort: agent http port, by default sensor will parse -http-port parameter or use 8500
  • token: 'token' to access consul endpoint when acl_default_policy is set to deny

The configuration value for httpPort needs to be an integer value, otherwise it will be ignored, that is, if it can't be parsed into a number, the standard port will be used.

Metrics collection

To view the metrics, select Infrastructure in the sidebar of the Instana User interface, click a specific monitored host, and then you can see a host dashboard with all the collected metrics and monitored processes.

Configuration data

  • Version
  • Consul agent configuration
    • Node name
    • Domain
    • State
    • Advertise address
    • Datacenter
    • Leader
    • Peers

Performance metrics

  • Number of freed heap objects
  • Number of objects allocated on the heap
  • Number of the virtual address space reserved by the Go runtime
  • Number of heap objects allocated
  • Number of total garbage collection runs
  • Number of loaded go routines
  • Number of bytes allocated by the Consul process
  • Number of total garbage collection pauses in ns
  • Session time-to-live active
  • Autopilot: healthy
  • Autopilot: failure tolerance
  • Raft: applied index
  • Raft: commit index
  • Raft: finite state machine pending
  • Raft: last contact in ms
  • Raft: last log index
  • Raft: last log term
  • Raft: last snapshot index
  • Raft: last snapshot term
  • Raft: number of peers
  • Raft: term, the number of new leader elections that have happened

Health signatures

For each sensor, there is a curated knowledgebase of health signatures that are evaluated continuously against the incoming metrics and are used to raise issues or incidents depending on user impact.

Built-in events trigger issues or incidents based on failing health signatures on entities, and custom events trigger issues or incidents based on the thresholds of an individual metric of any given entity.

For information about built-in events for the Consul sensor, see the Built-in events reference.