Calculate metrics in Splunk IAI

As a Splunk IAI administrator, you can create calculated metrics based on other metrics using the formula builder interface.

Create calculated metrics to accomplish the following goals:

• Create a useful metric for analysis, monitoring, or alerting that doesn't exist in your raw data by writing a formula based on one or more raw or calculated metrics.
• Calculate a useful value based on external data sources such as market prices or weather data that you can use for analysis, monitoring, or alerting.
• Convert the units from your raw data into more meaningful units for monitoring or comparing with other metrics. For example, you can create a formula to convert from Fahrenheit to Celsius.

Create a calculated metric

You can calculate metrics for individual assets or for groups of assets. After you save a calculated metric, it becomes available to all Splunk IAI users immediately. Create calculated metrics for groups and assets with unique names to avoid conflicts.

1. Select the asset or group that you want to create a calculated metric for.
   1. From Splunk IAI, select the Browse view.
   2. To calculate a metric for an asset, select the asset on the Assets tab. To calculate a metric for a group, select the group from the Groups tab, and then click Group Metrics.
2. Click Add.
3. Type a Name and an optional Description for the metric that you are creating.
4. Click Add. Splunk IAI opens the formula builder where you can create your calculated metric.
5. Use the browser panel on the left side of Splunk IAI to navigate the metrics and other data available to use as components of your formula.

   If your data contains more than 1000 assets, metrics, or alarms for a particular hierarchy node, you can only view the first 1000 results of each type for a particular node. Use the filter to search for the specific asset, metric, or alarm name.

   • Use the Assets tab to navigate your assets. You can use any raw or calculated metrics on any asset in your operation in your formula. Click a metric to use it in a formula.
   • If you are creating a calculated metric for a group, use the Groups tab to access a list of group metrics for the group that you are creating a metric for. You can use metrics from other groups by browsing to them from the Assets tab. Click a metric to use it in a formula.
   • Use the Other tab to search for numeric event data to use in your formula. You must specify an index, and you can narrow your search by sourcetype and keyword. The search returns a list of fields that match your criteria. Click a field to use it in a formula.
6. Use the Functions on the right side of Splunk IAI to apply functions and mathematical operations. Click a function or operator to use it in the formula. You cannot type function names manually. Some functions, such as the informational functions, must be used in combination with other functions.
7. In the canvas in the center of the screen, type numbers, mathematical symbols, parentheses, and logical operators. Place your cursor in the location you want to add a metric or function from the side panels, or highlight content in order to wrap it in a function. You cannot edit metrics, fields, or functions in this panel. You can only add and remove them.
8. Above the formula, specify the time interval for the calculation. The default is 1 minute.
   When you analyze your metric in the Analyze view, the timechart displaying the calculated metric uses a span equal to this time interval. When displayed on a monitor view, the calculated metric is computed based on the latest values in this interval of the component metrics.
9. When you are finished, click Save.

The operator precedence in formulas is as follows:

1. Commas in comma-supported arguments.
2. Parentheses enclosing the functions.
3. Multiplication and division, from left to right.
4. Addition and subtraction, from left to right.

For more detailed descriptions of each function, see Function reference.

If you try to save a formula for your metric and see a message indicating that you have a syntax error, see Troubleshoot issues creating formulas for calculated metrics.

Validate your formula before you base any alerts, other metrics, or monitor views on this metric. Check the validity of your calculated metric after you save it by clicking Analyze in the row for that metric. If the time series chart produces an error or doesn't look as you expect, verify that your formula is correct.

Edit the formula of a calculated metric

As an IAI admin, you can edit the formula of any calculated metric.

1. From Splunk IAI, select the Browse view.
2. Navigate to the calculated metric from the Assets or Groups tab.
3. Click the name of the metric.
4. In the metric details page, click Edit Formula in the right panel above the formula.
5. Edit the formula, and then click Save.

Edit the name of a calculated metric

You can rename calculated metrics for assets and groups.

Rename a calculated metric for an asset

1. From Splunk IAI, select the Browse view.
2. From the Assets tab, locate the asset that you calculated the metric for.
3. In the list of metrics, locate the metric that you want to rename.
4. In the Actions column, click Rename.
5. Type a new Name and optionally update the description.
6. Click Rename.

Rename a calculated metric for a group

1. From Splunk IAI, select the Browse view.
2. From the Groups tab, locate the group that the calculated metric applies to.
3. Click the group name, then click Group Metrics to view the calculated metrics for the group.
4. In the list of metrics, locate the metric that you want to rename.
5. In the Actions column, click Rename.
6. Type a new Name and optionally update the description.
7. Click Rename.

Rename a calculated metric from the formula builder

You can rename a calculated metric for an asset or group while editing the formula for the calculated metric.

1. From the formula builder, click the pencil icon next to the metric name.
2. Type a new Name and optionally update the description.
3. Click Change to save the changes.

Rename a calculated metric from the metric details

1. From Splunk IAI, select the Browse view.
2. Navigate to the calculated metric from the Assets or Groups tab.
3. Click the name of the metric.
4. Click Rename.
5. Type a new Name and optionally update the description.
6. Click Rename.

Delete a calculated metric

As an IAI administrator, you can delete calculated metrics.

Deleting a calculated metric is irreversible. If the calculated metric is in use, deleting it can cause other metrics and views to stop functioning correctly.

Deleting a calculated metric can have the following consequences:

• If you created alerts on the calculated metric, deleting the calculated metric also deletes the alerts.
• If you created other calculated metrics that use this calculated metric, deleting the calculated metric causes those metrics to stop working.
• If you created monitor views that use this calculated metric, deleting the calculated metric causes the widgets for this metric to display a message stating "This metric is not available."

To delete a calculated metric, perform the following steps:

1. From Splunk IAI, select the Browse view.
2. Navigate to the calculated metric from the Assets or Groups tab.
3. Delete the metric by clicking Delete in the Actions column, or click the name of the metric and click Delete.
4. Check the boxes to confirm that you understand the consequences of deleting the metric.
5. Click Delete.

Troubleshoot issues creating formulas for calculated metrics

If you see an error message indicating you have a syntax error in your formula, check for the following common issues:

• Do you have the expected number of arguments in each function?
• Are the function arguments comma-separated?
• Are all parentheses balanced?
• Are all mathematical operators logically placed?
• Is the first argument of each IF function a Boolean?
• If you used an informational function, is it used inside of a conditional function?

If you test a calculated metric on the Analyze page and see an error, check the following aspects of the metric:

• When you create a calculated metric for an asset that uses a calculated metric for a group in its formula, that asset must contain any and all raw metrics that are used in the formula for that group calculated metric.
  • For example, you create a calculated metric called tempC that converts a raw temperature metric temp to Celsius for all assets in the group Machines. You want a calculated metric on the asset Pilot Line that takes an average of all the temperatures of all the machines in the pilot line of your factory. Because of a current limitation of group metric functionality, you must use the raw temp metric for each asset in your formula, take the average, and then convert that to Celsius. You cannot use the group calculated metric in the formula for the average because the Pilot Line asset doesn't share the temp raw metric.

If you see an error on the Analyze page but you believe your formula is supported, submit a case using the Splunk Support Portal.

Function reference

If you are familiar with the functions used by the Search Processing Language (SPL) in Splunk software, the formula builder uses a subset of those functions.

Category	Function	Description	Example
Boolean Operators	AND	Returns values if all functions it connects return results. Use in combination with functions.	if(Floor1.Line1.Oven1.temp > 90 AND Floor1.Line1.Oven2.temp > 90, 1, 0)
Boolean Operators	OR	Returns values if any of the functions it connects return results. Use in combination with functions.	if(Floor1.Line1.Oven1.temp > 90 OR Floor1.Line1.Oven2.temp > 90, 1, 0)
Boolean Operators	NOT	Removes the values of the functions that follow it from results. Use in combination with functions.	if(NOT isbool(Floor1.Line1.Oven1.temp), 1, 0)
Conditional	if(condition, X, Y)	Checks whether a condition is met and returns X if true and Y if false. You can nest additional conditional functions or other functions inside the arguments.	if(Floor1.Line1.Oven1.temp > 90, 1, 0)
Informational	isbool(X)	Returns true if X is a Boolean. Use with conditional functions.	if(isbool(Floor1.Line1.Oven1.temp), 1, 0)
Informational	isint(X)	Returns true if X is an integer. Use with conditional functions.	if(isint(Floor1.Line1.Oven1.temp), Floor1.Line1.Oven1.temp*10, Floor1.Line1.Oven1.temp/10)
Informational	isnotnull(X)	Returns true if X is not null. Use with conditional functions.	if(isnotnull(Floor1.Line1.Oven1.temp), 1, 0)
Informational	isnull(X)	Returns true if X is null. Use with conditional functions.	if(isnull(Floor1.Line1.Oven1.temp), 0, 1)
Informational	isnum(X)	Returns true if X is a number. Use with conditional functions.	if(isnum(Floor1.Line1.Oven1.temp), Floor1.Line1.Oven1.temp, 42)
Informational	isstr(X)	Returns true if X is a string. Use with conditional functions.	if( isstr(Floor1.Line1.Oven1.temp), 98, Floor1.Line1.Oven1.temp)
Mathematical	abs(X)	Returns the absolute value of X.	abs(Floor1.Line1.Oven1.temp)
Mathematical	ceiling(X)	Returns X rounded up to the nearest whole integer.	ceiling(Floor1.Line1.Oven1.temp)
Mathematical	exact(X)	Returns X with a larger amount of precision.	exact(Floor1.Line1.Oven1.temp)
Mathematical	exp(X)	Returns the exponential function e to the power of X.	exp(Floor1.Line1.Oven1.temp)
Mathematical	floor(X)	Returns X rounded down to the nearest whole integer.	floor(Floor1.Line1.Oven1.temp)
Mathematical	ln(X)	Returns the natural logarithm of X.	ln(Floor1.Line1.Oven1.temp)
Mathematical	log(X,Y)	Returns the logarithm of X base Y. The default for Y is 10.	log(Floor1.Line1.Oven1.temp,10)
Mathematical	pow(X,Y)	Returns X to the power of Y.	pow(Floor1.Line1.Oven1.temp,10)
Mathematical	round(X,Y)	Returns X rounded to the amount of decimal places specified by Y.	round(Floor1.Line1.Oven1.temp, 2)
Mathematical	sigfig(X)	Returns X rounded to the appropriate number of significant figures.	sigfig(Floor1.Line1.Oven1.temp, 3)
Mathematical	sqrt(X)	Returns the square root of X.	sqrt(Floor1.Line1.Oven1.temp)
Mathematical	sum(X, ...)	Returns the sum of its arguments. Separate arguments with commas.	sum(Floor1.Line1.Oven1.temp, -32)/1.8
Statistical	avg(X, ...)	Returns the average of its arguments. Separate arguments with commas.	avg(Floor1.Line1.Oven1.temp, Floor1.Line1.Oven2.temp, Floor1.Line1.Oven3.temp)
Statistical	max(X, ...)	Returns the maximum value of its arguments. Separate arguments with commas.	max(Floor1.Line1.Oven1.temp, Floor1.Line1.Oven2.temp, Floor1.Line1.Oven3.temp)
Statistical	min(X, ...)	Returns the minimum value of its arguments. Separate arguments with commas.	min(Floor1.Line1.Oven1.temp, Floor1.Line1.Oven2.temp, Floor1.Line1.Oven3.temp)
Statistical	range(X, ...)	Returns the difference between the maximum and minimum arguments. Separate arguments with commas.	range(Floor1.Line1.Oven1.temp, Floor1.Line1.Oven2.temp, Floor1.Line1.Oven3.temp)
Trigonometry	acos(X)	Returns the arc cosine of X.	acos(Floor1.Line1.Slicer1.angle)
Trigonometry	acosh(X)	Returns the arc hyperbolic cosine of X.	acosh(Floor1.Line1.Slicer1.angle)
Trigonometry	asin(X)	Returns the arc sine of X.	asin(Floor1.Line1.Slicer1.angle)
Trigonometry	asinh(X)	Returns the arc hyperbolic sine of X.	asinh(Floor1.Line1.Slicer1.angle)
Trigonometry	atan(X)	Returns the arc tangent of X.	atan(Floor1.Line1.Slicer1.angle)
Trigonometry	atanh(X)	Returns the arc hyperbolic tangent of X.	atanh(Floor1.Line1.Slicer1.angle)
Trigonometry	cos(X)	Returns the cosine of X.	cos(Floor1.Line1.Slicer1.angle)
Trigonometry	cosh(X)	Returns the hyperbolic cosine of X.	cosh(Floor1.Line1.Slicer1.angle)
Trigonometry	sin(X)	Returns the sine of X.	sin(Floor1.Line1.Slicer1.angle)
Trigonometry	sinh(X)	Returns the hyperbolic sine of X.	sinh(Floor1.Line1.Slicer1.angle)
Trigonometry	tan(X)	Returns the tangent of X.	tan(Floor1.Line1.Slicer1.angle)
Trigonometry	tanh(X)	Returns the hyperbolic tangent of X.	tanh(Floor1.Line1.Slicer1.angle)

Extended function examples

The following are extended examples of calculated metrics you can create with the formula builder.

Set a null metric to a static value

For example, if you want to set a metric to a static value if it is null in the data, you could construct a calculated metric with the following formula:

if(isnull(Floor1.Line1.Oven1.temp), 10, Floor1.Line1.Oven1.temp)

In this case, if the temperature for Oven1 on Line1 on Floor1 is null, the value is set to 10. Otherwise, the value remains the value of the metric.

Convert a string value into a static numeric value

For example, if you want to convert a string value into a static numeric value, you could construct a calculated metric with the following formula:

if(isstr(Floor1.Line1.Oven1.temp), 98, Floor1.Line1.Oven1.temp)

In this case, if the temperature for Oven1 on Line1 on Floor1 is a string, the value is set to 98. Otherwise, the value remains the value of the metric.

Set a value based on the lack of a particular condition

For example, if you want to set a metric to a particular value if a particular condition is not true, you can use the NOT Boolean operator in combination with another function inside of a conditional function. To do this, you could construct a calculated metric with the following formula:

if(NOT sum(Floor1.Line1.Oven1.temp, Floor1.Line1.Oven2.temp)<1000, 85 , 25)

In this case, if the sum of the temperature of the two ovens is less than 1000, set the value of the calculated metric to 85. If the sum of the temperature of the two ovens is not less than 1000, set the value of the calculated metric to 25.

You can get the same result with if(sum(Floor1.Line1.Oven1.temp, Floor1.Line1.Oven2.temp)<1000, 25, 85).