Docs » Reference » Best Practices » Naming Conventions

Naming Conventions 🔗

If you are using an existing integration such as the SignalFx collectd agent or the AWS CloudWatch metrics importer, the names of the metrics, dimensions and events have already been chosen. For more information, see Integrations Guide and Integrations Reference.

On the other hand, if you plan to send custom metrics, dimensions or events to SignalFx, then you need to decide on their names and structure so that you can make them easy to find, view and analyze. Changing metric names after you start sending them is not advised, as any charts or detectors making use of the old metric name will need to be updated to use the new metric name.

In addition, if you are sending metrics that have previously been sent into other metrics systems like Graphite, you may want to consider modifying the naming structure so that you can take full advantage of SignalFx.

Naming custom metrics and dimensions 🔗

SignalFx metric datapoints are composed of a metric type, a metric name, a metric value, and zero or more dimensions. For more information, read up on the SignalFx metric data model.

For specific criteria and limitations on metric and dimension names and values (such as maximum length or acceptable characters), see Criteria for metric and dimension names and values in the SignalFx API documentation.

The discussion below discusses naming guidelines from a higher-level perspective.

  • Do not use timestamps in metric names.

    Using timestamps in the metric name can cause the data not to be ingested.

  • Separate out dimensions from metric names.

    Metrics represent distinct or concrete things that you are measuring or instrumenting (e.g. GET requests, memory utilization, response time) while dimensions typically represent metadata associated with that metric (e.g. service name, availability zone, request type) that are useful in filtering or aggregating metrics.

    SignalFx allows you to associate arbitrary key-value pairs with metrics, and to find the metric time series you want through any combination of metrics and dimensions. As a result, multi-dimensional data can be represented in SignalFx without overloading the metric name. Other benefits of separating them out include shorter, more readable metric names and superior filtering and aggregation functionality.

    Although the SignalFx UI provides significant accommodations for using long, dot- or slash-separated metric names (as is common for Graphite, StatsD, New Relic etc.), some of our most popular features, e.g. dashboard variables or the Infrastructure Navigator, require the use of dimensions. If you have an existing body of metrics with dot-separated names, we recommend that you use the SignalFx Gateway (formerly called the metric proxy) to parse out dimensions.

  • Structure metric names hierarchically from left to right.

    Start with the domain or namespace that the metric belongs to, followed by the thing that is being measured, and ending with the unit of measurement. For example, at SignalFx we have the following metrics coming from our analytics service:

    • analytics.jobs.total, a gauge periodically measuring the current number of jobs executing
    • analytics.thrift.execute.count, a counter incrementing every time a new job is executed
    • analytics.thrift.execute.time, a gauge measuring the time it took to process a job execution request
    • analytics.jobs_by_state, a counter with a state dimension, incremented every time a job reaches a given state.

    For all these metrics, we report under a hostname-based dimension (analytics-1, analytics-2, …), and under a customer-based dimension (org-x, org-y, …), which give us an infrastructure-focused or a customer-focused view of the usage of our analytics service, respectively.

  • Do not send metric types as a dimension.

    In the SignalFx data model, a metric (identified by its name) is associated with a single metric type, and each metric type is rolled up in a specific way: gauges are averaged, counters are summed, and so on. Although it is possible to use a dimension to represent a metric type, doing so is likely to lead to erroneous data for longer time ranges, and we strongly recommend against it.

    For example, if you have a metric foo for which you want to send in both a gauge (say, its average of all of foo’s values sent in during a 10-second interval) and a counter (e.g. the number of such values sent in, during the same interval), you should send them in using two metric names, foo.average and foo.count, rather than sending in foo with a dimension type:average and type:count.

  • Use a single, consistent delimiter within the metric name to make wildcard queries simpler.

    Common delimiters are periods or underscores. Colons and slashes can be made to work, but are not recommended.

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

    Remember that you may not be the only person using the metric or dimension. If naming and structuring conventions have already been established, follow them. To get a sense for how metrics and dimensions are named in your environment, browse through your metrics using the Metric Finder.

  • Consider character limits.

    Individual metric names and dimension values of up to 256 characters can be stored correctly in our service; dimension names up to 128 characters are supported. However, these names and values stop being readable or usable well before those limits are reached. Forty or fewer characters is a good rule of thumb.

Naming custom events 🔗

Custom events are sets of keys and values which can be sent to SignalFx and overlaid on charts and viewed in event feeds. For example, by sending “release” events whenever new code is released, you can visually correlate metric changes with releases by overlaying the release events on charts. For more information, see View Additional Data with Events.

From a data model perspective, events are very similar to metrics, and therefore the recommendations above apply equally well.