Usage dictionary

When someone signs up for New Relic, they get a New Relic organization (represented by an organization ID). That organization can contain one or more accounts (with each account having an account ID). For more about the distinction between organization and account, see Organization and account structure.

In general usage, outside of New Relic, account is often used in a more broad sense. For example, it might be used in the same way we use organization, or it might be used to refer to someone's user record. We should try to be as precise as possible when using these terms. This is especially true when we're documenting aspects that apply only to a New Relic account, and not to a New Relic organization (for example, account-level data and query limits).

That said, the more general the usage is, the more it's acceptable to use account as a synonym for organization. For example, New Relic sometimes uses a phrase like, "Sign up for a New Relic account." This substitution of account for organization is okay because it jibes with the way account is commonly used and is not referencing something specific to our definition of account.

A unique number that identifies a particular New Relic account. Don't use account number.

For the definition of agent, see the glossary.

Style guidelines:

• Don't capitalize: use the Ruby agent, not the Ruby Agent.
• Don't refer to a synthetics private minion as an agent.
• How agents relate to integrations: an integration is a connection between technologies. New Relic provides many types of integrations, which are linkages between various technologies and our platform. And some of those integrations require no additional software: for example, some of our integrations just require changing a setting in a service to send data to New Relic, or changing an endpoint to send data to New Relic. Agents, on the other hand, are pieces of software that enable one or more integrations. For example, our APM agents have integrations with various app frameworks and web servers and types of databases. One way to frame this is: "The integrations included with our agents are just some of our many integrations" or "Our agent-based integrations..."

Short for artificial intelligence for IT operations.

• Use the 12-hour clock followed by the (lowercased) time period am or pm.

• Don’t put a space after the last number in a timestamp (12:00am, not 12:00 am).

• Don't include a leading 0 when the hour is less than 10.

  9:30am, 12:30pm, 8:30pm

  コピー

• Generally referred to in conversation as AWS. Refer to Amazon Web Services in the first instance, then you may use AWS thereafter.
• Amazon has a number of products like Amazon EC2 and Amazon S3 that are almost always referred to by their abbreviated name, rather than the full name. You can abbreviate in the first instance if Amazon does.
• Some Amazon products use Amazon as the prefix (as in Amazon EC2), others AWS (as in AWS Amplify). Match the AWS docs site.
• Some Amazon product names also can be used in more informal ways to refer to data or configuration options. For example, for AWS Metric Streams, AWS formats that name in title case when referencing the product but, when referencing the data produced, they'll refer to it informally (for example, as metric stream data or metric streams). We should generally do what AWS does.

Don’t use ampersands in sentences or headings, unless they’re part of a company or brand name. Exception: If space is tight (meaning, “and” does not fit), it’s acceptable to use an ampersand.

The "machine name" that the collector uses to uniquely identify an app is its app name. The server-side configuration setting that changes the visible "name" of an app without changing its unique identifier is its app alias.

Use Microsoft Azure cloud computing platform naming conventions as prescribed by Microsoft; it’s what customers understand and recognize. For example, Azure Native New Relic Service.

Whether used as an adjective or a noun, this is one word. See also frontend.

Use standard prefixes and capitalization for International System of Units (SI), International Organization for Standardization (ISO), or Joint Electron Device Engineering Council (JEDEC memory) values when referring to multiples of bits (b) and bytes (B). 1 byte = 8 bits.

Don't use. Instead, use deny list and allow list; for example, "Add a hostname to your deny list."

When describing how one entity communicates or is connected to another, focus on the calls and which direction they’re going. For example, “service A calls service B,” “called services,” “calling services.”

Avoid using "upstream" and "downstream" to describe this.

This is more complex than can be covered in this usage dictionary. For detailed information, see:

• Heading capitalization
• Capitalization of features and UI elements

A parent account contains one or more child accounts. Child accounts were previously referred to as "sub-accounts".

In general, use click rather than the vaguer select. For example, you might click something in the UI, but then select something from a list.

Be particularly careful to use click to describe actions that only make sense with a mouse; for example, with a right click or a click and drag. Also use click when the user must click on a non-selectable object (to save your changes, click anywhere outside the dialog box). See also mouse over.

When referring to an agent talking to the New Relic servers, describe this as the New Relic collector. Although internally the collector refers only to specific parts of our architecture, we use it more broadly in our documentation to mean "any endpoint a customer must connect to report data, for any product." Avoid "connect to New Relic," and do not use "connect to the New Relic UI."

When it makes sense for clarity, conciseness, and tone and voice, use contractions. Use them where they make the writing sound more like natural speech, and where they improve clarity and accessibility without sacrificing expertise and authority.

There are no hard and fast rules for which contractions are or aren't acceptable, but simple and common is preferable to complicated and rare. For example, it's for it is is fine, but less common constructions like mustn't or wouldn't've are best avoided.

Also:

• When using a negative contraction (don't, can't, won't) try to provide some additional info about what what to do and what can be done. (See the style guide intro for more on this.)
• There are places in our docs—for example, in notes and warnings—where spelling out do not, cannot, or will not is preferable to contractions to emphasize the action or blockage to be avoided.

When possible, use the second person you to form a sense of connection with the reader. For times when you need a descriptive third-person noun, keep the following guidelines in mind:

• customer and user are both appropriate depending on context.
• customer makes more sense when talking about billing, or about a group of people or a business entity. For example, one customer may have one or more individual users who interact with New Relic through the customer's account(s).
• user makes more sense as a general term for an individual user, or when talking about users as an object in the account model. For example, when discussing account models, it's important to be specific about what constitutes a single person identity in our system.

From a general industry standpoint, dashboard usually refers to one or more charts or other widgets on a screen. You can see this general definition in the Wikipedia entry for dashboard.

At New Relic, we use the term dashboard a couple different ways:

• Dashboards refer to a New Relic feature called New Relic dashboards, as seen on its feature page. In this context, New Relic dashboards refers to the ability to create and use customized views that are not built into our core platform experiences (for example, the UI for APM, browser monitoring, OpenTelemetry, and others). These custom dashboards are found on the Dashboards UI page.
• Dashboards can also refer to curated dashboards. These dashboards are default views that customers get when they use our core platform solutions (for example, the UI experiences for APM, infrastructure, and browser monitoring).

Our customized dashboards include dashboards found in New Relic apps, and in quickstarts on our Instant Observability page. For example, if you look at the .NET quickstart, you see that it comes with one extra dashboard that is not part of our curated experience.

If you think there's ambiguity when using the general term 'dashboard', then we recommend the following usage:

• To refer to custom experiences found in nerdpacks, quickstarts, or dashboards made by a customer or their team, use custom dashboards, or customizable dashboards, or quickstart dashboards.
• To refer to our more curated views, use curated views, curated dashboards, New Relic-built dashboards, APM dashboards, APM views (to give a few ideas).

Really, we recommend being as specific as possible to establish context. If a piece of writing has established that context once, then feel free to use the general dashboard.

When referring to a data sheet, separate into two words so it reads data sheet and not datasheet.

Short for software developers and operations.

If you need to refer to the docs themselves—don't. Generally it's better to directly link to the doc you're referencing and use the doc title as your link text. For example, See [Install the .NET agent](URL) rather than See our [.NET agent install docs](URL).

If there's not a good alternative, doc generally sounds more natural than document or documentation. If you're tempted to use a longer form, try reading it aloud to see which reads best.

If you must refer to the site as a whole, call it the docs site rather than Docs site or documentation site. Internally, you can also refer to the whole URL docs.newrelic.com to avoid ambiguity with other sources of docs like internal platform docs or API explorer docs. To refer to our docs GitHub repo, use the repo name docs-website or the repo path newrelic/docs-website.

Don't use to describe how entities relate to each other. How people interpret downstream and upstream varies significantly, so focus on the specific type of connection as we do in the related entities element: calls, creates, hosts, maintains, etc.

Examples: [Service A] calls [service B] Called services Calling services maintained by [repository name]

Use dropdown instead of drop-down or drop down.

Although it isn't common usage, you can use dropdown independently as a noun, without needing to say dropdown menu or dropdown list. For example, select a date from the <b>date</b> dropdown.

Avoid these Latin abbreviations.

Instead of e.g., use for example or such as. Subbing for i.e. is tricker, because sometimes people use it to mean that is, while at other times it's mis-used to mean for example. Read the context to be clear, but usually the best solution is to rewrite so the description is clear without needing explanatory text.

In quoted material, use an ellipsis to indicate omitted text. Treat an ellipsis as a unique character without space between the three periods. For example, stylize an ellipses as (...) but not (. . .) When an ellipses appears between two complete sentences, use terminal punctuation at the end of the first sentence, then follow with an ellipses. For example:

“Security is important to us at New Relic. ... We hold ourselves to high standards, maintaining several certifications, including ISO 27001 and FedRAMP.”

Note that a space precedes and follows the ellipsis.

Em dashes are rarely needed in tech docs, sadly. You can usually accomplish what you need to by breaking the thought into multiple sentences or using parentheses. In some rare cases, though, an em dash can add drama and spice.

If you think you've found such a case, make sure you use them right. An em dash should always use the real em dash character (not a hyphen), and no space before and after. For example:

You can sign up for New Relic fast and free—we won't even ask for a credit card number.

You can insert an em dash with the COMMAND+OPTION+- shortcut or use the HTML entity.

Unlike the Latin abbreviations e.g. or i.e., you're welcome to use etc. It should have a period at the end (etc.). Ensure that you have several meaningful examples, though, before using it. For example, cities including Portland, Seattle, Dublin, etc. but not cities including Portland, etc..

To understand how to optimally write about events, we recommend reading:

• The event section in the data types doc

• The glossary entry for "event"

  Some language-related considerations when writing about events:

• It's important to understand some of the ambiguity and history around how we sometimes use the word "event." Prior to the roll-out of our three other core data types of Metric, Log, and Span, at New Relic we referred to all NRDB-stored objects as "events." For this reason, internally and sometimes externally we still sometimes refer to all NRDB objects as "events." (For example, in the query UI, we still use "events inspected" and this refers to all NRDB data types). But for public-facing resources, we should attempt to use "event" to refer to NRDB-stored data that is not Metric, Log, or Span data types.

• It's important to understand how the concept of "event" can overlap with the concept of "metric." Both are broad general terms and due to that there can be some overlap in meaning. Because metrics are just measurements, all New Relic data (events, spans, logs) can be said to be or contain metrics. For example, the events reported by our infrastructure monitoring contain various metrics, which are simply numeric measurements of various kinds (read more about infrastructure events containing metrics).

E words are words that use e as a shorthand for electronic, like ebook, ecommerce, email, or esports. Treat e words like common nouns that follow sentence case. Do not hyphenate e words.

Whether used as an adjective or a noun, this is one word. See also backend.

Spell out: generative AI. When space does not permit, GenAI is acceptable. Generative AI is an application of machine learning that can create a variety of content, including as text, images, or audio from natural language prompts.

Two words, not one.

This is one word. Don't hyphenate.

When using an inline icon from the UI, always describe it first, then embed the icon image, and then end with the word icon.

For example, select the delete icon.

Don't put icons in bold.

When writing about icons, describe the icon for its purpose or action, not what the icon looks like. For example:

• Yes: Select the edit icon.

• No: Select the pencil icon.

  For technical information on embedding images, see Inserting inline images and Embedding Font Awesome icons.

A list of entities, such as the APM applications index, the synthetic monitor index, or the alerts incidents index. See also page.

Short for information security.

Short for infrastructure and operations.

Avoid using generically, to avoid confusion with infrastructure monitoring.

Instead, use an appropriate substitute such as architecture, environment, system, host, etc.

For a definition of "integration," see the glossary. For an explanation of how the concept of "integration" relates to the concept of "agent," see the usage dictionary entry for agent.

Always use Introduction to for overview docs for a particular product. For example, Introduction to New Relic Infrastructure or Introduction to the PHP agent or Introduction to transaction traces.

Don't use welcome to, basics, intro, overview, etc.

Also avoid the Thing: Tagline format, as in X-Ray sessions: Traces and thread profiles for key transactions, unless having a title with keywords will help with SEO.

Camel-case (JavaScript), not Javascript or JS.

Don't use. Instead, use original.

One word.

The proper name for Apple's desktop operating system is macOS.

Don't use the older product names Mac OS, Mac OS X, or OS X.

Avoid and/or replace the use of "master" whenever possible. For example, use "main" for root branches in GitHub instead.

We previously used master account and sub-account but now we use parent account and child account.

The list of pages and indexes on the top and left sides of the New Relic user interface.

For an explanation of how the word "metric" is used in the industry and how it's used at New Relic, see Data types.

Some tips about some often confusing aspects of metric data:

• Note that the word "metrics" is a broad, general concept and at New Relic we have a number of data types and data-reporting methods that are called "metrics".

• The best metric data format is dimensional metric data, aka the Metric data type. That data is reported via the Metric API. This is the "metric" data that we are primarily referring to when we talk about the "metrics" in our four core "MELT" data types: metrics, events, logs, and traces.

• Our original metric data format is called metric timeslice data. This is still reported by APM, browser monitoring, and mobile monitoring. This was a very simple form of metric data and was not stored in NRDB, so it could not be queried in NRQL. Currently APM metric timeslice data is mirrored in NRDB and so can be queried via NRQL.

  Some style-related recommendations:

• Err on the side of talking about "metrics" generally and not going into detail about the data structure and reporting process. In general, whether talking about dimensional metrics (the Metric data type) or metric timeslice data or metrics reported as infrastructure event attributes, you can simply use "metrics" or "metric data." It's thought that in most cases in docs and UI, a customer won't often need to know exactly what type of data it is. But if it's thought that it would be helpful to know the type of data (for example, when talking about how to query that data), you can give more detail about the type of data.

• When you want to clarify the type of metric data in a simple way, you can link to a specific metric data type collapser in this section. For example, you might do something like this: "This integration reports metric data."

Refers to for machine learning operations, which lets you automate deployment at-scale. Our model performance monitoring lets you monitor your MLOps with our applied intelligence solution.

For mouse movements that involve placing the mouse pointer over an area, but not clicking it. For example, the APM Overview page includes functions that are only visible when the mouse pointer is over a particular chart. Do not use point to or hover over. See also click.

Use New to refer to a feature or capability that has recently been released to the general public (GA). In the UI, use the badge component to label new features or capabilities.

Use Preview to refer to features and capabilities that are pre-GA but are available to select users and sometimes more broadly. These features or capabilities are usually not complete. Previews enable us to gather initial user feedback as we work towards general availability.

For either term, in the UI, use the badge component in spots like these:

• the left-hand navigation
• the tile on the All Capabilities page
• the page title

Use lowercase for all URLs, New Relic and external alike. For example, newrelic.com, github.com, and cncf.io.

Always refer to the agent and language as .NET, never as .Net or .net or dotnet.

We generally refer to the programming language as Node.js, not Node. For example, Node.js agent not Node agent.

Be careful, though, because unfortunately, the Node.js community is wildly inconsistent on this point. There are two key tools whose unabbreviated names say Node instead of Node.js: nvm stands for Node Version Manager, and npm stands for Node Package Manager. On the rare occasions you need to expand the acronym, follow the official naming.

Note also that node itself is a wildly overloaded term in computing, so that for example Kubernetes has nodes that have nothing to do with the programming language.

Don't hyphenate when using as a noun; hyphenate when using as a compound adjective.

See account.

See serial comma.

Use lower case for open source. Some legal contracts may require upper case.

Use instead of "legacy" to refer to the first or previous versions of products, features, and capabilities that might still be in use. "Original" conveys the viability and ongoing support of the feature, while the word "legacy" can erroneously convey that a feature is no longer supported.

A specific place in the New Relic UI, located at a particular URL. Compare and contrast index, menu, and UI. Don't use dashboard, menu, tab, screen, or similar terms.

Two words, not one.

New Relic organizations can have a parent/child account structure. This is more important for our original user model but still plays a role for some behind-the-scenes features on our newer user model. Learn more about account structure.

Parent accounts were previously referred to as master accounts, and there are still some uses of this in the codebase.

See User-related language.

For pricing tier/edition language, see Pricing language.

Docs use the preview callout for features in preview. In the body text, use lowercase. For example:

If the developer team prefers to use a term other than preview, clarify what is driving that use of the term (Legal requirement?), and add any relevant info here in the usage dictionary.

See Pricing language.

See our glossary entry for quickstart. Note that not everything we offer is a quickstart. The quickstart term should be reserved for the Install now install routes on the Instant Observability page entries, and shouldn't be used to refer to the installation or setup of agents and integrations that don't follow that quickstart route.

Don't use this outside of browser monitoring docs. Often abbreviated as RUM, this is a generic industry term for browser monitoring. New Relic usually refers to this as page load timing or browser monitoring. Use this term only for SEO or clarification, not to refer to the actual feature.

Use report when discussing data sent to New Relic, such as, "your host reports data to New Relic."

Avoid using report as a noun. Instead use "the reported metrics" or "the collected data."

If "report" sounds too clunky, you can also use collect as long as whatever New Relic is collecting doesn't sound security sensitive.

One word. For example, You won't want to miss the upcoming FutureStack roadshow!

Don't refer to the New Relic UI as RPM. Always refer to the specific product, such as the APM UI or the Browser UI. However, you may use rpm when required in the visible URL string in UI paths.

Also referred to as an Oxford comma. Always use serial commas with inline lists. For example, Portland, Seattle, and Dublin rather than Portland, Seattle and Dublin.

When referring to a skill set, separate into two words so it reads skill set and not skillset.

See Punctuation # Slashes.

Include a space (time zone). Don't hyphenate or run together as timezone.

The graphical component of a New Relic product, encompassing all its pages, menus, and indexes. See also UI paths.

If you need to tell a user how to path through the UI, see our style guide page on UI paths.

Use update when users need to change the version of whatever they're using. No money or payment is needed for an update.

Use upgrade whenever money or payment may be involved, such as upgrading to the Pro version of a product. The new pricing model makes it unlikely that you'll need to use this.

For styles and formats related to user roles and groups and more, see User-related style.

One word (username), not two. This is the most common usage and is recommended by Microsoft and Google style guides.

When referring to multiple version numbers, use or higher or or lower. Don't use and higher (it's more ambiguous than or), or the words greater or later. Also don't use punctuation, as in version 1.2+ or <version 1.2. Avoid 1.2.X style references, and instead use the exact version numbers. For example:

Foo requires Ruby agent version 1.2.3 or higher

Bar is compatible with ActiveMerchant version 4.5.6 or lower

You'll find that both version and versions work depending on the context; try reading it aloud if you're unsure.

Other usage notes:

• Tell users to use the latest version and not an up-to-date or current version.
• To abbreviate the word version, use a lowercase v with no space before the number; for example, v2 or v1.2.3.
• Use update not upgrade when talking about agent versions, as in "To update to the latest version..."
• Consider using in earlier agent versions when referring to versions more vaguely.

Say we and our when it works with the flow of your writing. Avoid overloading paragraphs with New Relic mentions, or reword so the focus is on the user, not New Relic. For example, avoid writing something like this:

New Relic recommends setting a startup timeout.

Instead, write something like this:

Recommendation: To help with troubleshooting, include a startup timeout in your configuration.

OR

We recommend setting a startup timeout.

Two words, not one.

Use a lowercase x to signify "times." For example:

• Cloud adoption can increase the number of hosts 2–50x.
• Up to 10x the max duration per query and 3x the max query limit.

We use you and your liberally in our docs. Addressing the reader directly makes for simpler, cleaner sentences. It also tends to expose lazy uses of passive construction and it helps users to understand procedures.