Set a custom user agent

To ensure that New Relic correctly identifies API integration publishers, each integration needs a unique custom user agent string.

If you are only using your integration internally, and don't plan on sharing it with anyone outside your organization, you don't need to set a unique custom agent string.

Prerequisites

This document assumes you plan to publicly distribute an integration that makes use of any of New Relic's public RESTful APIs. Examples of public distribution include:

• Publicizing your integration code on Github.
• Packaging your integration into a plugin, extension, or other package, and distributing it via a directory like WordPress Plugins.
• Offering an "as a service" integration between your product and New Relic, without actually distributing your integration code, like Runscope's integration.

User agents

When writing applications to work with New Relic's RESTful APIs (referred to as an integration in this document), you are creating an HTTP agent to manage information exchange between your application and New Relic. An integration identifies itself by submitting a standard identification string. In HTTP this string is included in the header field User-Agent.

When using New Relic's RESTful APIs, set a User-Agent header that identifies your integration in API calls. This custom User-Agent string allows New Relic to identify the integration that is making requests to New Relic's APIs.

By setting a custom user agent, New Relic can track:

• Usage statistics for your integration.
• Potentially buggy or abusive API usage.

Set a user agent

To set a custom user agent, include an agent string in the HTTP header User-Agent.

Examples:

curl -H 'User-Agent: my-integration/1.2.3'

get.setHeader("User-Agent", "my-integration/1.2.3");

header('User-Agent: my-integration/1.2.3');

The minimum user agent string is the integration name and version: name/version. You can string together multiple values in a space-separated list. The full syntax is:

name/version [(comments)] [name/version [(comments)]] [...]​

For the integration name, use a string that clearly and meaningfully identifies your integration.

• Ambiguous name: New Relic Integration
• Clear and meaningful name: SaaS XYZTools Integration with New Relic

For the integration version, use a build ID, commit hash, or other identifier that is updated when you release new integration versions.

Wrap comments in parentheses () as a semi-colon separated list;

Helpful comments to include:

• The publicly-accessible URL of your integration. For instance, a Github URL, or a page in your docs site that describes the integration.
• Contact information so that New Relic can easily reach the integration publisher.

User agent strings and New Relic

New Relic captures user agent strings from API calls to identify their source.

Using custom user agent strings for publicly-available integration is a recommended best practice. Depending on your business relationship with New Relic, it may be required. Labeling your integration with a custom user agent string does not affect its interaction with New Relic's APIs.