Package com.newrelic.api.agent

Class NewRelic

  • public final class NewRelic
extends java.lang.Object
    The New Relic API. Consumers of this API should add the newrelic-api.jar to their classpath. The static methods of this class form the Agent's basic Java API. Use getAgent() to obtain the root of a hierarchy of objects offering additional capabilities.

    • Constructor Summary

      Constructors 
      Constructor Description
      NewRelic()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void addCustomParameter​(java.lang.String key, boolean value)
      Add a key/value pair to the current transaction.
      static void addCustomParameter​(java.lang.String key, java.lang.Number value)
      Add a key/value pair to the current transaction.
      static void addCustomParameter​(java.lang.String key, java.lang.String value)
      Add a key/value pair to the current transaction.
      static void addCustomParameters​(java.util.Map<java.lang.String,​java.lang.Object> params)
      Add key/value pairs to the current transaction.
      static Agent getAgent()
      Returns the root of the New Relic Java Agent API object hierarchy.
      static java.lang.String getBrowserTimingFooter()
      Get the RUM JavaScript footer for the current web transaction.
      static java.lang.String getBrowserTimingFooter​(java.lang.String nonce)
      Get the RUM JavaScript footer for the current web transaction.
      static java.lang.String getBrowserTimingHeader()
      Get the RUM JavaScript header for the current web transaction.
      static java.lang.String getBrowserTimingHeader​(java.lang.String nonce)
      Get the RUM JavaScript header for the current web transaction.
      static void ignoreApdex()
      Ignore the current transaction for calculating Apdex score.
      static void ignoreTransaction()
      Ignore the current transaction.
      static void incrementCounter​(java.lang.String name)
      Increment the metric counter for the given name.
      static void incrementCounter​(java.lang.String name, int count)
      Increment the metric counter for the given name.
      static void noticeError​(java.lang.String message)
      Notice an error and report it to New Relic.
      static void noticeError​(java.lang.String message, boolean expected)
      Notice an error and report it to New Relic.
      static void noticeError​(java.lang.String message, java.util.Map<java.lang.String,​?> params)
      Notice an error and report it to New Relic.
      static void noticeError​(java.lang.String message, java.util.Map<java.lang.String,​?> params, boolean expected)
      Notice an error and report it to New Relic.
      static void noticeError​(java.lang.Throwable throwable)
      Report an exception to New Relic.
      static void noticeError​(java.lang.Throwable throwable, boolean expected)
      Report an exception to New Relic.
      static void noticeError​(java.lang.Throwable throwable, java.util.Map<java.lang.String,​?> params)
      Notice an exception and report it to New Relic.
      static void noticeError​(java.lang.Throwable throwable, java.util.Map<java.lang.String,​?> params, boolean expected)
      Notice an exception and report it to New Relic.
      static void recordMetric​(java.lang.String name, float value)
      Record a metric value for the given name.
      static void recordResponseTimeMetric​(java.lang.String name, long millis)
      Record a response time in milliseconds for the given metric name.
      static void setAccountName​(java.lang.String name)
      Set the account name to associate with the RUM JavaScript footer for the current web transaction.
      static void setAppServerPort​(int port)
      Set the app server port which is reported to RPM.
      static void setErrorGroupCallback​(ErrorGroupCallback errorGroupCallback)
      Registers an ErrorGroupCallback that's used to generate a grouping key for the supplied error.
      static void setInstanceName​(java.lang.String instanceName)
      Set the instance name in the environment.
      static void setProductName​(java.lang.String name)
      Set the product name to associate with the RUM JavaScript footer for the current web transaction.
      static void setRequestAndResponse​(Request request, Response response)
      Sets the request and response instances for the current transaction.
      static void setServerInfo​(java.lang.String dispatcherName, java.lang.String version)
      Set the dispatcher name and version which is reported to RPM.
      static void setTransactionName​(java.lang.String category, java.lang.String name)
      Set the name of the current transaction.
      static void setUserId​(java.lang.String userId)
      Sets the user ID for the current transaction by adding the "enduser.id" agent attribute.
      static void setUserName​(java.lang.String name)
      Set the user name to associate with the RUM JavaScript footer for the current web transaction.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • NewRelic

        public NewRelic()

    • Method Detail

      • getAgent

        public static Agent getAgent()
        Returns the root of the New Relic Java Agent API object hierarchy.
        Returns:
        the root of the New Relic Java Agent API object hierarchy
        Since:
        3.9.0

      • recordMetric

        public static void recordMetric​(java.lang.String name,
                                float value)
        Record a metric value for the given name.
        Parameters:
        name - The name of the metric. The metric is not recorded if the name is null or the empty string.
        value - The value of the metric.
        Since:
        1.3.0

      • recordResponseTimeMetric

        public static void recordResponseTimeMetric​(java.lang.String name,
                                            long millis)
        Record a response time in milliseconds for the given metric name.
        Parameters:
        name - The name of the metric. The response time is not recorded if the name is null or the empty string.
        millis - The response time in milliseconds.
        Since:
        1.3.0

      • incrementCounter

        public static void incrementCounter​(java.lang.String name)
        Increment the metric counter for the given name.
        Parameters:
        name - The name of the metric to increment.
        Since:
        1.3.0

      • incrementCounter

        public static void incrementCounter​(java.lang.String name,
                                    int count)
        Increment the metric counter for the given name.
        Parameters:
        name - The name of the metric to increment.
        count - The amount in which the metric should be incremented.
        Since:
        2.21.0

      • noticeError

        public static void noticeError​(java.lang.Throwable throwable,
                               java.util.Map<java.lang.String,​?> params)
        Notice an exception and report it to New Relic. If this method is called within a transaction, the exception will be reported with the transaction when it finishes. If it is invoked outside of a transaction, a traced error will be created and reported to New Relic. If noticeError is invoked multiple times while in a transaction, only the last error will be reported.

        Note: The key and value pairs in custom parameters params will be dropped or modified in the traced error if the key or value, each, cannot be encoded in 255 bytes. If key or value is over this limit, the behavior will be the same as defined in addCustomParameter.

        Parameters:
        throwable - The throwable to notice and report.
        params - Custom parameters to include in the traced error. May be null.
        Since:
        1.3.0

      • noticeError

        public static void noticeError​(java.lang.Throwable throwable)
        Report an exception to New Relic.
        Parameters:
        throwable - The throwable to report.
        Since:
        1.3.0
        See Also:
        noticeError(Throwable, Map)

      • noticeError

        public static void noticeError​(java.lang.String message,
                               java.util.Map<java.lang.String,​?> params)
        Notice an error and report it to New Relic. If this method is called within a transaction, the error message will be reported with the transaction when it finishes. If it is invoked outside of a transaction, a traced error will be created and reported to New Relic. If noticeError is invoked multiple times while in a transaction, only the last error will be reported.

        Note: The key and value pairs in custom parameters params will be dropped or modified in the traced error if the key or value, each, cannot be encoded in 255 bytes. If key or value is over this limit, the behavior will be the same as defined in addCustomParameter.

        Parameters:
        message - The error message to be reported.
        params - Custom parameters to include in the traced error. May be null.
        Since:
        1.3.0

      • noticeError

        public static void noticeError​(java.lang.String message)
        Notice an error and report it to New Relic. If this method is called within a transaction, the error message will be reported with the transaction when it finishes. If it is invoked outside of a transaction, a traced error will be created and reported to New Relic. If noticeError is invoked multiple times while in a transaction, only the last error will be reported.
        Parameters:
        message - Message to report with a transaction when it finishes.
        Since:
        2.21.0

      • noticeError

        public static void noticeError​(java.lang.Throwable throwable,
                               java.util.Map<java.lang.String,​?> params,
                               boolean expected)
        Notice an exception and report it to New Relic. If this method is called within a transaction, the exception will be reported with the transaction when it finishes. If it is invoked outside of a transaction, a traced error will be created and reported to New Relic. If noticeError is invoked multiple times while in a transaction, only the last error will be reported. Expected errors do not increment an application's error count or contribute towards its Apdex score.

        Note: The key and value pairs in custom parameters params will be dropped or modified in the traced error if the key or value, each, cannot be encoded in 255 bytes. If key or value is over this limit, the behavior will be the same as defined in addCustomParameter.

        Parameters:
        throwable - The throwable to notice and report.
        params - Custom parameters to include in the traced error. May be null.
        expected - true if this error is expected, false otherwise.
        Since:
        3.38.0

      • noticeError

        public static void noticeError​(java.lang.Throwable throwable,
                               boolean expected)
        Report an exception to New Relic. Expected errors do not increment an application's error count or contribute towards its Apdex score.
        Parameters:
        throwable - The throwable to report.
        expected - true if this error is expected, false otherwise.
        Since:
        3.38.0
        See Also:
        noticeError(Throwable, Map)

      • noticeError

        public static void noticeError​(java.lang.String message,
                               java.util.Map<java.lang.String,​?> params,
                               boolean expected)
        Notice an error and report it to New Relic. If this method is called within a transaction, the error message will be reported with the transaction when it finishes. If it is invoked outside of a transaction, a traced error will be created and reported to New Relic. If noticeError is invoked multiple times while in a transaction, only the last error will be reported. Expected errors do not increment an application's error count or contribute towards its Apdex score.

        Note: The key and value pairs in custom parameters params will be dropped or modified in the traced error if the key or value, each, cannot be encoded in 255 bytes. If key or value is over this limit, the behavior will be the same as defined in addCustomParameter.

        Parameters:
        message - The error message to be reported.
        params - Custom parameters to include in the traced error. May be null.
        expected - true if this error is expected, false otherwise.
        Since:
        3.38.0

      • noticeError

        public static void noticeError​(java.lang.String message,
                               boolean expected)
        Notice an error and report it to New Relic. If this method is called within a transaction, the error message will be reported with the transaction when it finishes. If it is invoked outside of a transaction, a traced error will be created and reported to New Relic. If noticeError is invoked multiple times while in a transaction, only the last error will be reported. Expected errors do not increment an application's error count or contribute towards its Apdex score.
        Parameters:
        message - Message to report with a transaction when it finishes.
        expected - true if this error is expected, false otherwise.
        Since:
        3.38.0

      • addCustomParameter

        public static void addCustomParameter​(java.lang.String key,
                                      java.lang.Number value)
        Add a key/value pair to the current transaction. These are reported in errors, transaction traces, and transaction events. The key and value will only be reported if this call is made within a New Relic transaction.

        Note: The key and value pair will only be reported if the key argument can be represented in 255 bytes when encoded with UTF-8 encoding.

        Parameters:
        key - Custom parameter key.
        value - Custom parameter value.
        Since:
        1.3.0

      • addCustomParameter

        public static void addCustomParameter​(java.lang.String key,
                                      java.lang.String value)
        Add a key/value pair to the current transaction. These are reported in errors, transaction traces, and transaction events. The key and value will only be reported if this call is made within a New Relic transaction.

        Note: The key and value pair will only be reported if the key argument can be represented in 255 bytes when encoded with UTF-8 encoding. The value argument will be truncated, by stripping characters, to fit in 255 bytes, encoded using UTF-8 encoding.

        Parameters:
        key - Custom parameter key.
        value - Custom parameter value.
        Since:
        1.3.0

      • addCustomParameter

        public static void addCustomParameter​(java.lang.String key,
                                      boolean value)
        Add a key/value pair to the current transaction. These are reported in errors, transaction traces, and transaction events. The key and value will only be reported if this call is made within a New Relic transaction.

        Note: The key and value pair will only be reported if the key argument can be represented in 255 bytes when encoded with UTF-8 encoding.

        Parameters:
        key - Custom parameter key.
        value - Custom parameter value.
        Since:
        6.1.0

      • addCustomParameters

        public static void addCustomParameters​(java.util.Map<java.lang.String,​java.lang.Object> params)
        Add key/value pairs to the current transaction. These are reported in errors, transaction traces, and transaction events. The key and value will only be reported if this call is made within a New Relic transaction.

        Note: The key and value pairs will only be reported if the key argument can be represented in 255 bytes when encoded with UTF-8 encoding. The value argument will be truncated, by stripping characters, to fit in 255 bytes, encoded using UTF-8 encoding.

        Parameters:
        params - Custom parameters to include.
        Since:
        4.12.0

      • setUserId

        public static void setUserId​(java.lang.String userId)
        Sets the user ID for the current transaction by adding the "enduser.id" agent attribute. It is reported in errors and transaction traces. When high security mode is enabled, this method call will do nothing.
        Parameters:
        userId - The user ID to report. If it is a null or blank String, the "enduser.id" agent attribute will not be included in the current transaction and any associated errors.
        Since:
        8.1.0

      • setTransactionName

        public static void setTransactionName​(java.lang.String category,
                                      java.lang.String name)
        Set the name of the current transaction.
        Parameters:
        category - Metric category. If the input is null, then the default will be used.
        name - The name of the transaction starting with a forward slash. example: /store/order
        Since:
        1.3.0

      • ignoreTransaction

        public static void ignoreTransaction()
        Ignore the current transaction.
        Since:
        1.3.0

      • ignoreApdex

        public static void ignoreApdex()
        Ignore the current transaction for calculating Apdex score.
        Since:
        1.3.0

      • setRequestAndResponse

        public static void setRequestAndResponse​(Request request,
                                         Response response)
        Sets the request and response instances for the current transaction. Use this API to generate web transactions for custom web request dispatchers. Only the first call to setRequestAndResponse will take effect.
        Parameters:
        request - The current transaction's request.
        response - The current transaction's response.
        Since:
        2.21.0

      • getBrowserTimingHeader

        public static java.lang.String getBrowserTimingHeader()
        Get the RUM JavaScript header for the current web transaction.
        Returns:
        RUM JavaScript header for the current web transaction.
        Since:
        2.21.0

      • getBrowserTimingHeader

        public static java.lang.String getBrowserTimingHeader​(java.lang.String nonce)
        Get the RUM JavaScript header for the current web transaction.
        Parameters:
        nonce - a random per-request nonce for sites using Content Security Policy (CSP)
        Returns:
        RUM JavaScript header for the current web transaction.
        Since:
        7.6.0

      • getBrowserTimingFooter

        public static java.lang.String getBrowserTimingFooter()
        Get the RUM JavaScript footer for the current web transaction.
        Returns:
        RUM JavaScript footer for the current web transaction.
        Since:
        2.21.0

      • getBrowserTimingFooter

        public static java.lang.String getBrowserTimingFooter​(java.lang.String nonce)
        Get the RUM JavaScript footer for the current web transaction.
        Parameters:
        nonce - a random per-request nonce for sites using Content Security Policy (CSP)
        Returns:
        RUM JavaScript footer for the current web transaction.
        Since:
        7.6.0

      • setUserName

        public static void setUserName​(java.lang.String name)
        Set the user name to associate with the RUM JavaScript footer for the current web transaction. If high security mode is enabled, this method call does nothing.

        Note: The user name argument has a limit of 255 bytes, encoded with UTF-8 encoding. A name that requires more than 255 bytes will be truncated, by stripping characters, to fit in 255 bytes.

        Parameters:
        name - User name to associate with the RUM JavaScript footer.
        Since:
        2.21.0

      • setAccountName

        public static void setAccountName​(java.lang.String name)
        Set the account name to associate with the RUM JavaScript footer for the current web transaction.

        Note: The account name argument has a limit of 255 bytes, encoded with UTF-8 encoding. A name that requires more than 255 bytes will be truncated, by stripping characters, to fit in 255 bytes.

        Parameters:
        name - Account name to associate with the RUM JavaScript footer.
        Since:
        2.21.0

      • setProductName

        public static void setProductName​(java.lang.String name)
        Set the product name to associate with the RUM JavaScript footer for the current web transaction.

        Note: The product name argument has a limit of 255 bytes, encoded with UTF-8 encoding. A name that requires more than 255 bytes will be truncated, by stripping characters, to fit in 255 bytes.

        Parameters:
        name - Product name to associate with the RUM JavaScript footer.
        Since:
        2.21.0

      • setAppServerPort

        public static void setAppServerPort​(int port)
        Set the app server port which is reported to RPM.
        Parameters:
        port - the app server port
        Since:
        3.36.0

      • setServerInfo

        public static void setServerInfo​(java.lang.String dispatcherName,
                                 java.lang.String version)
        Set the dispatcher name and version which is reported to RPM.
        Parameters:
        dispatcherName - the dispatcher name that is reported to RPM
        version - the version that is reported to RPM
        Since:
        3.36.0

      • setInstanceName

        public static void setInstanceName​(java.lang.String instanceName)
        Set the instance name in the environment. A single host:port may support multiple JVM instances. The instance name is intended to help the customer identify the specific JVM instance.
        Parameters:
        instanceName - the instance name to set in the environment
        Since:
        3.36.0

      • setErrorGroupCallback

        public static void setErrorGroupCallback​(ErrorGroupCallback errorGroupCallback)
        Registers an ErrorGroupCallback that's used to generate a grouping key for the supplied error. This key will be used to group similar error messages on the Errors Inbox UI. If the errorGroupCallback instance is null no grouping key will be generated.
        Parameters:
        errorGroupCallback - the ErrorGroupCallback used to generate grouping keys for errors
        Since:
        8.10.0