--- title: Telegraf Documentation description: Telegraf plugin for collecting metrics from Stackdriver Google Cloud Monitoring url: https://docs.influxdata.com/telegraf/v1/input-plugins/stackdriver/ estimated_tokens: 3622 product: Telegraf version: v1 --- - Telegraf v1.10.0+ # Stackdriver Google Cloud Monitoring Input Plugin This plugin collects metrics from [Google Cloud Monitoring](https://cloud.google.com/monitoring) (formerly Stackdriver) using the [Cloud Monitoring API v3](https://cloud.google.com/monitoring/api/v3/). This plugin accesses APIs which are [chargeable](https://cloud.google.com/stackdriver/pricing#stackdriver_monitoring_services), cost might incur. **Introduced in:** Telegraf v1.10.0 **Tags:** cloud **OS support:** all ## Global configuration options Plugins support additional global and plugin configuration settings for tasks such as modifying metrics, tags, and fields, creating aliases, and configuring plugin ordering. See [CONFIGURATION.md](/telegraf/v1/configuration/#plugins) for more details. ## Configuration ```toml # Gather timeseries from Google Cloud Platform v3 monitoring API [[inputs.stackdriver]] ## GCP Project project = "erudite-bloom-151019" ## Include timeseries that start with the given metric type. metric_type_prefix_include = [ "compute.googleapis.com/", ] ## Exclude timeseries that start with the given metric type. # metric_type_prefix_exclude = [] ## Most metrics are updated no more than once per minute; it is recommended ## to override the agent level interval with a value of 1m or greater. interval = "1m" ## Maximum number of API calls to make per second. The quota for accounts ## varies, it can be viewed on the API dashboard: ## https://cloud.google.com/monitoring/quotas#quotas_and_limits # rate_limit = 14 ## The delay and window options control the number of points selected on ## each gather. When set, metrics are gathered between: ## start: now() - delay - window ## end: now() - delay # ## Collection delay; if set too low metrics may not yet be available. # delay = "5m" # ## If unset, the window will start at 1m and be updated dynamically to span ## the time between calls (approximately the length of the plugin interval). # window = "1m" ## TTL for cached list of metric types. This is the maximum amount of time ## it may take to discover new metrics. # cache_ttl = "1h" ## If true, raw bucket counts are collected for distribution value types. ## For a more lightweight collection, you may wish to disable and use ## distribution_aggregation_aligners instead. # gather_raw_distribution_buckets = true ## Aggregate functions to be used for metrics whose value type is ## distribution. These aggregate values are recorded in in addition to raw ## bucket counts; if they are enabled. ## ## For a list of aligner strings see: ## https://cloud.google.com/monitoring/api/ref_v3/rpc/google.monitoring.v3#aligner # distribution_aggregation_aligners = [ # "ALIGN_PERCENTILE_99", # "ALIGN_PERCENTILE_95", # "ALIGN_PERCENTILE_50", # ] ## Filters can be added to reduce the number of time series matched. All ## functions are supported: starts_with, ends_with, has_substring, and ## one_of. Only the '=' operator is supported. ## ## The logical operators when combining filters are defined statically using ## the following values: ## filter ::= {AND AND AND } ## resource_labels ::= {OR } ## metric_labels ::= {OR } ## user_labels ::= {OR } ## system_labels ::= {OR } ## ## For more details, see https://cloud.google.com/monitoring/api/v3/filters # ## Resource labels refine the time series selection with the following expression: ## resource.labels. = # [[inputs.stackdriver.filter.resource_labels]] # key = "instance_name" # value = 'starts_with("localhost")' # ## Metric labels refine the time series selection with the following expression: ## metric.labels. = # [[inputs.stackdriver.filter.metric_labels]] # key = "device_name" # value = 'one_of("sda", "sdb")' # ## User labels refine the time series selection with the following expression: ## metadata.user_labels."" = # [[inputs.stackdriver.filter.user_labels]] # key = "environment" # value = 'one_of("prod", "staging")' # ## System labels refine the time series selection with the following expression: ## metadata.system_labels."" = # [[inputs.stackdriver.filter.system_labels]] # key = "machine_type" # value = 'starts_with("e2-")' ``` ### Authentication It is recommended to use a service account to authenticate with the Stackdriver Monitoring API. [Getting Started with Authentication](https://cloud.google.com/docs/authentication/getting-started). ## Troubleshooting When Telegraf is ran with `--debug`, detailed information about the performed queries will be logged. ## Metrics Metrics are created using one of there patterns depending on if the value type is a scalar value, raw distribution buckets, or aligned bucket values. In all cases, the Stackdriver metric type is split on the last component into the measurement and field: ```sh compute.googleapis.com/instance/disk/read_bytes_count └────────── measurement ─────────┘ └── field ───┘ ``` ### Scalar Values - measurement - tags: - resource\_labels - metric\_labels - fields: - field ### Distributions Distributions are represented by a set of fields along with the bucket values tagged with the bucket boundary. Buckets are cumulative: each bucket represents the total number of items less than the `lt` tag. - measurement - tags: - resource\_labels - metric\_labels - fields: - field\_count - field\_mean - field\_sum\_of\_squared\_deviation - field\_range\_min - field\_range\_max - measurement - tags: - resource\_labels - metric\_labels - lt (less than) - fields: - field\_bucket ### Aligned Aggregations - measurement - tags: - resource\_labels - metric\_labels - fields: - field\_alignment\_function ## Example Output The output depends on the defined filters and metric types. #### Related - [Configure plugins](/telegraf/v1/configure_plugins/) - [Stackdriver Google Cloud Monitoring Plugin Source](https://github.com/influxdata/telegraf/tree/v1.38.4/plugins/inputs/stackdriver/README.md)