Dimensions, custom properties, and tags in Splunk Observability Cloud 🔗
Data comes into Splunk Observability Cloud as data points associated with a metric name and additional metadata. Observability Cloud has three types of metadata:
Metadata |
Description |
|---|---|
Dimensions |
Key-value pairs sent in with metric time series (MTS) at the time of ingest to add context to the metrics. |
Custom properties |
Key-value pairs applied to metric dimensions after ingest to add context to the metrics. |
Tags |
Labels or keywords applied to metric dimensions and custom properties after ingest. |
Note
All metrics and MTS generated by Splunk Observability Cloud start with the prefix sf. or sf_metric.
Comparing dimensions, custom properties, and tags 🔗
The following table shows the main differences between the three types of metadata
Metadata |
Created |
Format |
Can be added to |
Filter? |
Group by? |
|---|---|---|---|---|---|
Dimensions |
When Observability Cloud ingests data |
Key-value pair |
Metric time series |
Yes |
Yes |
Custom properties |
After ingest, through the user interface or REST API |
Key-value pair |
Dimensions and tags |
Yes |
Yes |
Tags |
After ingest, through the user interface or REST API |
String |
Dimensions and custom properties |
Yes |
No |
Dimensions 🔗
Dimensions are metadata in the form of key-value pairs that a monitoring software sends in along with the metrics. Dimensions provide additional information about the metric, such as the name of the host that sent the metric. For example, "hostname": "host1".
Note
Two key-value pairs with different keys are different dimensions, regardless of value.
Two key-value pairs that have the same key but different values are different dimensions.
Two key-value pairs with the same key and value are the same dimension.
Dimensions criteria 🔗
You can define up to 36 unique dimensions per MTS.
Dimension name criteria:
UTF-8 string, maximum length of 128 characters (512 bytes).
Must start with an uppercase or lowercase letter.
Must not start with an underscore (_).
After the first character, the name can contain letters, numbers, underscores (_), hyphens (-), and period (.).
Must not start with the prefix
sf_, except for dimensions defined by Observability Cloud such assf_hires.Must not start with the prefix
aws_,gcp_, orazure_.
Custom properties 🔗
Custom properties are key-value pairs you can assign to dimensions of existing metrics. For example, you can add the custom property use: QA to the host dimension of your metrics to indicate that the host that is sending the data is used for QA. The custom property use: QA then propagates to all MTS with that dimension. To learn more about adding custom properties to existing metric dimensions, see Search and edit metadata using the Metadata Catalog.
When Splunk Observability Cloud assigns a different name to a dimension coming from an integration or monitor, the dimension also becomes a custom property as it is assigned to the metric after ingest. For example, the AWS EC2 integration sends the instance-id dimension, and Observability Cloud renames the dimension to aws_instance_id. This renamed dimension is a custom property.
For more information on how Observability Cloud uses custom properties to rename dimensions generated by monitoring software, see Guidance for metric and dimension names.
You can also apply custom properties to tags. When you do this, anything that has that tag inherits the properties associated with the tag. For example, if you associate the "tier:web" custom property with the "apps-team" tag, Observability Cloud attaches the "tier:web" custom property to any metric or dimension that has the "apps-team" tag.
Custom properties criteria 🔗
You can define up to 75 custom properties per dimension.
Custom property name and value criteria:
Names must be UTF-8 strings with a maximum length of 128 characters (512 bytes).
Values must be UTF-8 strings with a maximum length of 256 characters (1024 bytes).
The optional description property lets you provide a detailed description of a metric, dimension, or tag. You can use up to 1024 UTF-8 characters for a description.
In custom property values, Observability Cloud stores numbers as numeric strings.
Tags 🔗
Note
Metadata tags in Splunk Infrastructure Monitoring are distinct from span tags in Splunk APM, which are key-value pairs added to spans through instrumentation to provide information and context about the operations that the spans represent. To learn more about span tags, see Manage services, spans, and traces in Splunk APM.
Tags are labels or keywords that you can assign to dimensions and custom properties. A tag is a string rather than a key-value pair. Use tags when you want to give the same searchable value to multiple dimensions.
To learn more about adding tags to existing metrics, see Search and edit metadata using the Metadata Catalog.
Tags criteria 🔗
Tags are UTF-8 strings with a maximum length of 256 UTF-8 characters/1024 bytes.
You can have up to 50 tags per dimension.
You can have up to 50 tags per custom property.
When to use each type of metadata 🔗
Each type of metadata has its own function in Observability Cloud. The following sections discuss several considerations to help you choose the most appropriate type of metadata for your metrics.
Dimensions versus custom properties 🔗
Note
Dimensions and custom properties are not distinguishable from one another in the UI, but they behave in different ways and serve different purposes.
Dimensions and custom properties are similar in that they are both key-value pairs that add context to your metrics and offer you the tools to effectively group and aggregate your metrics. The key differences between dimensions and custom properties are:
You send in dimensions at the time of ingest, and you add custom properties after ingest.
You can’t make changes to dimensions, but you can make changes to custom properties.
Due to these differences, use dimensions in the following situations:
When you need the metadata to define a unique MTS.
Example: You send in a metric called
cpu.utilizationfrom two data centers. Within each data center, you have 10 servers with unique names represented by these key-value pairs:host:server1,host:server2,…,host:server10. However, your server names are only unique within a data center and not within your whole environment. You want to add more metadata for your data centers,dc:westanddc:east, to help with the distinction. In this case, you need send metadata about the hosts and the data centers as dimensions because you know before ingesting that you want a separate MTS for every host in your environment.When you want to keep track of historical values for your metadata.
Example: You collect a metric called
latencyto measure the latency of requests made to your application. You already have a dimension for customers, but you also want to track the improvement between versions 1.0 and 2.0 of your application. In this case, you need to makeversion:1.0andversion:2.0dimensions. If you makeversion:1.0a custom property, then change it toversion:2.0when you release a new version of your application, you lose all the historical values for thelatencyMTS defined byversion:1.0.
Use custom properties in the following situations:
When you have metadata that provides additional context for your metrics, but you don’t want that metadata to create another uniquely identifiable MTS.
When you have metadata you know you want to make changes to in the future.
Example: You collect a metric called
service.errorsto know when your customers are running into issues with your services. The MTS for this metric are already uniquely identifiable by the customer and service dimensions. You want to attach the escalation contacts for each service for every customer to your metrics. In this case, you assign the escalation contacts as custom properties to the specific service dimension or customer dimensions. As your team grows and goes through reorganization, you want to be able to change this metadata. You also don’t need the escalation contacts as dimensions as the customer and service dimensions already yield separate MTS.
Tags 🔗
Use tags when there is a one-to-many relationship between the tag and the objects you are assigning it to.
Example 1: You do canary testing in your environment. When you do a canary deployment, you use the canary tag to mark the hosts that received the new code, so you can identify their metrics and compare their performance to those hosts that didn’t receive the new code. You don’t need a key-value pair as there’s only a single value, canary.
Example 2: You have hosts that run multiple apps in your environment. To identify the apps that a particular host is running, you create a tag for each app, then apply one or more of these tags to the host:<name> dimension to specify the apps that are running on each host.