Docs » Reference » Best Practices » Metric, Dimension, and Event Name Requirements

Metric, Dimension, and Event Name Requirements 🔗

Metric, dimension, and event data name requirements help you choose useful names and avoid problems.

Splunk Infrastructure Monitoring has two broad categories of data names:

  • When you use an existing data collection integration such as the collectd agent or the AWS CloudWatch integration, the integration defines metric, dimension, and event names for you. To learn more , see the Integrations Guide and Integrations Reference.
  • When you send custom metrics, dimensions, or events to Infrastructure Monitoring, you choose your own names.
  • Infrastructure Monitoring also lets you send custom events for which you choose your own names. To learn more about custom event names, see Custom event name requirements.

Note

This topic assumes some knowledge of the Infrastructure Monitoring data model.

Metric names and dimension key name requirements 🔗

  • Separate out dimensions from metric names.

    • Metrics are distinct numeric measurements that change over time. They’re generated by system infrastructure, application instrumentation, or other hardware or software. The following are some examples of metrics:

      • Count of GET requests received
      • Percent of total memory in use
      • Network response time in milliseconds
    • Dimensions are arbitrary key-value pairs you associate with metrics. They can be numeric or non-numeric. Some dimensions, such as host name and value, come from a system you’re monitoring. You can also create your own dimensions. The following are some examples of dimensions:

      • "hostname": "production1"
      • "region": "emea"

      By using dimensions, you get the following benefits:

      • Classification of different streams of data points for a metric.
      • Simple representation of metrics and metadata without overloading the meaning of the metric name.
      • Shorter, more readable metric names
      • Simplified filtering and aggregation. For example, SignalFlow lets you filter and aggregate data streams by one or more dimensions.
    • Compatibility: For compatibility with other monitoring systems such as Graphite and New Relic, the Infrastructure Monitoring UI supports long metric names delimited by periods or slashes. Even so, some features such as dashboard variables or the Infrastructure Navigator require the use of dimensions. If you have metrics with long period-separated names (such as the names used by Graphite), use the SignalFx Gateway to create dimensions from your metrics.

  • Modify naming schemes you used for other metrics systems. When you send metrics that you previously sent to other metrics systems such as Graphite, New Relic, and so forth, modify the naming scheme to take full advantage of Infrastructure Monitoring features. To learn more, see Example: Custom metric name and dimensions.

  • Send low-cardinality data only in metric names or dimension key names.

    • Low-cardinality data has a small number of distinct values. For example, the metric name web.http.error.count for a gauge metric that reports the number of HTTP request errors has a single value. This name is also readable and self-explanatory.

    • High-cardinality data has a large number of distinct values. For example, timestamps and UUIDs are high-cardinality data. Only send this kind of high-cardinality data in dimension values.

      If you send high-cardinality data in metric names, Infrastructure Monitoring might not ingest the data. Infrastructure Monitoring specifically rejects metrics with names that contain timestamps or UUIDs.

    • High-cardinality data does have legitimate uses. For example, in containerized environments, container_id is usually a high-cardinality field. If you include container_id in a metric name such as system.cpu.utilization.<container_id>, instead of having one MTS, you would have as many MTS as you have containers.

      To learn more about metric time series, see Data Model.

  • Create metric names using a hierarchical left to right structure.

    Start at the highest level, then add more specific values as you proceed. For example:

    • Start with a domain or namespace that the metric belongs to, such as analytics or web.
    • Next, add the entity that the metric measures, such as jobs or http.
    • At your discretion, add intermediate names, such as errors.
    • Finish with a unit of measurement. For example, Splunk Infrastructure Monitoring reports these metrics from its analytics service:
      • analytics.jobs.total: Gauge metric that periodically measures the current number of executing jobs
      • analytics.thrift.execute.count: Counter metric that’s incremented each time new job starts
      • analytics.thrift.execute.time: Gauge metric that measures the time needed to process a job execution request
      • analytics.jobs_by_state: Counter metric with a dimension key called state, incremented each time a job reaches a particular state.

    All these metrics have a hostname dimension key with values such as analytics-1, analytics-2, and so forth. These metrics also have a customer dimension key with values org-x, org-y, and so forth. The dimensions provide an infrastructure-focused or a customer-focused view of the analytics service usage.

  • Use different metric names to indicate metric types.

    In the Infrastructure Monitoring data model, all metrics have a single metric type, with a specific default rollup. The following list shows the types and their default rollups:

    • Gauge metric: Average (mean() SignalFlow function)
    • Counter metric: Sum (sum() SignalFlow function)
    • Cumulative counter: Delta (delta() SignalFlow function). This measures the change in the value of the metric from the previous data point.

    To track a measurable value using two different metric types, use two metrics instead of one metric with two dimensions. For example, suppose you have a network_latency measurement that you want to send as two different types:

    • Gauge metric: Average network latency in milliseconds
    • Counter metric: Total number of latency values sent in an interval

    Send the measurement using two different metric names, such as network_latency.average and network_latency.count, instead of one metric name with two dimensions type:average and type:count.

  • Use a single consistent delimiter in metric names.

    Using a single consistent delimiter in metric names helps you search with wildcards.

    Use periods or underscores as delimiters. Don’t use colons or slashes.

  • Use names that others in your organization can identify and understand.

    Remember that you’re not the only person using the metric or dimension. Follow established conventions. To find out the conventions in your organization, browse your metrics using the Metric Finder.

  • Consider metric name, dimension name, and dimension value character limits.

    Metric and dimension length specifications:

    • Metric names up to 256 characters
    • Dimension names up to 128 characters
    • Dimension values up to 256 characters

    To ensure readability, keep names and values to 40 characters or less.

    See Criteria for metric and dimension names and values in the developer documentation for a complete list of requirements.

  • Avoid changing metric and dimension names.

    If you change a name, you have to update the charts and detectors that use the old name. Infrastructure Monitoring doesn’t do this automatically.

Custom event name requirements 🔗

Custom events are key-value pairs you can send to Infrastructure Monitoring to display in charts and view in event feeds. For example, you can send “release” events whenever you release new code and then correlate metric changes with releases by overlaying the release events on charts. To learn more, see View Additional Data with Events.

Metric and dimension key naming recommendations also apply generally to custom event naming.