Docs » Dimensions, custom properties, and tags in Splunk Observability Cloud

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.

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 as sf_hires.

  • Must not start with the prefix aws_, gcp_, or azure_.

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 for you to 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:

  1. You send in dimensions at the time of ingest, and you add custom properties after ingest.

  2. 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.utilization from 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:west and dc: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 latency to 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 make version:1.0 and version:2.0 dimensions. If you make version:1.0 a custom property, then change it to version:2.0 when you release a new version of your application, you lose all the historical values for the latency MTS defined by version: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.errors to 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.