---
title: newrelic_custom_metric (PHP agent API)
source: https://docs.newrelic.com/docs/apm/agents/php-agent/php-agent-api/newreliccustommetric-php-agent-api
---

## Syntax

```php
newrelic_custom_metric(string $metric_name, float $value)
```

Add a custom metric (in milliseconds) to time a component of your app not captured by default.

## Requirements

Compatible with all agent versions.

## Description

Record [custom metrics](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/custom-metrics) that aren't captured by default by the PHP agent.

Then you can:

-   Use [metrics and events](https://docs.newrelic.com/docs/query-your-data/explore-query-data/data-explorer/introduction-data-explorer) to search for your custom metrics, create customizable charts, and add them to dashboards.
-   Use the [New Relic REST API](https://docs.newrelic.com/docs/apis/rest-api-v2/requirements/new-relic-rest-api-v2-getting-started) to programmatically retrieve and use custom metric data outside of the New Relic UI.
-   [Create custom metric alerts](https://docs.newrelic.com/docs/alerts/new-relic-alerts/configuring-alert-policies/define-custom-metrics-alert-condition) to notify you or your team when your custom metric exceeds specific values.

## Parameters

| Parameter               | Description                                                                                                                                                                                                                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `$metric_name` _string_ | Required. Name your custom metrics with a **Custom/** prefix (for example, **Custom/MyMetric**). This helps the UI organize your custom metrics in one place, and it makes them easily findable via the Metric Explorer.                                                                                     |
| `$value` _float_        | Required. Records timing in milliseconds. For example: a value of `4` is stored as `.004` seconds in New Relic's systems. 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. |

## Return values

Returns `true` if the metric was added successfully.

## Examples

### Record a 100 millisecond response time [#100-ms-example]

```php
function example() {
    if (extension_loaded('newrelic')) { // Ensure PHP agent is available
        newrelic_custom_metric("Custom/custom-metric-name", 100.00);
    }
}
```