Class NewRelic

java.lang.Object
com.newrelic.api.agent.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

    Modifier and Type Method Description
    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 getBrowserTimingHeader()
    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 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 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 Details

  • Method Details

    • 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 first 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 first 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 first 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 first 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 first 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 first 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
    • 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
    • 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
    • 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
    • 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.

      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