ec2tagger

README

EC2 Tagger Processor

The EC2 Tagger Processor can be used to scrape metadata from IMDS in EC2 instances or ECS EC2 or EKS EC2 and add the metadata to the data point attributes

Status
Stability	[stable]
Supported pipeline types	metrics
Distributions	[amazon-cloudwatch-agent]

Amazon Authentication

The EC2 Tagger Processor uses a credential chain for Authentication with the EC2 API endpoint. In the following order the plugin will attempt to authenticate.

1. STS Credentials if Role ARN is specified
2. Explicit credentials from 'access_key' and 'secret_key'
3. Shared profile from 'profile' (https://stackoverflow.com/a/66121705)

The next will be the default credential chain from AWS SDK Go

1. Environment Variables
2. Share Credentials Files with default profile
3. ECS Task IAM Role
4. EC2 Instance Profile

The IAM User or Role making the calls must have permissions to call the EC2 DescribeTags API.

Processor Configuration:

The following receiver configuration parameters are supported.

Name	Description	Supported Value	Default
refresh_interval_seconds	is the frequency for the plugin to refresh the EC2 Instance Tags and ebs Volumes associated with this Instance.	"0s"	"0s"
ec2_metadata_tags	is the option to specify which tags to be scraped from IMDS and add to datapoint attributes	["InstanceId", "ImageId", "InstanceType"]	[]
ec2_instance_tag_keys	is the option to specific which EC2 Instance tags to be scraped associated with this instance.	["aws:autoscaling:groupName", "Name"]	[]
disk_device_tag_key	is the option to Specify which tags to use to get the specified disk device name from input metric	[]	[]

Documentation

Index

• Constants
• Variables
• func NewFactory() processor.Factory
• type Config
  • func (cfg *Config) Validate() error
• type Tagger
  • func (t *Tagger) Shutdown(context.Context) error
  • func (t *Tagger) Start(ctx context.Context, _ component.Host) error

Constants

const (
	AttributeVolumeId            = "VolumeId"
	ValueAppendDimensionVolumeId = "${aws:VolumeId}"
)

const (
	Ec2InstanceTagKeyASG = "aws:autoscaling:groupName"
)

Variables

var (
	ThrottleBackOffArray = []time.Duration{0, 1 * time.Minute, 3 * time.Minute}                                                                      // backoff retry for ec2 describe instances API call. Assuming the throttle limit is 20 per second. 10 mins allow 12000 API calls.
	BackoffSleepArray    = []time.Duration{0, 1 * time.Minute, 1 * time.Minute, 3 * time.Minute, 3 * time.Minute, 3 * time.Minute, 10 * time.Minute} // backoff retry for ec2 describe instances API call. Assuming the throttle limit is 20 per second. 10 mins allow 12000 API calls.
)

var SupportedAppendDimensions = map[string]string{
	"AutoScalingGroupName": "${aws:AutoScalingGroupName}",
	"ImageId":              "${aws:ImageId}",
	"InstanceId":           "${aws:InstanceId}",
	"InstanceType":         "${aws:InstanceType}",
}

var (
	TypeStr, _ = component.NewType("ec2tagger")
)

Functions

func NewFactory

func NewFactory() processor.Factory

Types

type Config

type Config struct {
	RefreshIntervalSeconds time.Duration `mapstructure:"refresh_interval_seconds"`
	EC2MetadataTags        []string      `mapstructure:"ec2_metadata_tags"`
	EC2InstanceTagKeys     []string      `mapstructure:"ec2_instance_tag_keys"`
	EBSDeviceKeys          []string      `mapstructure:"ebs_device_keys,omitempty"`

	//The tag key in the metrics for disk device
	DiskDeviceTagKey string `mapstructure:"disk_device_tag_key,omitempty"`

	// unlike other AWS plugins, this one determines the region from ec2 metadata not user configuration
	AccessKey   string `mapstructure:"access_key,omitempty"`
	SecretKey   string `mapstructure:"secret_key,omitempty"`
	RoleARN     string `mapstructure:"role_arn,omitempty"`
	Profile     string `mapstructure:"profile,omitempty"`
	Filename    string `mapstructure:"shared_credential_file,omitempty"`
	Token       string `mapstructure:"token,omitempty"`
	IMDSRetries int    `mapstructure:"imds_retries,omitempty"`
}

func (*Config) Validate

func (cfg *Config) Validate() error

Validate does not check for unsupported dimension key-value pairs, because those get silently dropped and ignored during translation.

type Tagger

type Tagger struct {
	*Config

	sync.RWMutex //to protect ec2TagCache
	// contains filtered or unexported fields
}

func (*Tagger) Shutdown

func (t *Tagger) Shutdown(context.Context) error

func (*Tagger) Start

func (t *Tagger) Start(ctx context.Context, _ component.Host) error

Start acts as input validation and serves the purpose of updating ec2 tags and ebs volumes if necessary. It will be called when OTel is enabling each processor