friendlytagger

package
v0.0.0-...-d5407a0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 21, 2021 License: BSD-2-Clause Imports: 6 Imported by: 0

README

This telegraf plugin can be used to add user-friendly "label" tags to measurements which contain ASNs, ISO-2 country codes or Netacq-Edge region/county identifiers.

Examples:

  • a country_code tag of AU will result in an additional country_label tag with the value "Australia".
  • a region_code tag of 4416 will result in an additional region_label tag with the value "California".
  • a county_code tag of 2735 will result in an additional county_label tag with the value "San Diego".
  • a asn tag of 10000 will result in an additional asn_label tag with the value "NCM, JP".

Installation

Make sure ${GOROOT} is set -- default is usually /usr/local/go

go get github.com/influxdata/telegraf
go get github.com/mattn/go-sqlite3

mkdir -p ${GOROOT}/src/github.com/influxdata/telegraf/plugins/processors/friendlytagger
cp friendlytagger.go ${GOROOT}/src/github.com/influxdata/telegraf/plugins/processors/friendlytagger/
sed -i '8i\        _ "github.com/influxdata/telegraf/plugins/processors/friendlytagger"' ${GOROOT}/src/github.com/influxdata/telegraf/plugins/processors/all/all.go

cd ${GOROOT}/src/github.com/influxdata/telegraf/ && make && go install -ldflags "-w -s" ./cmd/telegraf

Configuration

To enable this plugin, add the following to the "Processor Plugins" section of your telegraf configuration file:

[[processors.friendlytagger]]
    databasename = "/path/to/your/labeldatabase"

Your label database will be an SQLite3 database containing all of the tag to label mappings that the plugin can apply. See ../helperscripts for more information on how to create and populate this database file.

This plugin also supports several optional configuration options (in addition to the required databasename option):

reloadfrequency: the frequency at which the plugin should re-read the label mappings in the database (in seconds). Defaults to 120 (2 minutes). Longer intervals will mean it will take longer for any database updates to be applied to data processed by this plugin.

countrylabeltable: the name of the table in the database where country code to label mappings are stored. Defaults to country_mappings.

countylabeltable: the name of the table in the database where county number to label mappings are stored. Defaults to county_mappings.

regionlabeltable: the name of the table in the database where region number to label mappings are stored. Defaults to region_mappings.

asnlabeltable: the name of the table in the database where ASN to label mappings are stored. Defaults to asn_mappings.

Documentation

Overview

Package friendlytagger implements a telegraf processing plugin that adds human-readable labels to certain tags present in time series input.

Author: Shane Alcock <shane@alcock.co.nz>

Code tags that can be augmented with labels by this plugin: 

continent_code
country_code
region_code
county_code
asn

The code -> label mappings for all code tags (except the continent codes which are statically defined in this module) are read from an SQLite3 database. The database should have a separate table for each code tag type, e.g. a table for country codes, a table for ASNs etc.

The mapping tables should have the following columns: 

code (text)
label (text)
apply_from (int)

"code" is the tag value that will already be present in the report plugin output for the metric concerned. "label" is the human-readable label that corresponds to the code. For instance, a country code of "US" would have a label of "United States of America".

"apply_from" is a unix timestamp that indicates when a given label should be considered as applying to the code. This allows for a code to have different labels at different time periods, such as when a region changes names or an ASN changes ownership (and therefore name). When assigning a label to a code, this plugin will use the label with the closest "apply_from" timestamp to the timestamp associated with the telegraf metric.

If the underlying database is updated, you will need to restart telegraf to load any new mappings into the plugin.

See the accompanying README for details on how to install this plugin.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type FriendlyTag 

type FriendlyTag struct {
	// The name of the code field in the report plugin output
	CodedTag string
	// The name of the label field to add to the report plugin output
	NewTag string
	// The code->label mappings for this tag type
	ValueMappings map[string]LabelSet
}

A set of code->label mappings for a single tag type (e.g. country_code)

type FriendlyTagger 

type FriendlyTagger struct {
	// The path to the SQLite3 database where the code->label mappings are
	DatabaseName string

	// The name of the table where the country code mappings are
	CountryLabelTable string

	// The name of the table where the region code mappings are
	RegionLabelTable string

	// The name of the table where the county code mappings are
	CountyLabelTable string

	// The name of the table where the ASN name mappings are
	AsnLabelTable string

	// The set of code->label mappings, indexed by tag type (e.g.
	// country_code, asn, region_code, etc.)
	Replacements map[string]FriendlyTag

	LastReload int64

	ReloadFrequency int64
}

An instance of this plugin

func (*FriendlyTagger) Apply 

func (tagger *FriendlyTagger) Apply(in ...telegraf.Metric) []telegraf.Metric

Apply takes a metric received by telegraf and adds the appropriate human-friendly labels for any geo-tags and ASNs that might be present in the metric.

func (*FriendlyTagger) Description 

func (tagger *FriendlyTagger) Description() string

Description returns a brief description of this plugin, required by the telegraf processor plugin interface.

func (*FriendlyTagger) InsertFriendlyLabels 

func (tagger *FriendlyTagger) InsertFriendlyLabels(metric telegraf.Metric) telegraf.Metric

InsertFriendlyLabels scans a telegraf metric for any tags that match names where we can potentially add human-readable alternative labels, then looks up the value for the tag in our replacements map. If it finds a suitable label, then that label is added to the metric as another tag.

func (*FriendlyTagger) LoadAsnLabels 

func (tagger *FriendlyTagger) LoadAsnLabels()

LoadAsnLabels populates the Replacements map with the ASN to ASN label mappings from the database

func (*FriendlyTagger) LoadCountryLabels 

func (tagger *FriendlyTagger) LoadCountryLabels()

LoadCountryLabels populates the Replacements map with the country code to country label mappings from the database

func (*FriendlyTagger) LoadCountyLabels 

func (tagger *FriendlyTagger) LoadCountyLabels()

LoadCountyLabels populates the Replacements map with the county code to county label mappings from the database

func (*FriendlyTagger) LoadGenericLabels 

func (tagger *FriendlyTagger) LoadGenericLabels(table string,
	replacecode string, replacelabel string)

LoadGenericLabels reads the code->label mappings for a given tag type from the SQLite database and inserts them into memory for fast lookup when processing. "table" is the name of the table to read the mappings from. "replacecode" is the tag name for the field where the code will be found in the report plugin output (e.g. 'country_code', 'asn'). "replacelabel" is the tag name for the field where the label will be added if the code matches one of the codes found in the table (e.g. "country_label").

func (*FriendlyTagger) LoadRegionLabels 

func (tagger *FriendlyTagger) LoadRegionLabels()

LoadRegionLabels populates the Replacements map with the region code to region label mappings from the database

func (*FriendlyTagger) SampleConfig 

func (tagger *FriendlyTagger) SampleConfig() string

SampleConfig returns some sample configuration for this plugin, required by the telegraf processor plugin interface.

type LabelSet 

type LabelSet struct {
	StartTimes []int64
	Labels     []string
}

A set of labels for a given code and the timestamps from which those labels apply. Each entry in the Labels array will have its corresponding timestamp at the same index in the StartTimes array.

Example: ASN 681 changes its name from "University of Waikato, NZ" to "Quigley College, NZ" at timestamp 1592346088

StartTimes: {0, 1592346088} Labels: {"University of Waikato, NZ", "Quigley College, NZ"}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.