• EnglishEspañol日本語한국어Português
  • Log inStart now

newrelic_set_appname (PHP agent API)

Syntax

newrelic_set_appname(string $name)
newrelic_set_appname(string $name, string $license[, bool $xmit])

Sets the New Relic app name, which controls data rollup.

Requirements

Agent version 3.1.5.111 or higher.

Description

Set the New Relic application name, which the New Relic UI uses to connect your data to the correct application.

The recommended and preferred method for setting the New Relic application name is to use global or per-directory INI settings to associate your application to the desired name at the start of execution.

If you cannot edit your agent config file (for example, many shared hosting environments do not allow you to edit config files), the newrelic_set_appname API call can be used to configure app name, (optional, for if you use multiple accounts), and a true/false flag (optional, to determine whether to keep or discard previously recorded data). To ensure maximal APM trace continuity, call this as early as possible. This API call will discard all current transaction data and start a new transaction after it has reconnected with the given app name.

For other app-naming options, see Name your PHP application. When possible, INI-based solutions are recommended.

Call and location behavior

We highly recommend that you call this function as soon as possible after you start monitoring your app and in as shallow of a call stack as possible. Applications are discrete entities in APM, and when you change an app's name, there's nothing to tie the data of the two app names together. Using the newrelic_set_appname function can lead to a discontinuity of your transaction traces. In other words, new transactions are reported to the new app name and there's nothing to tie them to the data connected to the old app name.

This method is intended to be called once, as each call to the API (even with the same app name) will cause the current transaction data to be discarded and lead to further discontinuity of transaction traces.

Parameters

Parameter

Description

function newrelic_set_appname(string $name) : bool

$name

string

Required. Name(s) of app metrics should be reported under in New Relic user interface. Uses the same format as newrelic.appname and can set multiple application names by separating each with a semicolon ;.

function newrelic_set_appname(string $name, string $license, bool $xmit) : bool

$name

string

Required. Name(s) of app metrics should be reported under in New Relic user interface. Uses the same format as newrelic.appname and can set multiple application names by separating each with a semi-colon ;.

$license

string

Required (can be empty string). Specify a different license key to report metrics to a different New Relic account. If set to empty string, defaults to license key in the agent's newrelic.ini file.

$xmit

boolean

Optional. Defaults to false.

If false or omitted, the agent discards the current transaction and all data captured up to this call is lost.

If true, the agent sends the data that was gathered right before executing this call. The data is associated with the old app name. This has a very slight performance impact as it takes a few milliseconds for the agent to dump its data.

Return values

Returns true if the application name was successfully changed, or false otherwise.

Examples

Set a single app name

function example() {
if (extension_loaded('newrelic')) { // Ensure PHP agent is available
newrelic_set_appname("App1");
}
...
}

Set two app names

This example sets multiple app names:

function example() {
if (extension_loaded('newrelic')) { // Ensure PHP agent is available
newrelic_set_appname("App1;App2");
}
...
}

Set app name and license key

function example() {
if (extension_loaded('newrelic')) { // Ensure PHP agent is available
newrelic_set_appname("App1", "01234567890abcde01234567890abcde01234567890");
}
...
}

Set app name and keep previous data

This example sets an app name and keeps the existing data, but doesn't change the :

function example() {
if (extension_loaded('newrelic')) { // Ensure PHP agent is available
newrelic_set_appname("App1", "", true);
}
...
}

Set app name and license key, and keep previous data

This example sets the app name and license key, and keeps the existing data:

function example() {
if (extension_loaded('newrelic')) { // Ensure PHP agent is available
newrelic_set_appname("App1", "01234567890abcde01234567890abcde01234567890", true);
}
...
}
Copyright © 2024 New Relic Inc.

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