PHP agent API

The agent provides a number of extra PHP API calls which you can add to your application to fine-tune New Relic.

Enclose these API calls in a conditional check for the New Relic PHP agent so that your code will work with and without the agent present.

For example:

if (extension_loaded('newrelic')) {
  newrelic_set_appname($name);
}

The API calls you can use in your scripts are:

newrelic_add_custom_parameter (key, value)

Before creating custom attributes, review New Relic's list of reserved terms used by NRQL and Insights. Otherwise unexpected results may occur.

function newrelic_add_custom_parameter (string $key, scalar $value): bool

Add a custom parameter to the current web transaction with the specified value. For example, you can add a customer's full name from your customer database. This parameter appears in any transaction trace that results from this transaction.

If the value given is a float with a value of NaN, Infinity, denorm or negative zero, the behavior of this function is undefined. For other floating point values, New Relic may discard 1 or more bits of precision (ULPs) from the given value.

This function will return true if the parameter was added successfully.

String values will be truncated to 255 characters.

newrelic_add_custom_tracer (function_name)
function newrelic_add_custom_tracer (string $function_name): bool

API equivalent of the newrelic.transaction_tracer.custom setting. It allows you to add user-defined functions or methods to the list to be instrumented. Internal PHP functions cannot have custom tracing.

The function_name can be formatted either as "function_name" for procedural functions, or as "ClassName::method" for methods. Both static and instance methods will be instrumented if the method syntax is used.

This function will return true if the tracer was added successfully.

newrelic_background_job ( [flag] )
function newrelic_background_job (bool $flag = true): null

If the flag argument is set to true or omitted, the current transaction is marked as a background job. If flag is set to false, then the transaction is marked as a web transaction.

newrelic_capture_params ( [enable] )
function newrelic_capture_params (bool $enable = true): null

If enable is omitted or set to true, this enables the capturing of URL parameters for displaying in transaction traces. This will override the newrelic.capture_params setting.

Note: Until version 2.1.3 of the PHP agent, this function was called newrelic_enable_params. Although this alias still exists, it is deprecated and will be removed in the future.

newrelic_custom_metric (metric_name, value)

Avoid creating too many unique custom metric names. New Relic limits the total number of custom metrics you can use (not the total you can report for each of these custom metrics). Exceeding more than 2000 unique custom metric names can cause automatic clamps that will affect other data.

function newrelic_custom_metric (string $metric_name, float $value): bool

Adds a custom metric with the specified name and value, which is of type double. Values saved are assumed to be milliseconds, so "4" will be stored as ".004" in our system. If the value is NaN, Infinity, denorm or negative zero, the behavior of this function is undefined. New Relic may discard 1 or more bits of precision (ULPs) from the given value.

Name your custom metrics with a Custom/ prefix (for example, Custom/MyMetric). This will make them easily usable in custom dashboards.

Use the Metric Explorer in Insights to search for your custom metrics, create customizable charts, and add them to Insights dashboards.

This function will return true if the metric was added successfully.

newrelic_disable_autorum ( )
function newrelic_disable_autorum (): bool

Prevents the output filter from attempting to insert the JavaScript for page load timing (sometimes referred to as real user monitoring or RUM) for this current transaction.

This function will always return true.

newrelic_end_of_transaction ( )
function newrelic_end_of_transaction (): null

Stop recording the web transaction immediately. Usually used when a page is done with all computation and is about to stream data (file download, audio or video streaming, etc.) and you don't want the time taken to stream to be counted as part of the transaction. This is especially relevant when the time taken to complete the operation is completely outside the bounds of your application. For example, a user on a very slow connection may take a very long time to download even small files, and you wouldn't want that download time to skew the real transaction time.

newrelic_end_transaction ( [ignore] )
function newrelic_end_transaction (bool $ignore = false): bool

Despite being similar in name to newrelic_end_of_transaction above, this call serves a very different purpose. newrelic_end_of_transaction simply marks the end time of the transaction but takes no other action. The transaction is still only sent to the daemon when the PHP engine determines that the script is done executing and is shutting down. This function on the other hand, causes the current transaction to end immediately, and will ship all of the metrics gathered thus far to the daemon unless the ignore parameter is set to true. In effect this call simulates what would happen when PHP terminates the current transaction. This is most commonly used in command line scripts that do some form of job queue processing. You would use this call at the end of processing a single job task, and begin a new transaction (see below) when a new task is pulled off the queue.

Normally, when you end a transaction you want the metrics that have been gathered thus far to be recorded. However, there are times when you may want to end a transaction without doing so. In this case use the second form of the function and set ignore to true.

This function will return true if the transaction was successfully ended and data was sent to the New Relic daemon.

function newrelic_get_browser_timing_footer (bool $include_tags = true): string

Returns the JavaScript string to inject at the very end of the HTML output for page load timing (sometimes referred to as real user monitoring or RUM). If include_tags omitted or set to true, the returned JavaScript string will be enclosed in a <script> tag.

newrelic_get_browser_timing_header ( [include_tags] )
function newrelic_get_browser_timing_header (bool $include_tags = true): 

Returns the JavaScript string to inject as part of the header for page load timing (sometimes referred to as real user monitoring or RUM). If include_tags are omitted or set to true, the returned JavaScript string will be enclosed in a <script> tag.

newrelic_ignore_apdex ( )
function newrelic_ignore_apdex (): null

Do not generate Apdex metrics for this transaction. This is useful when you have either very short or very long transactions (such as file downloads) that can skew your Apdex score.

newrelic_ignore_transaction ( )
function newrelic_ignore_transaction (): null

Do not generate metrics for this transaction. This is useful when you have transactions that are particularly slow for known reasons and you do not want them always being reported as the transaction trace or skewing your site averages.

newrelic_name_transaction (name)
function newrelic_name_transaction (string $name): bool

Sets the name of the transaction to the specified name. This can be useful if you have implemented your own dispatching scheme and want to name transactions according to their purpose. Naming by URL should be avoided where possible.

This function will return true if the transaction name was successfully changed. If false is returned, check the agent log for more information.

Call this function as early as possible. It will have no effect, for example, if called after the JavaScript footer for page load timing (sometimes referred to as real user monitoring or RUM) has been sent.

Avoid creating too many unique transaction names. This will make your charts less useful, and you may run into limits New Relic sets on the number of unique transaction names per account. It also can slow down the performance of your application.

Example: Naming transactions

You have /product/123 and /product/234. If you generate a separate transaction name for each, then New Relic will store separate information for these two transaction names.

Instead, store the transaction as /product/*, or use something significant about the code itself to name the transaction, such as /Product/view. The total number of unique transaction names should be less than 1000. Exceeding that is not recommended.

In MVC frameworks, one good option is to use the newrelic_name_transaction() call where your request is routed and name your transaction with a format of Controller / Action.

Unique values like URLs, Page Titles, Hex Values, Session IDs and uniquely identifiable values should not be used in naming your transactions, but instead tagged to the transaction as a custom parameter. See newrelic_add_custom_parameter() API function.

newrelic_notice_error (message [, exception] )
newrelic_notice_error (unused, message, unused, unused, unused)
function newrelic_notice_error (string $message, Exception $exception = null): null

function newrelic_notice_error (int $unused_1, string $message, string $unused_2, int $unused_3, mixed $unused_4 = null): null

Report an error at this line of code, with a complete stack trace. The first form of the call was added in agent version 2.6 and should be used for reporting exceptions. Only the exception for the last call is retained during the course of a transaction. Agent version 4.3 enhanced this form to use the exception class as the category for grouping within the New Relic APM user interface.

Only a single error per transaction is captured by newrelic_notice_error and reported to New Relic. If you are using multiple newrelic_notice_error calls in a single transaction, only the last error captured by the call will be reported.

The exception parameter must be a valid PHP Exception class, and the stack frame recorded in that class will be the one reported, rather than the stack at the time this function was called. When using this form, if the error message is empty, a standard message in the same format as created by Exception::__toString() will be automatically generated.

With the second form of the call, only the message is used. This set of parameters allows newrelic_notice_error to be set as an error handler with the internal PHP function set_error_handler().

newrelic_record_custom_event (name, attributes)
function newrelic_record_custom_event (string $name, array $attributes): null

This API call was introduced in version 4.18 of the agent.

Records a New Relic Insights custom event. For more information, see Inserting custom events with the PHP agent.

The attributes parameter is expected to be an associative array. The keys should be the attribute names, which may be up to 255 characters in length, and the values should be scalar values. Arrays and objects are not supported.

newrelic_set_appname (name [, license [, xmit]] )
function newrelic_set_appname (string $name, string $license = ini_get('newrelic.license'), bool $xmit = false): bool

Sets the name of the application to name. The string uses the same format as newrelic.appname and can set multiple application names by separating each with a semi-colon (;). However, be aware of the restriction on the application name ordering as described for that setting.

The first application name is the primary name. You can also specify up to two extra application names. (However, the same application name can only ever be used once as a primary name.) Call this function as early as possible. It will have no effect if called after the JavaScript footer for page load timing (sometimes referred to as real user monitoring or RUM) has been sent.

Consider setting the application name in a file loaded by PHP's auto_prepend_file INI setting. This function returns true if it succeeded or false otherwise.

If you use multiple licenses, you can also specify a license key along with the application name. An application can appear in more than one account; the license key controls which account where you are changing the name. If you do not want to change the license but instead use the third variant, set the license key to the empty string ("").

The xmit flag was introduced with PHP agent version 3.1. Usually when you change an application name, the agent discards the current transaction and does not send any of the accumulated metrics to the daemon. However, if you want to record the metric and transaction data up to the point at which you called this function, you can specify a value of true for this argument to make the agent send the transaction to the daemon. This has a very slight performance impact as it takes a few milliseconds for the agent to dump its data. By default this parameter is false.

This function will return true if the application name was successfully changed.

newrelic_set_user_attributes (user, account, product)
function newrelic_set_user_attributes (string $user, string $account, string $product): bool

As of release 4.4, calling newrelic_set_user_attributes("a", "b", "c"); is equivalent to calling newrelic_add_custom_parameter("user", "a"); newrelic_add_custom_parameter("account", "b"); newrelic_add_custom_parameter("product", "c"); Previously, the three parameter strings were added to collected browser traces. All three parameters are required, but they may be empty strings.

This function will return true if the attributes were added successfully.

newrelic_start_transaction (appname [, license] )
function newrelic_start_transaction (string $appname, string $license = ini_get('newrelic.license')): bool

Use this call if you have ended a transaction before your script terminates (for example, it finished a task in a job queue manager) and you want to start a new transaction. This will perform the same operations that occur when the script was first started. Of the two arguments, only the application name is mandatory. However, if you are processing tasks for multiple accounts, you may also provide a license for the associated account. The license set for this API call will supersede all per-directory and global default licenses configured in INI files.

This function will return true if the transaction was successfully started.

For more help

Additional documentation resources include:

Join the discussion about PHP in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.