Introduction to the New Relic Agent SDK

As a standard security measure for data collection, New Relic requires that your application server supports SHA-2 (256-bit). SHA-1 is not supported.

The SDK dynamically links to the openssl and cURL libraries. The SDK works with the following libraries:

Some portions of the Agent SDK's transaction library are thread-safe, while others are not. The following activities should be considered thread-safe:

• Starting transactions on different threads

• Starting, modifying, and ending segments on different threads for different transactions

  The following activities should not be considered thread-safe:

• Modifying and ending a single transaction from different threads

• Starting, modifying, and ending segments on different threads within the same transaction

By default, the Agent SDK enables HTTPS for communication between the SDK and New Relic. However, developers are responsible for obfuscating or hiding any sensitive data that should not appear in the New Relic UI. For example, you may want to hide certain parameters inside a request URL or database query.

Use caution when naming custom metrics, transactions, and segments. Issues come about when the granularity of names is too fine, resulting in metric explosion, which can impact the performance of both your application and New Relic. Your application may also get blacklisted. For more information, including best practices, see Metric grouping issues.

The Agent SDK consists of three C++ libraries and three C header files. To install the SDK:

1. Download the SDK to your development machine (Linux only).

2. Unzip nr_agent_sdk-<version>-beta.<architecture>.tar.gz to a working directory.

3. For instructions on implementing the Agent SDK, read the AgentSDK.pdf included in the download.

   New Relic's public repo on Github includes Agent SDK sample wrappers and code.

The New Relic Agent SDK uses log4cplus for logging. This provides flexibility into log levels, log file locations, etc.

The SDK searches for a log4cplus.properties file in this order:

1. The location specified by NEWRELIC_LOG_PROPERTIES_FILE environment variable

2. Your $HOME/.newrelic directory

3. The current working directory

   To configure logging:

4. Copy the config/log4cplus.properties file to one of the locations specified above.

5. Optional: Modify the log4cplus.properties file by following the instructions at http://sourceforge.net/p/log4cplus/wiki/Home/.

All functions in the SDK return integers or longs. Any positive number indicates success and any negative number indicates a failure. For a list of all error codes, see the New Relic header files for a list of all error codes.

To measure transactions and important segments of code in your application:

1. Include the newrelic_transaction.h and newrelic_common.h header files.

2. Link your application to the libnewrelic-transaction and libnewrelic-common libraries.

3. Create a transaction; for example:

   long transaction_id = newrelic_transaction_begin();

   Copy

4. Optional: Set a name for the transaction any time before the transaction ends. For example:

   int return_code = newrelic_transaction_set_name
       (
       transaction_id,
       "create_account"
       );

   Copy

5. Measure segments; for example:

   long segment_id = newrelic_segment_generic_begin
       (
       transaction_id,
       parent_id,
       "check_if_account_exists"
       );
       <call check_if_account_exists>
       int return_code = newrelic_segment_end
       (
       transaction_id,
       segment_id
       );

   Copy

6. Optional: If this is not a web transaction, set the transaction type any time before the transaction ends. For example:

   newrelic_transaction_set_type_other(transaction_id);

   Copy

7. End your transaction; for example:

   int error_code = newrelic_transaction_end(transaction_id);

   Copy

8. Start your app, and then wait a few minutes to start seeing data in your New Relic dashboards.

The New Relic Agent SDK is designed to have a minimal impact on your system's performance. However, in addition to the default settings, you can use these controls to limit or disable data collection.

newrelic_enable_instrumentation(0);

newrelic_transaction_set_threshold(transaction_id, 5000);

// Only collect up to 50 trace segments
newrelic_transaction_set_max_trace_segments(transaction_id, 50);

In order to maintain communication with New Relic, the Agent SDK requires a thread to be started that harvests data once per minute. This means that your app will need to be able to start a thread that runs continuously as long as transactions are being executed.

For some languages, this is simple to do. For others, there is no mechanism to start a thread within the same process running your web transactions. For example, if you are running perl apps through Apache, then each perl script is a short-lived process that exits upon completion of the script. There is no ability to start up a thread that lives beyond the life of the script.

To solve this problem, New Relic designed the SDK so that your agent can run in two different modes: daemon-mode or embedded-mode.

• In daemon-mode you will run the newrelic-collector-client-daemon that came with the Agent SDK as a standalone process. The daemon will collect and send data to New Relic.
• In embedded-mode your application will start a thread that has the same responsibilities as the daemon. However, it will run within the same process as your transactions.

Adjust these values in your configuration as applicable for your selected mode (daemon-mode or embedded-mode).

The SDK daemon will run with the privileges of the application starting it, which may be elevated. For example, if the daemon is started by Apache, it may run as root.

1. Set the required environment variables before launching the daemon, including:

   export NEWRELIC_LICENSE_KEY=<your license key>
       export NEWRELIC_APP_NAME="Hello World"
       export NEWRELIC_APP_LANGUAGE="Perl"
       export NEWRELIC_APP_LANGUAGE_VERSION="5.5"

   Copy

   Start the daemon by executing the following command in a terminal window:

   ./newrelic-collector-client-daemon

   Copy

2. Start your app, and then wait a few minutes to start seeing data in New Relic.

To run in embedded-mode, embed the collector client in your app by following these steps:

1. Include the newrelic_collector_client.h and newrelic_common.h header files.

2. Link your application to the libnewrelic-common and libnewrelic-collector-client libraries.

3. Optional: Create a function to receive status change notifications. For example:

   void newrelic_status_update(int status)
       {
       if (status == NEWRELIC_STATUS_CODE_SHUTDOWN)
       {
       // do something when the agent shuts down
       }
       }
       newrelic_register_status_callback(newrelic_status_update);

   Copy

4. To send data to New Relic when transactions are completed, register a callback that has already been defined inside the libnewrelic-collector-client library:

   newrelic_register_message_handler(newrelic_message_handler);

   Copy

5. Initialize the library. For example:

   newrelic_init
       (
       my_license_key_string,
       "Hello World", 
       "Perl", 
       "5.5"
       );

   Copy

6. Optional: Shut down the connection to New Relic. For example:

   newrelic_request_shutdown("insert your reason here");

   Copy

7. Start your app, and then wait a few minutes to start seeing data in New Relic.

New Relic APM automatically generates traces when transactions exceed the threshold, which defaults to two seconds. A maximum of two traces will be sent to New Relic per minute. To modify the threshold for any of your application's transactions, change your Apdex settings.

Custom metrics give you a way to record arbitrary metrics about your application. You can also instrument your code, which will report performance metrics automatically whenever that code is executed. With a custom metric, you provide the value to be recorded for a specified metric name; for example:

newrelic_record_metric("ActiveUsers", 25);

To view custom metrics, create a custom dashboard.

A query trace is automatically generated for each Datastore segment. Every minute the agent sends several of these traces to New Relic APM. The selected traces will represent the worst performing query statements during that minute.

Your database code may contain sensitive information that you do not want or need to send to New Relic APM. By default, the Agent SDK obfuscates your query strings. It uses a basic literal replacement obfuscator that strips the string literals and numeric sequences, and then replaces them with the ? character. For example:

SELECT * FROM table WHERE ssn=‘000-00-0000’

Obfuscates to:

SELECT * FROM table WHERE ssn=?

For more information, see Security options for transaction traces.

Apdex T is the response time threshold used to measure customer satisfaction. The transaction trace threshold is calculated as four times the Apdex T value. The default Apdex T value is 0.5 seconds.

To change the Apdex T value across all transactions of your application, use the environment variable NEWRELIC_APP_SERVER_APDEX_T. If you do not set this environment variable, New Relic uses the default.

In order to build a transaction trace, you need to provide information to the SDK about the relationships between segments. To accomplish this, your agent needs to pass parent IDs when starting new segments. Depending on your language, you might be able to take advantage of the SDK's auto-scoping feature.

Auto-scoping can be used to automatically identify the transaction ID and parent ID of a newly started segment. It works by keeping track of the last segment started within the current thread (using thread local storage). This is useful, for example, when a transaction runs uninterrupted from beginning to end within the same thread. For more information about threading considerations, see the threading section below.

If auto-scoping does not work, you will need to find a way to keep track of the current call stack. A simple way to do this is to keep a stack of segment IDs in memory. When a new segment starts, add it to the stack. When a segment ends, remove it from the stack. The challenge then becomes one of identifying where to store the stack. Here are some options:

• You can use a global web context object if your language supports it.

• You can use thread local storage.

• You can create a global map of running transactions.

  Recommendation: For segments at the transaction's root, set the parent_segment_id to NEWRELIC_ROOT_SEGMENT.

Recommendation: Name the transactions based on their purpose, but use caution.

Issues arise when the granularity of the transaction name is too fine. This results in hundreds if not thousands of different transactions. If you name transactions poorly, your application may get blacklisted due to too many metrics being sent to New Relic.

A basic rule is to name transactions based on the controller action rather than the URL. For more information, see Metric grouping issues.

Different languages support different threading models. Depending on the characteristics of your threading model, you will need to consider how your threads will interact with the SDK.

Transaction events are not reported to Insights, and the SDK does not provide an API call to report custom events to Insights. You must insert custom events via the Insights API.

Known bugs in the New Relic Agent SDK include:

• You will see an error page if you select Settings directly from Applications > (selected app).
• You will also see an error page if you select Settings > Application.

Released on: Friday, June 12, 2015 - 11:15

Fixes:

• We fixed a memory leak that occurs while communicating with New Relic.
• Calls of newrelic_segment_external_begin() no longer create duplicate external metrics. Previously, one call would cause two external metrics to display in the breakdown table. We removed the less informative of the two metrics that appear.
• Corrected the parameter definition for newrelic_enable_instrumentation(). You should pass 0 to disable and 1 to enable instrumentation. The old comment had those instructions reversed. Also, the docs site example used a boolean rather than an integer, and that has been corrected.

Released on: Monday, November 10, 2014 - 17:46

Fixes:

Changed the way we initialize our libraries to avoid potential crashes and/or undefined behavior due to static initialization reordering.

Released on: Tuesday, November 4, 2014 - 11:11

Fixes:

The Agent SDK will now work on systems that have libcurl built against an SSL library other than OpenSSL.

Improvements:

Released on: Wednesday, October 15, 2014 - 17:18

This release changes the Agent SDK's SSL/TLS configuration to disable SSLv3 and always use TLS1.x if SSL is enabled for the agent.

Released on: Friday, October 10, 2014 - 15:02

Fixes:

Fixed memory leak when obfuscating SQL or cleansing a request URL.

Released on: Thursday, October 9, 2014 - 11:54

Improvements:

This release of the Agent SDK is focused around thread safety.

• Modifying and ending a single transaction from different threads is now thread-safe.
• Starting, modifying, and ending segments on different threads within the same transaction is now thread-safe.

Released on: Thursday, September 11, 2014 - 12:42

This release of the Agent SDK is focused around adding support for SQL traces and improving insight gained from transaction traces.

New Features:

• SQL trace aka Slow SQL: The Agent SDK now generates an SQL trace for each instrumented datastore segment. Every minute the agent sends 10 of these traces up to the New Relic service. The traces selected will represent the worst performing SQL statements during that minute.

• Custom SQL obfuscation: SQL is obfuscated by default by replacing string literals and number sequences with the ? character. There is also a way for you to supply the Agent SDK with your own custom obfuscator for a datastore segment.

• SQL trace aggregation: By default, the Agent SDK aggregates SQL traces that have similar SQL statements using the obfuscated SQL. It also provides a way for you to decide how to aggregate these traces.

• SQL statements inside transaction traces: You can also see SQL statements for datastore segments that are part of a transaction trace.

  Note: In high security mode, the Agent SDK will not send any SQL traces nor will it send SQL inside a transaction trace.

Released on: Wednesday, August 13, 2014 - 16:04

New Features:

The Agent SDK now supports high security mode. There is a new local configuration setting that enables high security for the agent. Once enabled, SSL will be enforced and attributes inside transaction traces and traced errors will not be collected.

Note: Server-side high security mode must be enabled via the New Relic web interface before turning it on locally. After local config has changed, the agent must be restarted in order to read setting changes and to create a new connection. For those running a daemon, this means restarting the daemon.

Released on: Monday, July 28, 2014 - 12:42

Notes:

This release of the Agent SDK focuses on providing more insight into your application's overall performance.

New Features:

CPU and memory metrics: The Agent SDK now supports CPU and memory usage. This gives you a better picture of an application's performance and impact on the system. To get started, make an API call to newrelic_record_cpu_usage and newrelic_record_memory_usage whenever you want to see an application's CPU and memory usage at a given time. You can get an overall picture of your application's system performance by periodically making these API calls.

Bug Fixes:

The Agent SDK build script now updates version header files with the latest release version number. Releases used after version 0.6 and before this version were reporting as 0.6. This did not affect user experience, but potentially could have if certain APM features were enabled for future versions of the Agent SDK.