Docs » Metrics in Splunk Observability Cloud » Metadata: Dimensions, custom properties, tags, and attributes

Metadata: Dimensions, custom properties, tags, and attributes 🔗

Splunk Observability Cloud data comes enriched with additional metadata:

Name

Description

Data type

Format

Dimensions

Sent in with metric time series (MTS) at the time of ingest to add context to metrics. Along with the metric name, they uniquely identify the MTS. Dimension names do not change over time.

Infrastructure metric

Key-value pair

Custom properties

Applied to metric dimensions after ingest to add context to the metrics. Custom properties do not contribute to uniquely identify an MTS.

Infrastructure metric

Key-value pair

Tags

Labels or keywords applied to metric dimensions and custom properties after ingest to help you categorize them. You can use tags to filter MTSes in charts and detectors using sf_tags.

Infrastructure metric

String

Attributes or span tags

Annotation to carry information about the operation being tracked.

APM metric, Collector metric, span

Key-value pair

Dimensions 🔗

Caution

The OpenTelemetry data model uses attributes instead of dimensions. See more at Tags in OpenTelemetry.

Dimensions are immutable metadata in the form of key-value pairs that monitoring software sends in along with the metrics. The set of MTS dimensions sent during ingest is used, along with the metric name, to uniquely identify an MTS.

Dimensions provide additional information about the metric, such as the name of the host that sent the metric. For example, "hostname": "host1".

The following applies:

  • Two key-value pairs with different keys are different dimensions, regardless of value. For example, "hostname": "bcn" and "clustername": "bcn".

  • Two key-value pairs that have the same key but different values are different dimensions. For example, "hostname": "bcn" and "hostname": "gir".

  • Two key-value pairs with the same key and value are the same dimension. For example, "hostname": "host" and "hostname": "host".

See how to use dimensions in When to use each metadata type in Infrastructure.

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 periods (.), but cannot contain blank spaces.

  • Must not start with the prefix sf_, except for dimensions defined by Splunk Observability Cloud such as sf_hires.

Custom properties 🔗

Custom properties are key-value pairs you can assign to dimensions of existing MTSes after ingest. Custom properties are single-valued and don’t support multiple values.

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 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 Splunk Observability Cloud renames the dimension to aws_instance_id. This renamed dimension is a custom property.

For more information on how Splunk 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, Splunk 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). Avoid custom property names already used as dimension names.

  • 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, Splunk Observability Cloud stores numbers as numeric strings.

Infrastructure Monitoring tags 🔗

In Infrastructure Monitoring, tags are labels or keywords you can assign to dimensions and custom properties to give the same searchable value to multiple dimensions. Unlike custom properties, tags go under the sf_tags property of a dimension and can have multiple values.

To learn more about adding tags to existing metrics, see Search 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.

Span attributes or tags 🔗

Tags are used when there is a need for a many-to-one relationship of tags to an object or a one-to-many relationship between the tag and the objects you are applying them to. They are useful for grouping together metrics that may not be intrinsically associated.

Attributes in OpenTelemetry 🔗

In the OpenTelemetry data model, metadata is provided as span attributes or tags. You can add and modify them using an attributes processor in your Collector’s traces pipelines.

Learn more in Tags in OpenTelemetry.

Attributes in Splunk APM 🔗

In Splunk APM, span tags 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 in APM, see:

Attributes in Splunk RUM 🔗

To set global attributes in RUM, see:

When to use each metadata type in Infrastructure 🔗

The following table shows the main differences between the types of IM metadata:

Metadata

Created

Can be added to

Filter?

Group by?

Dimensions

When Splunk Observability Cloud ingests data

Metric time series

Yes

Yes

Custom properties

After ingest, through the user interface or REST API

Dimensions and tags

Yes

Yes

Tags

After ingest, through the user interface or REST API

Dimensions and custom properties

Yes

No

Each type of metadata has its own function in Splunk Observability Cloud. The following sections discuss several considerations to help you choose the most appropriate type of metadata for your metrics.

Use dimensions or 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:

Example: Sending the same metric from multiple data centers 🔗

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

Example: Tracking and comparing historical values 🔗

Suppose 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: Adding context without creating more MTS 🔗

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

Use Infrastructure Monitoring tags 🔗

In Infrastructure Monitoring, use tags when there is a one-to-many relationship between the tag and the objects you are assigning it to.

Example: Canary testing 🔗

Suppose you do canary testing in your environment. When you create a canary deployment, you can 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: Host running multiple applications 🔗

Suppose you have hosts that run multiple applications in your environment. To identify the apps that a particular host is running, 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.

This page was last updated on Jun 25, 2024.