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 metrics at the time of ingest to add context to the metrics.

Custom properties

Key-value pairs applied to metrics or dimensions after ingest to add context to the metrics or dimensions.

Tags

Labels or keywords applied to metrics, dimensions, detectors, and other objects after ingest.

Comparing dimensions, custom properties, and tags 🔗

The following table shows the main differences between the three types of metadata

Metadata

Created

Format

Used for

Filter?

Group by?

Dimensions

When Observability Cloud ingests data

Key-value pair

Metrics

Yes

Yes

Custom properties

After ingest, through the user interface or REST API

Key-value pair

Metrics, dimensions, tags, charts, and detectors

Yes

Yes

Tags

After ingest, through the user interface or REST API

String

Dimensions, charts, and detectors

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 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 (_) and hyphens (-).

  • 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 🔗

When Splunk Observability Cloud assigns a different name to a dimension coming from an integration or monitor, the dimension 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 assign your own custom properties 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 value. To learn more about adding custom properities to existing metrics, see Search and edit metadata using the Metadata Catalog.

You can 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.

You can also add custom properties to charts and detectors. In this case, the custom properties identify some aspect of the chart or detector that you can query.

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 assign to dimensions. 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.

You can also assign tags to charts and detectors and use them to filter your charts and detectors.

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.

  • You can only have 50 tags per chart or detector

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 🔗

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 metric time series (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 need the metadata for the MTS to be uniquely identifiable.

  • 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.