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:

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:

Language Example
cURL
curl -H 'User-Agent: my-integration/1.2.3'
Java
(using GET)
get.setHeader("User-Agent", "my-integration/1.2.3");
PHP
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.

  • [icon-no] Ambiguous name: New Relic Integration
  • [icon-yes] 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.

Information from the user agent string will never be shared, nor used by New Relic for any purpose other than discussing the integration with its publisher.

Set custom user-agent for your integration

You have an integration with the following identifying information:

  • Name: MetricMeter
  • Version: 3.2
  • URL: meter.me/info
  • Contact: help​@​meter.me

The custom user agent string would be:

MetricMeter for New Relic/3.2 (meter.me/info; help​@​meter.me)

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.

For more help

Additional documentation resources include Getting started with the New Relic REST API (overview of setup, URL, API key, and payload, as well as examples and a demo).

Recommendations for learning more: