Guide to using the PHP agent API

New Relic APM for PHP provides an API for customizing the behavior of New Relic's PHP agent. The PHP agent automatically instruments many popular PHP frameworks, but you can use the API to instrument activity that the agent doesn't instrument by default. Other common tasks include:

You can also set many of these options per directory or in newrelic.ini. If setting via API, the API takes precedence over the other methods.

For all available New Relic APIs, see Intro to APIs.

Name reporting app

The New Relic UI organizes data by how you name your application. Each name appears as a different app. You can rename the reporting app for any part of your code to better help you:

This is especially useful if you have a multi-site application or distinct sets of application code using the same PHP installation.

Alternatively, you can set the app name at a higher level instead via the newrelic.appname config value, via Apache, or via PHP-FPM.

If you want to...

Do this...

Rename the reporting app for a specific part of your code

Set the app name. See newrelic_set_appname().

Instrument missing sections of your code with transactions

To instrument your app, New Relic separates each path through your code into its own transaction. New Relic times (or "instruments") the parent method in these transactions to measure your app's overall performance, and collects transaction traces from long-running transactions for additional detail. For more information about transactions, see transaction and transaction trace.

Use these methods when New Relic is not instrumenting a particular part of your code at all:

If you want to...

Do this...

Start timing a method New Relic is not instrumenting automatically

Start a transaction. See newrelic_start_transaction().

Stop timing a method after its work is completed

Stop a transaction. See newrelic_end_transaction().

Prevent a transaction from reporting to New Relic

Ignore the transaction. See newrelic_ignore_transaction().

Time specific methods using segments

If a transaction is already visible in the New Relic UI, but you don't have enough data about a particular method that was called during that transaction, you can create segments to time those individual methods in greater detail. For example, you might want to time a particularly critical method with complex logic.

Use this methods when you want to instrument a method within an existing transaction:

If you want to...

Do this...

Time a particular method

See newrelic_add_custom_tracer().

Enhance the metadata of a transaction

Sometimes, the code you are targeting is visible in the New Relic UI, but some details of the method are not useful. For example, the default name might not be helpful (perhaps it is causing a metric grouping issue), or you want to add custom attributes to your transactions so you can filter them in Insights.

Use these methods when you want to change how New Relic instruments a transaction that's already visible in the New Relic UI:

If you want to...

Do this...

Change the name of a transaction

See newrelic_name_transaction().

Add metadata (such as your customer's account name or subscription level) to your transactions

Use custom attributes. See newrelic_add_custom_parameter().

Mark a transaction as a background job

See newrelic_background_job().

Prevent a transaction from affecting your Apdex score

See newrelic_ignore_apdex().

Instrument asynchronous work

The only async work the PHP agent instruments is Guzzle, which is instrumented by default.

Collect errors

Usually, the agent detects errors automatically. However, you can manually mark an error with the agent.

If you want to...

Do this...

Report an error the agent does not report automatically

See newrelic_notice_error().

Ignore an error

Edit error_collector.ignore_exceptions or error_collector.ignore_errors in thenewrelic.ini file.

Send custom event and metric data from your app

New Relic APM includes a number of ways to record arbitrary custom data. For an explanation of New Relic data types, see Data collection.

If you want to...

Do this...

Send data about an event so you can analyze it in New Relic Insights

Create a custom event. See Insert custom events via APM agent (PHP).

Tag your events with metadata to filter and facet them in Insights or error analytics

Add custom attributes. See newrelic_add_custom_parameter().

Report custom performance data once a minute

Create a custom metric. See newrelic_custom_metric().

Instrument calls to datastores

Use these methods to collect data about your app's connections to other datastores:

If you want to...

Do this...

Time a call to a datastore not instrumented by default

See newrelic_record_datastore_segment().

Control the New Relic Browser agent

Usually the Browser agent is added automatically to your pages or deployed by copy/pasting the JavaScript snippet. For more information about these recommended methods, see Add apps to New Relic Browser.

However, you can also control the New Relic Browser agent via APM agent API calls. For more information, see New Relic Browser and the PHP agent.

For more help

Recommendations for learning more: