• /
  • EnglishEspañol日本語한국어Português
  • Log inStart now

newrelic_add_custom_parameter (PHP agent API)

Syntax

newrelic_add_custom_parameter(string $key, scalar $value)

Attaches a custom attribute (key/value pair) to the current transaction and the current span (if enabled).

Requirements

Agent version 4.4.5.35 or higher.

Description

Add a custom attribute (a key and a value data pair) to the current web transaction. (The call name is newrelic_add_custom_parameter because "custom attributes" were previously called "custom parameters.") For example, you can add a customer's full name from your customer database. This attribute appears in any transaction trace that results from this transaction. You can also query the Transaction event for your custom attributes.

Important

Security recommendation—Review your Transaction attributes configuration. Any attribute include or exclude settings specific to Transaction events, should be applied to your Span attributes configuration or your Global Attributes configuration.

Important

If you want to use your custom attributes, avoid using any of the reserved terms used by NRQL.

Parameters

Parameter

Description

$key

string

Required. The name of the custom attribute. Only the first 255 characters are retained.

$value

scalar

Required. The value to associate with this custom attribute.

If the value given is a float with a value of NaN, Infinity, denorm or negative zero, the behavior of this function is undefined. For other floating point values, the agent may discard 1 or more bits of precision (ULPs) from the given value.

Return values

Returns true if the parameter was added successfully.

Examples

Report a variable as the value

if (extension_loaded('newrelic')) { // Ensure PHP agent is available
// Record custom data about this web transaction
newrelic_add_custom_parameter('user_email', $user_email);
}

Multiple calls

If you call newrelic_add_custom_parameter multiple times with the same value for the $key parameter in the same web transaction, the $value from the last call takes precedence. The value from the last call is recorded as the custom attribute in the web transaction.

For example, if the code looks like this:

if (extension_loaded('newrelic')) { // Ensure PHP agent is available
// Record custom data about this web transaction
newrelic_add_custom_parameter('user_email', billy@newrelic.com);
newrelic_add_custom_parameter('user_email', samantha@newrelic.com);
}

The value samantha@newrelic.com gets recorded as the user_email custom attribute in the web transaction, and billy@newrelic.com from the earlier call is overwritten.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.