Skip to content

Latest commit

 

History

History
1247 lines (971 loc) · 25.4 KB

record-custom-metrics.mdx

File metadata and controls

1247 lines (971 loc) · 25.4 KB
Raw
title type shortDescription tags metaDescription redirects freshnessValidatedDate
Record custom metrics
apiDoc
Create custom metrics to record numberic app data.
Mobile monitoring
Mobile SDK API
Custom instrumentation
Mobile app monitoring API used to create custom metrics to record arbitrary numeric app data.
/docs/mobile-monitoring/new-relic-mobile-ios/ios-sdk-api/recordmetric-ios-sdk-api
/docs/mobile-monitoring/new-relic-mobile-android/android-sdk-api/recordmetric-android-sdk-api
2023-07-20
Android iOS Capacitor Cordova .NET MAUI Flutter React Native Unity Xamarin 
<TabsPages>
    <TabsPageItem id="android">

Syntax [#syntax]

Java [#java]

NewRelic.setUserId(string $userId)

Kotlin [#kotlin]

NewRelic.recordMetric(
            name: String,
            category: String,
            count: Int,
            totalValue: Double,
            exclusiveValue: Double,
            countUnit: MetricUnit,
            valueUnit: MetricUnit
        )
   NewRelic.recordMetric(name: String?, category: String?, value: Double = 1.0)

Description [#description]

With this method, you can record arbitrary custom metrics to give more detail about app activity that is not tracked by New Relic automatically. The call accepts several sets of parameters for optional levels of detail.

To get the most out of your metrics, follow these guidelines to create clear, concise metric names:

  • Use case and whitespace characters appropriate for display in the user interface. Metric names are rendered as-is.
  • Capitalize the metric name.
  • Avoid using the characters / ] [ | * when naming metrics.
  • Avoid multi-byte characters.

The category is also required; it is displayed in the UI and is useful for organizing custom metrics if you have many of them. It can be a custom category or it can be a predefined category using the MetricCategory enum.

Parameters [#parameters]

        <td>
    `string`
  </td>

  <td>
    Required. The desired name for the custom metric.
  </td>
</tr>

    <tr>
  <td>
    `$category`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The metric category name, either custom or using a predefined [metric category](/docs/mobile-monitoring/new-relic-mobile-android/install-configure/work-android-sdk-api#cat).
</td>
</tr>

        <tr>
  <td>
    `value`
  </td>

        <td>
    `double`
  </td>

  <td>
    Required. The value of the metric.
  </td>
</tr>

            <tr>
  <td>
    `count`
  </td>

        <td>
    `int`
  </td>

  <td>
    Required. The number of times the metric was recorded.
  </td>
</tr>

                <tr>
  <td>
    `totalValue`
  </td>

        <td>
    `double`
  </td>

  <td>
    Required. The total value of the metric.
  </td>
</tr>

                <tr>
  <td>
    `exclusiveValue`
  </td>

        <td>
    `double`
  </td>

  <td>
    Required. The exclusive value of the recording; for example, if the total value contains measurements accounted for elsewhere.
  </td>
</tr>

                    <tr>
  <td>
    `countUnit`
  </td>

        <td>
    `MetricUnit`
  </td>

  <td>
    Required. Unit of measurement for the metric count, including `PERCENT`, `BYTES`, `SECONDS`, `BYTES_PER_SECOND`, or `OPERATIONS`.
  </td>
</tr>

                    <tr>
  <td>
    `valueUnit`
  </td>

        <td>
    `MetricUnit`
  </td>

  <td>
    Required. Unit of measurement for the metric value, including `PERCENT`, `BYTES`, `SECONDS`, `BYTES_PER_SECOND`, or `OPERATIONS`.
  </td>
</tr>
Parameter Type Description
`$name`

Examples [#examples]

Here's an example of creating simple custom metrics:

Java [#java]

NewRelic.recordMetric("Custom Metric Name","MyCategory", 1.0);
NewRelic.recordMetric("Login Auth Metric", "Network", 1.0);

Kotlin [#kotlin]

    NewRelic.recordMetric("Custom Metric Name","MyCategory", 1.0)
    NewRelic.recordMetric("Login Auth Metric", "Network", 1.0)

Here's an example of creating a custom metric for agent start:

Java [#java]

NewRelic.recordMetric("Agent start", "Lifecycle");

Kotlin [#kotlin]

NewRelic.recordMetric("Agent start", "Lifecycle")

Here's an example of the same metric above, but with elapsed time value added:

Java [#java]

NewRelic.recordMetric("Agent start", "Lifecycle", 10.11f);

Kotlin [#kotlin]

NewRelic.recordMetric("Agent start", "Lifecycle", 10.11)

Here's an example of the same metric above, but with five counts of elapsed time, exclusive time, and a unit value parameter:

Java [#java]

NewRelic.recordMetric("Agent start", "Lifecycle", 5, 10.11, 1.23, MetricUnit.OPERATIONS, MetricUnit.SECONDS);

Kotlin [#kotlin]

    NewRelic.recordMetric("Agent start", "Lifecycle", 5, 10.11, 1.23, MetricUnit.OPERATIONS, MetricUnit.SECONDS)
    </TabsPageItem>
    <TabsPageItem id="ios">

Syntax [#syntax]

Objective-c [#objc]

NewRelic recordMetricWithName:(NSString *)name  category:(NSString *)category  value:(NSNumber *)value];

Swift [#swift]

NewRelic.recordMetric(withName: String!, category: String!, value: NSNumber!)

Description [#description]

With this method, you can record arbitrary custom metrics to give more detail about app activity that is not tracked by New Relic automatically. The call accepts several sets of parameters for optional levels of detail.

This method will record a metric of the form Custom/[Category]/[Name], with a count of 1 and a total value equal to the value passed in. Multiple calls will aggregate the count and value according to standard metric aggregation rules for .

To get the most out of your metrics, follow these guidelines to create clear, concise metric names:

  • Use case and whitespace characters appropriate for display in the user interface. Metric names are rendered as-is.
  • Capitalize the metric name.
  • Avoid using the characters / ] [ | * when naming metrics.
  • Avoid multi-byte characters.

The category is also required; it is displayed in the UI and is useful for organizing custom metrics if you have many of them. It can be a custom category or it can be a predefined category using the MetricCategory enum.

Parameters [#parameters]

        <td>
    `NSString`
  </td>

  <td>
    Required. The desired name for the custom metric.
  </td>
</tr>

    <tr>
  <td>
    `category`
  </td>

        <td>
    `NSString`
  </td>

  <td>
    Required. The metric category name, either custom or using a predefined [metric category](/docs/mobile-monitoring/new-relic-mobile-android/install-configure/work-android-sdk-api#cat).
</td>
</tr>

        <tr>
  <td>
    `value`
  </td>

        <td>
    `NSNumber`
  </td>

  <td>
    Required. The value of the metric.
  </td>
</tr>
Parameter Type Description
`name`

Examples [#examples]

Objective-C [#obj-c]

Here's an example of creating a metric in milliseconds:

[NewRelic recordMetricWithName:(NSString *)@"My Important Metric"
  category:(NSString *)@"Important Metrics" 
    value:(NSNumber *)145.67];

Swift [#swift]

Here's an example of creating a metric in milliseconds:

NewRelic.recordMetric(withName: "My Important Metric", category: "Important Metrics", value: 145.67)
    </TabsPageItem>
    <TabsPageItem id="capacitor">

Syntax [#syntax]

recordMetric(options: { name: string; category: string; value?: number; countUnit?: string; valueUnit?: string; }) => void

Description [#description]

Records custom metrics (arbitrary numerical data), where countUnit is the measurement unit of the metric count and valueUnit is the measurement unit for the metric value. If you use countUnit or valueUnit, then you must set all three: value, countUnit, and valueUnit.

Supported measurements for countUnit and valueUnit are:

  • PERCENT
  • BYTES
  • SECONDS
  • BYTES_PER_SECOND
  • OPERATIONS

Parameters [#parameters]

        <td>
    `string`
  </td>

  <td>
    Required. The desired name for the custom metric.
  </td>
</tr>

    <tr>
  <td>
    `category`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The metric category name, either custom or using a predefined [metric category](/docs/mobile-monitoring/new-relic-mobile-android/install-configure/work-android-sdk-api#cat).
</td>
</tr>

        <tr>
  <td>
    `value`
  </td>

        <td>
    `number`
  </td>

  <td>
    Required. The value of the metric.
  </td>
</tr>

            <tr>
  <td>
    `countUnit`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The unit of measurement for the count.
  </td>
</tr>

                <tr>
  <td>
    `valueUnit`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The unit of measurement for the count.
  </td>
</tr>
Parameter Type Description
`name`

Example [#example]

    NewRelicCapacitorPlugin.recordMetric({
      name: "CapacitorMetricName",
      category: "CapacitorMetricCategory",
    });
    NewRelicCapacitorPlugin.recordMetric({
      name: "CapacitorMetricName2",
      category: "CapacitorMetricCategory2",
      value: 25,
    });
    NewRelicCapacitorPlugin.recordMetric({
      name: "CapacitorMetricName3",
      category: "CapacitorMetricCategory3",
      value: 30,
      countUnit: NREnums.MetricUnit.SECONDS,
      valueUnit: NREnums.MetricUnit.OPERATIONS,
    });
    </TabsPageItem>
    <TabsPageItem id="cordova">

Syntax [#syntax]

recordMetric(name: string, category: string, value?: number, countUnit?: string, valueUnit?: string): void;

Description [#description]

Records custom metrics (arbitrary numerical data), where countUnit is the measurement unit of the metric count and valueUnit is the measurement unit for the metric value. If you use countUnit or valueUnit, then you must set all three: value, countUnit, and valueUnit.

Supported measurements for countUnit and valueUnit are:

  • PERCENT
  • BYTES
  • SECONDS
  • BYTES_PER_SECOND
  • OPERATIONS

Parameters [#parameters]

        <td>
    `string`
  </td>

  <td>
    Required. The desired name for the custom metric.
  </td>
</tr>

    <tr>
  <td>
    `category`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The metric category name, either custom or using a predefined [metric category](/docs/mobile-monitoring/new-relic-mobile-android/install-configure/work-android-sdk-api#cat).
</td>
</tr>

        <tr>
  <td>
    `value`
  </td>

        <td>
    `number`
  </td>

  <td>
    Required. The value of the metric.
  </td>
</tr>

            <tr>
  <td>
    `countUnit`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The unit of measurement for the count.
  </td>
</tr>

                <tr>
  <td>
    `valueUnit`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The unit of measurement for the count.
  </td>
</tr>
Parameter Type Description
`name`

Example [#example]

  NewRelic.recordMetric('CordovaCustomMetricName', 'CordovaCustomMetricCategory');
  NewRelic.recordMetric('CordovaCustomMetricName', 'CordovaCustomMetricCategory', 12);
  NewRelic.recordMetric('CordovaCustomMetricName', 'CordovaCustomMetricCategory', 13, 'PERCENT', 'SECONDS');
    </TabsPageItem>

   <TabsPageItem id="maui">

Syntax [#syntax]

RecordMetric(string name, string category) : void;
RecordMetric(string name, string category, double value) : void;

Description [#description]

Records custom metrics (arbitrary numerical data), where countUnit is the measurement unit of the metric count and valueUnit is the measurement unit for the metric value. If you use countUnit or valueUnit, then you must set all three: value, countUnit, and valueUnit.

Supported measurements for countUnit and valueUnit are:

  • PERCENT
  • BYTES
  • SECONDS
  • BYTES_PER_SECOND
  • OPERATIONS

Parameters [#parameters]

        <td>
    `string`
  </td>

  <td>
    Required. The desired name for the custom metric.
  </td>
</tr>

    <tr>
  <td>
    `category`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The metric category name, either custom or using a predefined [metric category](/docs/mobile-monitoring/new-relic-mobile-android/install-configure/work-android-sdk-api#cat).
</td>

</tr>

        <tr>
  <td>
    `value`
  </td>

        <td>
    `number`
  </td>

  <td>
    Required. The value of the metric.
  </td>
</tr>

            <tr>
  <td>
    `countUnit`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The unit of measurement for the count.
  </td>
</tr>

                <tr>
  <td>
    `valueUnit`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The unit of measurement for the count.
  </td>
</tr>
Parameter Type Description
`name`
## Example [#example] 
    CrossNewRelic.Current.RecordMetric("Agent start", "Lifecycle");
    CrossNewRelic.Current.RecordMetric("Login Auth Metric", "Network", 78.9);
    </TabsPageItem>
    <TabsPageItem id="flutter">

Syntax [#syntax]

recordMetric(name: string, category: string, value?: number, countUnit?: string, valueUnit?: string): void;

Description [#description]

Records custom metrics (arbitrary numerical data), where countUnit is the measurement unit of the metric count and valueUnit is the measurement unit for the metric value. If you use countUnit or valueUnit, then you must set all three: value, countUnit, and valueUnit.

Supported measurements for countUnit and valueUnit are:

  • PERCENT
  • BYTES
  • SECONDS
  • BYTES_PER_SECOND
  • OPERATIONS

Parameters [#parameters]

        <td>
    `string`
  </td>

  <td>
    Required. The desired name for the custom metric.
  </td>
</tr>

    <tr>
  <td>
    `category`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The metric category name, either custom or using a predefined metric category.
</td>
</tr>

        <tr>
  <td>
    `value`
  </td>

        <td>
    `number`
  </td>

  <td>
    Required. The value of the metric.
  </td>
</tr>

            <tr>
  <td>
    `countUnit`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The unit of measurement for the count.
  </td>
</tr>

                <tr>
  <td>
    `valueUnit`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The unit of measurement for the count.
  </td>
</tr>
Parameter Type Description
`name`

Example [#example]

NewrelicMobile.instance.recordMetric("testMetric", "Test Champ",value: 12.0);
     NewrelicMobile.instance.recordMetric("testMetric1", "TestChamp12",value: 10,valueUnit: MetricUnit.BYTES,countUnit: MetricUnit.PERCENT);
                </TabsPageItem>
    <TabsPageItem id="react">

Syntax [#syntax]

recordMetric(name: string, category: string, value?: number, countUnit?: string, valueUnit?: string): void;

Description [#description]

Records custom metrics (arbitrary numerical data), where countUnit is the measurement unit of the metric count and valueUnit is the measurement unit for the metric value. If you use countUnit or valueUnit, then you must set all three: value, countUnit, and valueUnit.

Supported measurements for countUnit and valueUnit are:

  • PERCENT
  • BYTES
  • SECONDS
  • BYTES_PER_SECOND
  • OPERATIONS

Parameters [#parameters]

        <td>
    `string`
  </td>

  <td>
    Required. The desired name for the custom metric.
  </td>
</tr>

    <tr>
  <td>
    `category`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The metric category name, either custom or using a predefined [metric category](/docs/mobile-monitoring/new-relic-mobile-android/install-configure/work-android-sdk-api#cat).
</td>
</tr>

        <tr>
  <td>
    `value`
  </td>

        <td>
    `number`
  </td>

  <td>
    Required. The value of the metric.
  </td>
</tr>

            <tr>
  <td>
    `countUnit`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The unit of measurement for the count.
  </td>
</tr>

                <tr>
  <td>
    `valueUnit`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The unit of measurement for the count.
  </td>
</tr>
Parameter Type Description
`name`

Example [#example]

   NewRelic.recordMetric('RNCustomMetricName', 'RNCustomMetricCategory');
   NewRelic.recordMetric('RNCustomMetricName', 'RNCustomMetricCategory', 12);
   NewRelic.recordMetric('RNCustomMetricName', 'RNCustomMetricCategory', 13, NewRelic.MetricUnit.PERCENT, NewRelic.MetricUnit.SECONDS);
    </TabsPageItem>

Syntax [#syntax]

RecordMetricWithName(string name, string category) : void;
RecordMetricWithName(string name, string category, double value) : void;
RecordMetricWithName(string name, string category, double value, MetricUnit countUnit, MetricUnit valueUnit) : void;

Description [#description]

Records custom metrics (arbitrary numerical data), where countUnit is the measurement unit of the metric count and valueUnit is the measurement unit for the metric value. If you use countUnit or valueUnit, then you must set all three: value, countUnit, and valueUnit.

Supported measurements for countUnit and valueUnit are:

  • PERCENT
  • BYTES
  • SECONDS
  • BYTES_PER_SECOND
  • OPERATIONS

Parameters [#parameters]

        <td>
    `string`
  </td>

  <td>
    Required. The desired name for the custom metric.
  </td>
</tr>

    <tr>
  <td>
    `category`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The metric category name, either custom or using a predefined [metric category](/docs/mobile-monitoring/new-relic-mobile-android/install-configure/work-android-sdk-api#cat).
</td>
</tr>

        <tr>
  <td>
    `value`
  </td>

        <td>
    `number`
  </td>

  <td>
    Required. The value of the metric.
  </td>
</tr>

            <tr>
  <td>
    `countUnit`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The unit of measurement for the count.
  </td>
</tr>

                <tr>
  <td>
    `valueUnit`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The unit of measurement for the count.
  </td>
</tr>
Parameter Type Description
`name`

Example [#example]

        NewRelicAgent.RecordMetricWithName('UnityCustomMetricName', 'UnityCustomMetricCategory');
        NewRelicAgent.RecordMetricWithName('UnityCustomMetricName', 'UnityCustomMetricCategory', 12);
        NewRelicAgent.RecordMetricWithName('UnityCustomMetricName', 'UnityCustomMetricCategory', 13, NewRelicAgent.MetricUnit.PERCENT, NewRelicAgent.MetricUnit.SECONDS);
    </TabsPageItem>
    <TabsPageItem id="xamarin">

Syntax [#syntax]

RecordMetric(string name, string category) : void;
RecordMetric(string name, string category, double value) : void;
RecordMetric(string name, string category, double value, MetricUnit countUnit, MetricUnit valueUnit) : void;

Description [#description]

Records custom metrics (arbitrary numerical data), where countUnit is the measurement unit of the metric count and valueUnit is the measurement unit for the metric value. If you use countUnit or valueUnit, then you must set all three: value, countUnit, and valueUnit.

Supported measurements for countUnit and valueUnit are:

  • PERCENT
  • BYTES
  • SECONDS
  • BYTES_PER_SECOND
  • OPERATIONS

Parameters [#parameters]

        <td>
    `string`
  </td>

  <td>
    Required. The desired name for the custom metric.
  </td>
</tr>

    <tr>
  <td>
    `category`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The metric category name, either custom or using a predefined [metric category](/docs/mobile-monitoring/new-relic-mobile-android/install-configure/work-android-sdk-api#cat).
</td>
</tr>

        <tr>
  <td>
    `value`
  </td>

        <td>
    `number`
  </td>

  <td>
    Required. The value of the metric.
  </td>
</tr>

            <tr>
  <td>
    `countUnit`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The unit of measurement for the count.
  </td>
</tr>

                <tr>
  <td>
    `valueUnit`
  </td>

        <td>
    `string`
  </td>

  <td>
    Required. The unit of measurement for the count.
  </td>
</tr>
Parameter Type Description
`name`

Example [#example]

    CrossNewRelicClient.Current.RecordMetric("Agent start", "Lifecycle");
    CrossNewRelicClient.Current.RecordMetric("Login Auth Metric", "Network", 78.9);
    CrossNewRelicClient.Current.RecordMetric("Request Metric", "Network", 20, MetricUnit.SECONDS, MetricUnit.OPERATIONS);
    </TabsPageItem>

</TabsPages>