newrelic_set_appname

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, license key (optional, for if you use multiple New Relic 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

New Relic highly recommends that you call this function as soon as possible and in as shallow of a call stack as possible. Applications are discrete entities in New Relic APM, and discontinuity of transaction traces is inherent to this method's usage. After connecting with the new app name, the new transactions start reporting to the new application without the context of the previous application or the data that has been reported to it.

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 value(s)

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

Example(s)

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 license key:

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);
    }
    ...
}

For more help

If you need more help, check out these support and learning resources: