• ログイン今すぐ開始

Code references

We use a variety of formatting to highlight code or other technical language.

When to use code formatting

The following table provides some examples of our use of code format.

For this...

Why use code?

Example

File paths and file names

Using code helps paths and file names stand out, and ensures clarity about the exact file name.

The agent looks for newrelic.config in the %ALLUSERSPROFILE%\New Relic\.NET Agent directory.

NRDB event names and attributes

Many attribute names (such as duration) look like ordinary English words. Formatting them as code helps clarify that we're talking about a specific data point.

To analyze APM errors, use the TransactionError event.

Method names

Using code formatting for method names is standard practice.

To initialize the APM agent, use startAgent().

URLs you don't intend to be clicked

Using code formatting hints to the user that they may need to customize or tweak the URL to ensure it works for them.

In your web browser, navigate to the minion Overview page at http://MINION_IP_ADDRESS.

Command line utility names

If you think a reader or translator might confuse a command with a general English word, use code.

  • curl: Sends http requests via a terminal session–not to be confused with the curls you do with weights at the gym.
  • cat: Lists the first ten lines of a file–not a feline pet who ignores you.
  • date: Displays the day, year, and time–not an outing that couples take.
  • tail: Displays the last ten lines of a file–not the appendage on various mammals.
  • which: Show the location of a program executable–not the pronoun.

To install the utility, use apt.

Inline code formatting

To format inline code (like maxSampleTimes or TransactionError), surround the text with backtick ` characters.

Multi-line code blocks

To format one or more lines of code, insert three backticks ( ``` ) above and below your code. This essentially acts like the HTML <pre> tag.

Highlight user input with <var>

The <var> tag is used to highlight areas the user needs to customize the value in a code snippet. For example: you might use <var>YOUR_ACCOUNT_ID</var> to draw a user's attention to a place they'll need to input their account ID.

Follow these guidelines when you use <var> tags:

  • Address the reader directly (YOUR_CONFIG_FILE not CONFIG_FILE).
  • Use all caps and underscores _ to separate words (also known as SCREAMING_SNAKE_CASE).
  • Don't combine them with other punctuation to indicate variables (such as wrapping the text in angle brackets or curly braces).
  • Don't overuse them. For example, if you're showing a complete config file where the user is expected to customize many values, a <var> tag on each configurable value is overkill.
  • Highlight areas of a code block that are particularly important but not directly procedural-related. Most commonly, <var> is used to highlight New Relic API methods in sample code that contains a lot of "other logic." They're also handy when you want to indicate a bit of code that will be referenced later in a procedure or doc. Examples:
    • Highlighting values in code response that are meant for later use: Activate Azure integrations doc.
    • Highlighting the commands in a large code block example that are New Relic-specific commands, with explanations below: Java API doc.

When you use <var>, you should usually follow the code block with a list of bullets that explain what each API call is doing and link to method syntax.

Do not use a <var> tag for:

  • Example code: If the code is meant to be an example, to show the format of the code, and there is not an actual procedure the customer is following, var tags are not needed. A couple reasons for this: 1) The important part of showing an example config file is to show the overall structure of the file, 2) Usually the number of config options present in a file will vary based on whatever the customer wishes to use, so using <var> tags can actually be confusing as it implies that these values must be present. Examples:
    • Example configuration file (or this Java agent config template): if you are showing an example config file that isn't part of a procedure, you shouldn't use the <var> tag.
    • Instrumentation procedure (at bottom of the Java section): the var tag wouldn't be necessary because it's an example, not part of a procedure, and the main goal is seeing the general structure. Also, because it's an example of app code, the concept of user-specific values doesn't have much meaning, because the entire code will vary dependent on how the customer has written their code. (If anything, this would be a potential for using <var> format to emphasize the New Relic functions.)
  • Response/output code: If the code is meant to show an expected return, and is not related to a procedure, then var tags shouldn't be used. Here's a doc section (the returned JSON) where var tags are not needed.

For some use cases, highlighting may be a better choice than a var tag.

Copyright © 2022 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.