--- title: Guide to using the PHP agent API source: https://docs.newrelic.com/docs/apm/agents/php-agent/php-agent-api/guide-using-php-agent-api --- New Relic's PHP agent provides an [API](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api) for customizing agent behavior. The agent automatically instruments many [popular PHP frameworks](https://docs.newrelic.com/docs/agents/php-agent/getting-started/php-agent-compatibility-requirements#frameworks), but you can use the PHP API to instrument activity that the agent doesn't already instrument by default. This guide describes PHP API calls for several common tasks; for example: - Notice or ignore specific [errors](#errors). - Name a [transaction](#metadata). - Rename the [application](#name-app) reporting the data. > #### 💡 TIP > > You can also set many of these options [per directory](https://docs.newrelic.com/docs/agents/php-agent/configuration/php-directory-ini-settings) or in [`newrelic.ini`](https://docs.newrelic.com/docs/agents/php-agent/configuration/php-agent-configuration#inivar-background). If setting via API, the [API takes precedence over the other methods](https://docs.newrelic.com/docs/agents/php-agent/configuration/php-agent-configuration#config-options-precedence). ## Notice or ignore errors [#errors] Usually, the agent detects errors automatically. However, you can [manually mark an error](https://docs.newrelic.com/docs/apm/applications-menu/error-analytics/ignoring-errors-new-relic-apm) with the agent. | If you want to... | Do this... | | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Report an error the agent does not report automatically | See [`newrelic_notice_error()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelic_notice_error). | | Ignore an error | Edit [`error_collector.ignore_exceptions`](https://docs.newrelic.com/docs/agents/php-agent/configuration/php-agent-configuration#inivar-err-ignore-exceptions) or [`error_collector.ignore_errors`](https://docs.newrelic.com/docs/agents/php-agent/configuration/php-agent-configuration#inivar-err-ignore-errors) in the`newrelic.ini` file. | ## Enhance the metadata of a transaction [#metadata] Sometimes the code you target is visible in New Relic, but some details of the method are not useful. For example: - The default name is not helpful, or it is causing a [metric grouping issue](https://docs.newrelic.com/docs/agents/manage-apm-agents/troubleshooting/metric-grouping-issues). - You want to add [custom attributes](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes) to your transactions or spans so you can filter them with NRQL queries. Use these methods when you want to change how New Relic instruments a transaction that's already visible in New Relic: | If you want to... | Do this... | | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Change the name of a transaction | See [`newrelic_name_transaction()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelic_name_transaction). | | Add metadata (such as your customer's account name or subscription level) to your transactions or spans | Use [custom attributes](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes). For custom attributes which will be added to transactions and spans (if enabled), see [`newrelic_add_custom_parameter()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelic_add_custom_parameter). For custom attributes which will be added only to spans, see [`newrelic_add_custom_span_parameter()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelic_add_custom_span_parameter). | | Mark a transaction as a background job | See [`newrelic_background_job()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelic_background_job). | | Prevent a transaction from affecting your [Apdex score](https://docs.newrelic.com/docs/apm/new-relic-apm/apdex/apdex-measuring-user-satisfaction) | See [`newrelic_ignore_apdex()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelic_ignore_apdex). | ## See related logs [#logs] To see logs directly within the context of your application's errors and traces, use these API calls to annotate your logs: - [`newrelic_get_trace_metadata`](https://docs.newrelic.com/docs/apm/agents/php-agent/php-agent-api/newrelicgettracemetadata/) - [`newrelic_get_linking_metadata`](https://docs.newrelic.com/docs/apm/agents/php-agent/php-agent-api/newrelicgetlinkingmetadata/) For more information about correlating log data with other telemetry data, see our [logs in context](https://docs.newrelic.com/docs/logs/logs-context/configure-logs-context-php/) documentation. ## Name reporting app [#name-app] The New Relic UI organizes data by how you [name your application](https://docs.newrelic.com/docs/agents/manage-apm-agents/app-naming/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: - Organize and analyze your data on New Relic UI pages (for example, APM's [**Applications index** page](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/view-your-applications-index), the [**Summary** page](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/apm-overview-page), the [**Transactions** page](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/transactions-page), etc.). - [Query](https://docs.newrelic.com/docs/insights/nrql-new-relic-query-language/using-nrql/introduction-nrql) your data. - Create [alert policies](https://docs.newrelic.com/docs/alerts/overview). 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`](https://docs.newrelic.com/docs/agents/php-agent/configuration/php-agent-configuration#inivar-appname) config value, via [Apache](https://docs.newrelic.com/docs/agents/php-agent/configuration/php-directory-ini-settings#perdir-apache), or via [PHP-FPM](https://docs.newrelic.com/docs/agents/php-agent/configuration/php-directory-ini-settings#php-fpm_per-dir). | 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()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelic_set_appname). | ## Instrument missing sections of your code with transactions [#creating-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](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#transaction) and [transaction trace](https://docs.newrelic.com/docs/apm/transactions/transaction-traces/introduction-transaction-traces). 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()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelic_start_transaction). | | Stop timing a method after its work is completed | Stop a transaction. See [`newrelic_end_transaction()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelic_end_transaction). | | Prevent a transaction from reporting to New Relic | Ignore the transaction. See [`newrelic_ignore_transaction()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelic_ignore_transaction). | ## Time specific methods using segments [#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()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelic_add_custom_tracer). | ## Instrument asynchronous work [#async] The only async work the PHP agent instruments is Guzzle, which is [instrumented by default](https://docs.newrelic.com/docs/agents/php-agent/frameworks-libraries/guzzle). ## Send custom event and metric data from your app [#custom-data] New Relic includes a number of ways to record arbitrary custom data. For an explanation of New Relic data types, see [Data collection](https://docs.newrelic.com/docs/data-analysis/metrics/analyze-your-metrics/data-collection-metric-timeslice-event-data). | If you want to... | Do this... | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Send data about an event so you can analyze it in New Relic | Create a [custom event](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-events). See [Insert custom events via APM agent (PHP)](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-data/insert-custom-events-new-relic-apm-agents#php-att). | | Tag your events with metadata to filter and facet them | Add [custom attributes](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes). See [`newrelic_add_custom_parameter()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelic_add_custom_parameter). | | Report custom performance data | Create a [custom metric](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/custom-metrics). See [`newrelic_custom_metric()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newreliccustommetric-php-agent-api). | ## Instrument calls to external services [#datastore] Use these methods to collect data about your app's connections to other apps or datastores: | If you want to... | Do this... | | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Time a call to a datastore not instrumented by default | See [`newrelic_record_datastore_segment()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelic_record_datastore_segment). | | See the path that a request takes as it travels through a distributed system | For PHP agent versions lower than 9.8, see these API calls: - [`newrelic_create_distributed_trace_payload()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newreliccreatedistributedtracepayload-php-agent-api) - [`newrelic_accept_distributed_trace_payload()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelicacceptdistributedtracepayload-php-agent-api) - [`newrelic_accept_distributed_trace_payload_httpsafe()`](https://docs.newrelic.com/docs/agents/php-agent/php-agent-api/newrelicacceptdistributedtracepayloadhttpsafe-php-agent-api) For PHP agent versions 9.8 or higher, see these API calls: - `newrelic_insert_distributed_trace_headers()` - `newrelic_accept_distributed_trace_headers()` For examples, see the documentation to [manually instrument distributed tracing](https://docs.newrelic.com/docs/agents/php-agent/features/distributed-tracing#manual). | | | | ## Monitor specific browser pages [#browser] You can [install the browser agent](https://docs.newrelic.com/docs/browser/new-relic-browser/installation/install-new-relic-browser-agent) by automatically adding it to your pages or by deploying it on specific pages by copying and pasting our JavaScript snippet. You can also control the browser monitoring agent by using APM agent API calls. For more information, see [Browser monitoring and the PHP agent](https://docs.newrelic.com/docs/agents/php-agent/features/new-relic-browser-php-agent).