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, license key (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

function newrelic_set_appname(string $name) : bool

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

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