• /
  • Log in
  • Free account

Add to data dictionary

We use the data dictionary to provide information about data types (for example, Transaction, Metric, Log) and attached attributes. This is exposed in the New Relic query experience, on hovering over the data types and attributes. And we also expose the dictionary to the public. This doc contains info on how to add data to the dictionary.

Note that currently we don't have infrastructure integration data in the dictionary. We also have very few attributes for the Metric data type, just a few basic default ones, despite there being many potential attributes attached to that data type depending on what the data source is.

Data dictionary structure

The data in the data dictionary is structured like this:

  • Data types: sometimes called "events" for historical reasons, these are the NRDB data objects, like Transaction, Metric, Log, Span, etc.
  • Attributes: these are key:value pairs attached to data types. One attribute can have multiple data types listed for it. For example, appName is on multiple data types.
  • Data source: The New Relic product from which the data originates. With the current implementation, a data type must have a single data source assigned. This isn't ideal, as theoretically a data type can come from multiple sources.

General style approaches

When creating new data types or attributes, copy the existing styles and approaches for existing ones. Try to give customer-friendly descriptions that help them make sense of the data but are also succinct.

Short and long descriptions

You can use sentence fragments in attribute definitions. If an attribute description can't be succinct and needs more detail, put a short description in the main description field and a longer description in the Long description field.

Formatting options

There is no styling available in an attribute definitions, so try to work around that as best you can. For example, data types are okay without styling as they are capitalized, and some uses of attribute names and values can be clear without styling.

When you need to style something for clarity you can use single quotes, as in this example definition: Reported when 'category' is 'http'.

Context-specific attributes

Some attributes are only present in some cases, for example:

  • When a specific APM agent is being used
  • When a specific config option is set to true
  • When another attribute has a specific value

If it's easy to include that information in the short description, do so. But it's not required. As long as the attribute definition is accurate, any details about when it shows up can be considered optional.

Add a new data type

To add a new data type:

  1. Make a new folder in this directory, alongside the other directories:
  2. Duplicate a data type file (for example, this Metric data type), place it in the new folder, and fill it out with the new info.
  3. For how to add attributes on a new data type, keep reading.

Add attributes

To add attributes:

  1. Check if there's an existing attribute that has the same name and same definition as the one you're trying to add. If it exists, edit that file to include the new data type.
  2. If there is no existing attribute, copy an existing attribute file (for example, this one), edit all relevant fields to be accurate, and place it in the folder of a data type it's attached to (for example, Transaction).

How to set unit of measurement

Attribute entries have an optional unit of measurement field. What unit of measurement to select for an attribute is sometimes obvious, like if the attribute value is measured in milliseconds or seconds, or a percentage.

We use several units of measurement that are not obvious, though, like count, enum, rate, and ID. (Technically, these aren't actually "units of measurement" and are more just conceptual data types but we're doing it this way as a workaround so you can ignore the fact that units of measurement isn't actually accurate.)

The main reason we want to specify this information is that this will control what kinds of queries or charts can be created or auto-suggested by New Relic. For example, the New Relic UI wouldn't want to auto-suggest a chart graphing the average of ID values because that wouldn't make any sense. So attributes with accurate units, such as data types, will help product provide more practical help/suggestions to customers in future.

Here are definitions and tips for using these "non-obvious" units of measurement:

  • Count: This is a count of something, though not a count of time-based units. For a number to be a count, it must (a) only be capable of increasing during a given time/sampling period, and (b) have a theoretically uncapped range. This wouldn't be used for a count of time units; if it was a count of seconds, for example, you would just use 'seconds' as the unit of measurement. A couple of examples of a count:
  • Enum: enum is short for enumerated list. In other words, it is a specific range of numbers that represent other non-numeric elements. For example, an attribute that had HTTP error codes (404, 505, etc.) as possible values would be an enum. A range of numbers that represent color codes would be another example of an enum. (Theoretically, an enum can represent lists without numeric values but we have no need to categorize strings so we only care about numeric-value lists.) Example: httpResponsecode.
  • Rate: Use this for any rate (for example, count per second). These are typically for averaged rates over small units of time, like second or millisecond. We previously have used the unit of time for these attributes (for example, using seconds as the unit of measurement for a count per second rate), but now we want to use rate for these. This is necessary because the types of displays used for rates would be different than the types of displays used for a simpler duration/count measurement. Example: MySQL integration attribute db.innodb.dataReadBytesPerSecond, which has the definition "Rate at which data is read from InnoDB tables in bytes per second."
  • ID: Use ID for any identification number attribute. Example: appId.

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.