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.

To add syntax highlighting to a code block, insert the language name on the same line as the first three backtacks. Here's an example using some Java code:

This is what the formatting looks like when it's published:

public class SampleTester {

    private String configName;
    private Map<String, Long> maxSampleTimes;

    public SampleTester(String pConfigName) {
        configName = pConfigName;
        maxSampleTimes = new HashMap<>();
    }

Check in gatsby-config.js to see if the language you want to format is already set up in Gatsby. The list of currently supported languages appears under prism:

prism: {
        languages: [
          'xml',
          'xml-doc',
          'c',
          'go',
          'handlebars',
          'java',
          'php',
          'phpdoc',
          'csharp',
          'python',
        ],
      },

To add formatting support for a language that isn't listed, create a pull request where you add the language to the list in gatsby-config.js.

Highlight user input with `<var>`

The <var> tag is used to highlight areas the user needs to customize the value in a code snippet.

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.

echo "license_key: YOUR_LICENSE_KEY" | sudo tee -a /etc/newrelic-infra.yml

PATH/TO/SOMETHING.exe

msiexec.exe /qn /i PATH\TO\newrelic-infra.msi

Annotate code with `<mark>`

Use the <mark> tag to highlight areas of a code block that are particularly important. Most commonly, <mark> 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.

When you use <mark>, 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.

private void storeItem(long id) {
    Segment segment = NewRelic.getAgent().getTransaction(). startSegment("storeItem");

      segment.reportAsExternal(DatastoreParameters
              .product("H2")
              .collection(null)
              .operation("insert")
              .instance("localhost", 8080)
              .databaseName("test")
              .build());

      // fire and forget
      DB_POOL.submit(() -> {
          segment.end();
          insertData(id);
      });
  }

The agent API calls in this sample are:

startSegment(...): Begins the segment that will time the code. For method syntax, see the Javadoc.
reportAsExternal(DatastoreParameters()): Associates the time with a datastore external call This will show up in APM with datastore data. For more information, see reportAsExternal API. For method syntax, see the Javadoc.
segment.end(): Stops timing this segment. For method syntax, see the Javadoc.

When to use code formatting

Inline code formatting

Multi-line code blocks

Syntax highlighting example

Adding language support for syntax highlighting

Highlight user input with `<var>`

Examples of using the <var> tag

Annotate code with `<mark>`

Example of using the <mark> tag

Code references

When to use code formatting

Inline code formatting

Multi-line code blocks

Adding language support for syntax highlighting

Highlight user input with <var>

Examples of using the <var> tag

Annotate code with <mark>

Example of using the <mark> tag

Highlight user input with `<var>`

Annotate code with `<mark>`