Introduction to iStats Part 1: Overview

Version 11 of BIG-IP brought with it many enhancements and new features ranging across the entire product. iRules improvements and features were among the cooler things changed, in the opinion of this avid iRuler. Between sideband connections, iFiles and improvements of already existing functionality, it's hard to imagine there is more yet to discuss in v11 iRules goodness, but there is. iStats were introduced in v11, and are worth talking about, as they can dramatically change the way you are solving problems, depending on your deployment. In this 2-parter we'll talk about iStats first from a higher level overview/introduction perspective, and then a bit more in-depth in part 2, talking about specific metrics that are measurable, commands available from within iRules, etc.

What are iStats?

iStats are user-created custom statistics, accessible from both the data plane (iRules) and the control plane (tmsh, on-box scripts, etc.).

iStats are similar in concept to the existing stats profile, with several important variations.  First let's look at what we know about a stats profile:

• - Limited to a small number of statistics
• - All stats must be preconfigured
• - Stat values are sometimes available only on a per-TMM basis
• - Cannot be modified from the control plane

While a stats profile can be useful in many cases, it is largely used to track data plane only metrics such as connections, data rates, etc. They aren't amazingly flexible, and provide limited hooks into the control plane (command line, GUI, etc.) which makes them somewhat isolated from the bigger picture of your BIG-IP's configuration and existence at large.

In contrast, let's look at iStats in a similar way and compare the differences:

• - Users can create an arbitrary number of iStats (although there is a practical limit of 5,000-10,000 iStats)
• - iStats do not have to be preconfigured or predefined, they can be built on the fly, effectively
• - Any consumer of iStats (even iRules) will always get the global view (meaning, not on a per-TMM basis, but rather aggregated over all stat producers), which is extremely important in many cases where you want to look at the overall picture when referencing a stat, not a per TMM number, given that there are multiple if not many TMMs per device in most cases
• - iStats can be both read and modified by the control plane, I.E. TMSH

Hopefully the picture that is shaping up is as obvious to everyone else as it is to me. iStats provides a more flexible, scalable, picture complete (non TMM specific) mechanism for tracking information vital to your deployment, and critical when building business solutions in many cases. The fact that iStats give you a view of the entire device when querying any particular stat, vs. a TMM specific one is massive. That alone is game changing in some cases. As a tradeoff for these benefits, the values returned by iStats are only updated periodically (every 10 seconds on an appliance or chassis with a single blade, or every 20-30 seconds on a chassis with multiple blades), as opposed to the precise real-time values in stats profiles. This means that in granular, real-time dependent situations where you are basing traffic decisions off of stats, stats profiles may still be the way to go, but that is of course situationally dependent.

How do I use iStats?

For both the purposes of this explanation, and when dealing with iStats in general, it is important to distinguish between the statistics you want to gather, and the things you want to gather them on. The thing you want to gather them on will be referred to here as the "subject", and the statistics you want to gather about the subject are referred to as "measures".  For example, you might want to record both the number of requests as well as the number of connections for pool members; in this case, a particular pool member will be the subject, and the request and connection counts will be the measures.

An iStat handle is composed of three parts: a subject name, a measure type, and a measure name. Together, this is referred to as the iStat "key". A subject name is a set of alternating keyspace/value pairs, all separated by spaces. Keyspaces, Measure Names and Values are arbitrary strings. At least one pair must be used, but more may be used. For example, a subject name might be "key1 value1", or "key1 value1 key2 value2", but could not be "key1 value1 key2".

That's a lot of terminology, let's review that for clarity:

• Subject Name - The thing you want to gather data on. I.E. a VIP, pool, etc.
• Measure Type - The statistics you want to gather about the subject, I.E. connections, requests, etc.
• Measure Name - An arbitrary name for the measure in question
• Key - The combination of the subject name, measure type and measure name, encapsulated in quotes.

Building an iStat

To construct an iStat key, you simply take the subject name and append the measure type and the measure name, again all separated by spaces.  The entire key must be enclosed in quotes. For instance, a valid key could be "a b c d". This would be a counter ('c' is shorthand for 'counter') named 'd', for a subject with a value of 'b' in keyspace 'a'. To clarify, let's look at a somewhat less generic example so you can see these different parts in action:

For an instance where:

• - Keyspace is "src_ip"
• - Value of the stat is "1.2.3.4"
• - Measure Type is counter, or "c" for shorthand
• - Measure Name "Connections"

The finished key would be "src_ip 1.2.3.4 c Connections".

An iStat key for a subject which has multiple key/value pairs could be: "src_ip 1.2.3.4 src_port 5678 counter connections", which would be a counter called "connections" for a subject with a value of "1.2.3.4" in keyspace "src_ip" and a value of "5678" in keyspace "src_port". So you are effectively tracking the source IP and source port simultaneously in a single key, by assigning it multiple key/value pairs.

It is important to note that the type of the iStat measure is part of the iStat key. This means that you could have multiple measures all with the same subject name and measure name but differing types. For example, "client 1.2.3.4 counter hits" is different from "client 1.2.3.4 gauge hits", both of which are different from "client 1.2.3.4 string hits". Even though they are all using the same keyspace, value and name, they are of different measure types and that is enough to differentiate them, technically speaking. As such all three of these could be used at the same time (as they are all distinct iStat keys), but this is discouraged to prevent confusion. As you can imagine this could get pretty heinous to logically track pretty quickly. It's better to keep things more distinct, most times. It is also important to note that the key/value pairs that make up the subject name are not forced to be specified in order. Meaning, "src_ip 1.2.3.4 src_port 5678" refers to the same subject as "src_port 5678 src_ip 1.2.3.4".

Interacting with iStat: TMSH & iRules

As mentioned earlier in the "What is an iStat" section, an iStat may be associated with a TMSH configuration object. In this case, the subject name would be a keyspace of a tmsh component dotted path, and a value of a specific object name or id. For example, ''ltm.pool /Common/my_pool counter num_hits" would refer to a counter named num_hits which is associated with the LTM pool named my_pool located in the Common folder. 

These custom iStats will be displayed with the tmsh show command on the associated object, but will not appear in the GUI. When either ''reset-stats ltm pool my_pool'' or ''delete ltm pool my_pool'' is executed from TMSH, all associated iStats will be automatically reset or deleted as well. Specifying keyspace/value pairs beyond what is necessary to describe the configuration object will interfere with object associations. In most cases, this means there will be a single keyspace/value pair for iStats associated with config objects, but iStats associated with pool members require two keyspace/value pairs: "ltm.pool /Common/my_pool member /Common/10.1.1.1:6666 counter hits".

iStats and their measures may be created, modified, and retrieved via iRules or TMSH scripts, making them amazingly flexible and giving you a wide array of options when building your keys. Any iRule or TMSH client can produce any iStat if they specify the exact key. Also, any iRule can read any iStat. For those of you keeping up, this means that you can specifically create iStats from within TMSH to expose data that is not currently available via iRules commands, and then have your iRule reference that particular iStat. This breaks open a new wealth of information that you can make available to your iRules if you so desire. If an iStat is not associated with a configuration object, then any TMSH client can read that iStat. If an iStat is associated with a configuration object, then a TMSH client can only read that iStat if they have permission to access the object it is associated with. In this way you can limit particular stats to particular roles. Even though the information is only periodically updated, there are several uses for this particular interaction.

iStats Facts

There is simply so much to say about iStats, how they can be used and how they work, that I had to break it into two parts. Before wrapping up, though, here are a few more facts about iStats to help you understand more about how their inner workings:

• - iStats are created on first write and do not need to be declared separately.
• - Each producer of an iStat will update its own private, local copy of that statistic.
• - A daemon on the system is responsible for periodically combining the data from the iStat producers into an aggregated version. That aggregated version is what any consumer of an iStat will read.
• - iStats currently supports three types of measures: counters, gauges, and strings. It is also possible to create derived stats. More information on these types of measures and stats will be available in Part 2.

Wrapping-up

iStats are powerful, flexible, and there are limitless ways to configure, build and manipulate them via both TMSH and iRules. They are an informational bridge from the control plane (TMSH) to the data plane (iRules), which is a new and revolutionary feature unto itself within BIG-IP. There will be more details on command specifics and usage in the next part so be sure to look there for the implementation details if that's what you're looking for. For now though, if there are any questions so far, don't hesitate to ask them here.

I also want to give a massive thank you to spark (DC Username) one of the core engineers responsible for bringing you new and exciting iRules features. He provided the lion's share of this information directly from the horse's mouth, as it were, which helps immeasurably in bringing the community the details that you crave. So if you see spark around the forums, pay attention and maybe say thanks.