aliyuncms

README

Alibaba (Aliyun) CloudMonitor Service Statistics Input Plugin

Here and after we use Aliyun instead Alibaba as it is default naming across web console and docs.

This plugin will pull metric statistics from Aliyun CMS.

Aliyun Authentication

This plugin uses an AccessKey credential for Authentication with the Aliyun OpenAPI endpoint. In the following order the plugin will attempt to authenticate.

1. Ram RoleARN credential if access_key_id, access_key_secret, role_arn, role_session_name is specified
2. AccessKey STS token credential if access_key_id, access_key_secret, access_key_sts_token is specified
3. AccessKey credential if access_key_id, access_key_secret is specified
4. Ecs Ram Role Credential if role_name is specified
5. RSA keypair credential if private_key, public_key_id is specified
6. Environment variables credential
7. Instance metadata credential

Global configuration options

In addition to the plugin-specific configuration settings, plugins support additional global and plugin configuration settings. These settings are used to modify metrics, tags, and field or create aliases and configure ordering, etc. See the CONFIGURATION.md for more details.

Configuration

# Pull Metric Statistics from Aliyun CMS
[[inputs.aliyuncms]]
  ## Aliyun Credentials
  ## Credentials are loaded in the following order
  ## 1) Ram RoleArn credential
  ## 2) AccessKey STS token credential
  ## 3) AccessKey credential
  ## 4) Ecs Ram Role credential
  ## 5) RSA keypair credential
  ## 6) Environment variables credential
  ## 7) Instance metadata credential

  # access_key_id = ""
  # access_key_secret = ""
  # access_key_sts_token = ""
  # role_arn = ""
  # role_session_name = ""
  # private_key = ""
  # public_key_id = ""
  # role_name = ""

  ## Specify ali cloud regions to be queried for metric and object discovery
  ## If not set, all supported regions (see below) would be covered, it can
  ## provide a significant load on API, so the recommendation here is to
  ## limit the list as much as possible.
  ## Allowed values: https://www.alibabacloud.com/help/zh/doc-detail/40654.htm
  ## Default supported regions are:
  ##   cn-qingdao,cn-beijing,cn-zhangjiakou,cn-huhehaote,cn-hangzhou,
  ##   cn-shanghai, cn-shenzhen, cn-heyuan,cn-chengdu,cn-hongkong,
  ##   ap-southeast-1,ap-southeast-2,ap-southeast-3,ap-southeast-5,
  ##   ap-south-1,ap-northeast-1, us-west-1,us-east-1,eu-central-1,
  ##   eu-west-1,me-east-1
  ##
  ## From discovery perspective it set the scope for object discovery,
  ## the discovered info can be used to enrich the metrics with objects
  ##  attributes/tags. Discovery is not supported for all projects.
  ## Currently, discovery supported for the following projects:
  ## - acs_ecs_dashboard
  ## - acs_rds_dashboard
  ## - acs_slb_dashboard
  ## - acs_vpc_eip
  regions = ["cn-hongkong"]

  ## Requested AliyunCMS aggregation Period (required)
  ## The period must be multiples of 60s and the minimum for AliyunCMS metrics
  ## is 1 minute (60s). However not all metrics are made available to the
  ## one minute period. Some are collected at 3 minute, 5 minute, or larger
  ## intervals.
  ## See: https://help.aliyun.com/document_detail/51936.html?spm=a2c4g.11186623.2.18.2bc1750eeOw1Pv
  ## Note that if a period is configured that is smaller than the minimum for
  ## a particular metric, that metric will not be returned by Aliyun's
  ## OpenAPI and will not be collected by Telegraf.
  period = "5m"

  ## Collection Delay (required)
  ## The delay must account for metrics availability via AliyunCMS API.
  delay = "1m"

  ## Recommended: use metric 'interval' that is a multiple of 'period'
  ## to avoid gaps or overlap in pulled data
  interval = "5m"

  ## Metric Statistic Project (required)
  project = "acs_slb_dashboard"

  ## Maximum requests per second, default value is 200
  ratelimit = 200

  ## How often the discovery API call executed (default 1m)
  #discovery_interval = "1m"

  ## Metrics to Pull (Required)
  [[inputs.aliyuncms.metrics]]
  ## Metrics names to be requested,
  ## Description can be found here (per project):
  ## https://help.aliyun.com/document_detail/28619.html?spm=a2c4g.11186623.6.690.1938ad41wg8QSq
  names = ["InstanceActiveConnection", "InstanceNewConnection"]

  ## Dimension filters for Metric (optional).
  ## This allows to get additional metric dimension. If dimension is not
  ## specified it can be returned or the data can be aggregated - it depends
  ## on particular metric, you can find details here:
  ## https://help.aliyun.com/document_detail/28619.html?spm=a2c4g.11186623.6.690.1938ad41wg8QSq
  ##
  ## Note, that by default dimension filter includes the list of discovered
  ## objects in scope (if discovery is enabled).
  # Values specified here would be added into the list of discovered objects.
  ## You can specify either single dimension:
  #dimensions = '{"instanceId": "p-example"}'

  ## Or you can specify several dimensions at once:
  #dimensions = '[{"instanceId": "p-example"},{"instanceId": "q-example"}]'

  ## Enrichment tags, can be added from discovery (if supported)
  ## Notation is <measurement_tag_name>:<JMES query path (https://jmespath.org/tutorial.html)>
  ## To figure out which fields are available, consult the Describe<ObjectType>
  ## API per project.
  ## For example, for SLB: https://api.aliyun.com/#/?product=Slb&version=2014-05-15&api=DescribeLoadBalancers&params={}&tab=MOCK&lang=GO
  #tag_query_path = [
  #    "address:Address",
  #    "name:LoadBalancerName",
  #    "cluster_owner:Tags.Tag[?TagKey=='cs.cluster.name'].TagValue | [0]"
  #    ]
  ## The following tags added by default:
  ##   regionId (if discovery enabled), userId, instanceId.

  ## Allow metrics without discovery data, if discovery is enabled.
  ## If set to true, then metric without discovery data would be emitted, otherwise dropped.
  ## This cane be of help, in case debugging dimension filters, or partial coverage of
  ## discovery scope vs monitoring scope 
  # allow_dps_without_discovery = false

Requirements and Terminology

Plugin Configuration utilizes preset metric items references

• discovery_region must be a valid Aliyun Region value
• period must be a valid duration value
• project must be a preset project value
• names must be preset metric names
• dimensions must be preset dimension values

Metrics

Each Aliyun CMS Project monitored records a measurement with fields for each available Metric Statistic Project and Metrics are represented in snake case

• aliyuncms_{project}
  • {metric}_average (metric Average value)
  • {metric}_minimum (metric Minimum value)
  • {metric}_maximum (metric Maximum value)
  • {metric}_value (metric Value value)

Example Output

$ ./telegraf --config telegraf.conf --input-filter aliyuncms --test
> aliyuncms_acs_slb_dashboard,instanceId=p-example,regionId=cn-hangzhou,userId=1234567890 latency_average=0.004810798017284538,latency_maximum=0.1100282669067383,latency_minimum=0.0006084442138671875

Documentation

Index

• type AliyunCMS
  • func (s *AliyunCMS) Gather(acc telegraf.Accumulator) error
  • func (s *AliyunCMS) Init() error
  • func (*AliyunCMS) SampleConfig() string
  • func (s *AliyunCMS) Start(telegraf.Accumulator) error
  • func (s *AliyunCMS) Stop()
• type Dimension
• type Metric

Types

type AliyunCMS

type AliyunCMS struct {
	AccessKeyID       string `toml:"access_key_id"`
	AccessKeySecret   string `toml:"access_key_secret"`
	AccessKeyStsToken string `toml:"access_key_sts_token"`
	RoleArn           string `toml:"role_arn"`
	RoleSessionName   string `toml:"role_session_name"`
	PrivateKey        string `toml:"private_key"`
	PublicKeyID       string `toml:"public_key_id"`
	RoleName          string `toml:"role_name"`

	Regions           []string        `toml:"regions"`
	DiscoveryInterval config.Duration `toml:"discovery_interval"`
	Period            config.Duration `toml:"period"`
	Delay             config.Duration `toml:"delay"`
	Project           string          `toml:"project"`
	Metrics           []*Metric       `toml:"metrics"`
	RateLimit         int             `toml:"ratelimit"`

	Log telegraf.Logger `toml:"-"`
	// contains filtered or unexported fields
}

AliyunCMS is aliyun cms config info.

func (*AliyunCMS) Gather

func (s *AliyunCMS) Gather(acc telegraf.Accumulator) error

Gather implements telegraf.Inputs interface

func (*AliyunCMS) Init

func (s *AliyunCMS) Init() error

Init perform checks of plugin inputs and initialize internals

func (*AliyunCMS) SampleConfig

func (*AliyunCMS) SampleConfig() string

func (*AliyunCMS) Start

func (s *AliyunCMS) Start(telegraf.Accumulator) error

Start plugin discovery loop, metrics are gathered through Gather

func (*AliyunCMS) Stop

func (s *AliyunCMS) Stop()

Stop - stops the plugin discovery loop

type Dimension

type Dimension struct {
	Value string `toml:"value"`
}

Dimension describe how to get metrics

type Metric

type Metric struct {
	ObjectsFilter                 string   `toml:"objects_filter"`
	MetricNames                   []string `toml:"names"`
	Dimensions                    string   `toml:"dimensions"` //String representation of JSON dimensions
	TagsQueryPath                 []string `toml:"tag_query_path"`
	AllowDataPointWODiscoveryData bool     `toml:"allow_dps_without_discovery"` //Allow data points without discovery data (if no discovery data found)
	// contains filtered or unexported fields
}

Metric describes what metrics to get