---
title: record_custom_metric (Python agent API)
source: https://docs.newrelic.com/docs/apm/agents/python-agent/python-agent-api/recordcustommetric-python-agent-api
---

## Syntax

```PY
newrelic.agent.record_custom_metric(name, value, application=None)
```

Records a single custom metric.

## Description

This call records a single [custom metric](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/custom-metrics). To record a set of metrics, see [`record_custom_metrics`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/record_custom_metrics).

## Parameters

| Parameter                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` _string_                    | Required. Name of the metric. There are no restrictions on naming formats, but we recommend you use a `Custom/` prefix for your custom metric names. This helps you differentiate custom metrics from default-monitored metrics in the our UI, and also helps you troubleshoot if necessary.                                                                                                                                                                 |
| `value` _int_ or _dict_            | Required. The numeric value of the metric. Can be an integer, a float, or a dictionary of values. The possible fields for a dictionary are: - `count` - `total` - `min` - `max` - `sum_of_squares`                                                                                                                                                                                                                                                           |
| `application` _application object_ | Optional. The [application object](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/application) corresponding to the app with which you want to associate the metrics. If the application is the default value of `None`, the agent records the custom metrics to the app associated with the current transaction. Thus, you should provide the application unless this method is used in code for a web transaction or background task. |

## Return values

None.

## Examples

### Recording a custom metric using the application object [#app-object-example]

To record custom metrics from a distinct background thread or other code, you must pass the [application object](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/application) corresponding to the application to which the custom metrics are to be reported.

```PY
import newrelic.agent
application = newrelic.agent.application()

newrelic.agent.record_custom_metric('Custom/my_favorite_number', 42, application)
```

## View and use custom metrics

To view custom metrics, use [metrics and events](https://docs.newrelic.com/docs/query-your-data/explore-query-data/data-explorer/introduction-data-explorer) to search and filter for custom metrics, create customizable charts, and add those charts to New Relic dashboards. You can use our [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 UI. It is also possible to [create custom metric alert conditions](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.