Tagging is used throughout the Stackstate product to make it easier to subset and query the machines and metrics that you have to monitor. Without the ability to assign and filter based on tags, finding the problems that exist in your environment and narrowing them down enough to discover the true causes would be extremely difficult.
There are four primary ways to assign tags: inherited from the integration, in the configuration, in the UI, and using the API. The recommended method is to rely on the integration or via the configuration files.
The easiest method for assigning tags is to rely on the integration. Tags assigned to your Chef recipes, Docker labels, and more are all automatically assigned to the hosts and metrics when they are brought in to Stackstate.
The following integration sources create tags automatically in Stackstate:
|Apache||Apache Host and Port|
|BTRFS||Usage & Replication Type|
|Consul||Previous and Current Consul Leaders and Followers, Consul Datacenter, Service Name, Service ID|
|CouchDB||Database Name, Instance Name|
|CouchBase||CouchBase Tags, Instance Name|
|Docker||Docker Container and Image Name, Container Command, Container Labels|
|Elasticsearch||Cluster Name, Host Name, Port Number|
|Etcd||State Leader or Follower|
|Fluentd||Host Name, Port Number|
|Go Expvar||Expvar Path|
|Gunicorn||State Idle or Working, App Name|
|HAProxy||Service Name, Availability, Backend Host, Status, Type|
|HTTP Check||URL, Instance|
|Kubernetes||Minion Name, Namespace, Replication Controller, Labels, Container Alias|
|Memcached||Host, Port, Request, Cache Hit or Miss|
|Mesos||Role, URL, PID, Slave or Master Role, Node, Cluster,|
|OpenStack||Network ID, Network Name, Hypervisor Name, ID, and Type, Tenant ID, Availability Zone|
|PHP FPM||Pool Name|
|RabbitMQ||Node, Queue Name, Vhost, Policy, Host|
|Redis||Host, Port, Slave or Master|
|SNMP||Device IP Address|
|Supervisord||Server Name, Process Name|
|TeamCity||Tags, Code Deployments, Build Number|
|TokuMX||Role Primary or Secondary, Replset, Replstate, Db, Coll, Shard|
|VSphere||Host, Datacenter, Server, Instance|
|Win32 Events||Event ID|
|Windows Services||Service Name|
The Stackstate integrations are all configured via the yaml configuration files located in the conf.d directory in your agent install. For more about where to look for your configuration files, refer to this article. You can define tags in the configuration file for the overall agent as well as for each integration, though the stackstate.conf file is a more traditional ini file. In yaml files, there is a tag dictionary with a list of tags you want assigned at that level. Any tag you assign to the agent will apply to every integration on that agent’s host.
Dictionaries with lists of values have two different yet functionally equivalent forms:
tags: firsttag, secondtag, thirdtag
tags: - firsttag - secondtag - thirdtag
You will see both forms in the yaml configuration files, but for the stackstate.conf ini file only the first form is valid.
Each tag can be anything you like but you will have the best success with tagging if your tags are key:value pairs. Keys could represent the role, or function, or region, or application and the value is the instance of that role, function, region, or application. Here are some examples of good tags:
region:east region:nw application:database database:primary role:sobotka
The reason why you should use key value pairs instead of simply values will become apparent when you start using the tags to filter and group metrics and machines. That said, you are not required to use key value pairs and simple values are valid.
After you have assigned tags at the host and integration level, you can start using them to filter and group in interesting ways. There are several places you can use tags:
TODO: Write documentation about the usage of tags.