open-vault/website/pages/docs/configuration/telemetry.mdx

---
layout: docs
page_title: Telemetry - Configuration
sidebar_title: <code>telemetry</code>
description: |-
  The telemetry stanza specifies various configurations for Vault to publish
  metrics to upstream systems.
---

# `telemetry` Stanza

The `telemetry` stanza specifies various configurations for Vault to publish
metrics to upstream systems. Available Vault metrics can be found in the
[Telemetry internals documentation](/docs/internals/telemetry).

```hcl
telemetry {
  statsite_address = "statsite.company.local:8125"
}
```

## `telemetry` Parameters

Due to the number of configurable parameters to the `telemetry` stanza,
parameters on this page are grouped by the telemetry provider.

### Common

The following options are available on all telemetry configurations.

- `disable_hostname` `(bool: false)` - Specifies if gauge values should be
  prefixed with the local hostname.
- `enable_hostname_label` `(bool: false)` - Specifies if all metric values should
  contain the `host` label with the local hostname. It is recommended to enable
  `disable_hostname` if this option is used.

### `statsite`

These `telemetry` parameters apply to
[statsite](https://github.com/armon/statsite).

- `statsite_address` `(string: "")` - Specifies the address of a statsite server
  to forward metrics data to.

```hcl
telemetry {
  statsite_address = "statsite.company.local:8125"
}
```

### `statsd`

These `telemetry` parameters apply to
[statsd](https://github.com/etsy/statsd).

- `statsd_address` `(string: "")` - Specifies the address of a statsd server to
  forward metrics to.

```hcl
telemetry {
  statsd_address = "statsd.company.local:8125"
}
```

### `circonus`

These `telemetry` parameters apply to [Circonus](http://circonus.com/).

- `circonus_api_token` `(string: "")` - Specifies a valid Circonus API Token
  used to create/manage check. If provided, metric management is enabled.

- `circonus_api_app` `(string: "nomad")` - Specifies a valid app name associated
  with the API token.

- `circonus_api_url` `(string: "https://api.circonus.com/v2")` - Specifies the
  base URL to use for contacting the Circonus API.

- `circonus_submission_interval` `(string: "10s")` - Specifies the interval at
  which metrics are submitted to Circonus.

- `circonus_submission_url` `(string: "")` - Specifies the
  `check.config.submission_url` field, of a Check API object, from a previously
  created HTTPTRAP check.

- `circonus_check_id` `(string: "")` - Specifies the Check ID (**not check
  bundle**) from a previously created HTTPTRAP check. The numeric portion of the
  `check._cid` field in the Check API object.

- `circonus_check_force_metric_activation` `(bool: false)` - Specifies if force
  activation of metrics which already exist and are not currently active. If
  check management is enabled, the default behavior is to add new metrics as
  they are encountered. If the metric already exists in the check, it will
  not be activated. This setting overrides that behavior.

- `circonus_check_instance_id` `(string: "<hostname>:<application>")` - Serves
  to uniquely identify the metrics coming from this _instance_. It can be used
  to maintain metric continuity with transient or ephemeral instances as they
  move around within an infrastructure. By default, this is set to
  hostname:application name (e.g. "host123:nomad").

- `circonus_check_search_tag` `(string: <service>:<application>)` - Specifies a
  special tag which, when coupled with the instance id, helps to narrow down the
  search results when neither a Submission URL or Check ID is provided. By
  default, this is set to service:app (e.g. "service:nomad").

- `circonus_check_display_name` `(string: "")` - Specifies a name to give a
  check when it is created. This name is displayed in the Circonus UI Checks
  list.

- `circonus_check_tags` `(string: "")` - Comma separated list of additional
  tags to add to a check when it is created.

- `circonus_broker_id` `(string: "")` - Specifies the ID of a specific Circonus
  Broker to use when creating a new check. The numeric portion of `broker._cid`
  field in a Broker API object. If metric management is enabled and neither a
  Submission URL nor Check ID is provided, an attempt will be made to search for
  an existing check using Instance ID and Search Tag. If one is not found, a new
  HTTPTRAP check will be created. By default, this is a random
  Enterprise Broker is selected, or, the default Circonus Public Broker.

- `circonus_broker_select_tag` `(string: "")` - Specifies a special tag which
  will be used to select a Circonus Broker when a Broker ID is not provided. The
  best use of this is to as a hint for which broker should be used based on
  _where_ this particular instance is running (e.g. a specific geo location or
  datacenter, dc:sfo).

### `dogstatsd`

These `telemetry` parameters apply to
[DogStatsD](http://docs.datadoghq.com/guides/dogstatsd/).

- `dogstatsd_addr` `(string: "")` - This provides the address of a DogStatsD
  instance. DogStatsD is a protocol-compatible flavor of statsd, with the added
  ability to decorate metrics with tags and event information. If provided,
  Vault will send various telemetry information to that instance for
  aggregation. This can be used to capture runtime information.

* `dogstatsd_tags` `(string array: [])` - This provides a list of global tags
  that will be added to all telemetry packets sent to DogStatsD. It is a list
  of strings, where each string looks like "my_tag_name:my_tag_value".

### `prometheus`

These `telemetry` parameters apply to
[prometheus](https://prometheus.io).

- `prometheus_retention_time` `(string: "24h")` - Specifies the amount of time that
  Prometheus metrics are retained in memory. 
- `disable_hostname` `(bool: false)` -  It is recommended to also enable the option
  `disable_hostname` to avoid having prefixed metrics with hostname. 

The `/v1/sys/metrics` endpoint is only accessible on active nodes
and automatically disabled on standby nodes. You can enable the `/v1/sys/metrics`
endpoint on standby nodes by [enabling unauthenticated metrics access][telemetry-tcp].

Vault does not use the default Prometheus path, so Prometheus must be configured 
with the path below. 
Note that using `?format=prometheus` in the path won't work as "?" will be 
escaped, so it must be specified as a parameter. 

A Vault token is required with `capabilities = ["read", "list"]` to 
/v1/sys/metrics. The Prometheus `bearer_token` or `bearer_token_file` options 
must be added to the scrape job. 

An example job_name stanza required in the [Prometheus config](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) is provided below. 

```
# prometheus.yml 
scrape_configs:
  - job_name: 'vault'
    metrics_path: "/v1/sys/metrics"
    params:
      format: ['prometheus']
    scheme: https
    tls_config:
      ca_file: your_ca_here.pem
    bearer_token: "your_vault_token_here"
    static_configs:
    - targets: ['your_vault_server_here:8200']
```

  An example telemetry configuration to be added to Vault's configuration file is shown below:

```hcl
telemetry {
  prometheus_retention_time = "30s",
  disable_hostname = true
}
```

### `stackdriver`

These `telemetry` parameters apply to [Stackdriver Monitoring](https://cloud.google.com/monitoring/).

The Stackdriver telemetry provider uses the official Google Cloud Golang SDK. This means
it supports the common ways of
[providing credentials to Google Cloud](https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application).

To use this telemetry provider, the service account must have the following
minimum scope(s):

```text
https://www.googleapis.com/auth/cloud-platform
https://www.googleapis.com/auth/monitoring
https://www.googleapis.com/auth/monitoring.write
```

And the following IAM role(s):

```text
roles/monitoring.metricWriter
```

- `stackdriver_project_id` the Google Cloud ProjectID to send telemetry data to.
- `stackdriver_location` the GCP or AWS region of the monitored resource.
- `stackdriver_namespace` a namespace identifier for the telemetry data.

It is recommended to also enable the option `disable_hostname` to avoid having prefixed
metrics with hostname and enable instead `enable_hostname_label`.

```hcl
telemetry {
  stackdriver_project_id = "my-test-project"
  stackdriver_location = "us-east1-a"
  stackdriver_namespace = "vault-cluster-a"
  disable_hostname = true
  enable_hostname_label = true
}
```

[telemetry-tcp]: /docs/configuration/listener/tcp#telemetry