Instrument your app with the C SDK

In order to monitor any application on Linux using a language that can import C libraries, you must:

  1. Create a config using newrelic_new_app_config(), connect to the daemon using newrelic_init(), and connect your application using newrelic_create_app(). For more information, see the C SDK installation procedures.
  2. Manually instrument transactions using the C SDK, as described in this document.

New Relic defines a web or non-web transaction as one logical unit of work in a software application. After you manually instrument transactions in your source code by adding New Relic functions, you can view the data on the Transactions page in the New Relic UI. You can also instrument segments of a transaction and errors so you can monitor them in the New Relic UI.

Instrument a transaction

To instrument a transaction so you can monitor it in the New Relic UI, wrap the New Relic functions that start and stop instrumentation around the transaction. The function that you use depends on whether you want to instrument a web or non-web transaction.

In the following example, the app is created after a call to newrelic_create_app(). For more information, see the C SDK installation procedures as well as the C SDK libnewrelic.h documentation on GitHub.

  1. Add the following code immediately before the transaction that you want to monitor, supplying the required parameters.

    For web transactions:

    // Example code:
newrelic_txn_t *txn;
/* ... */
txn = newrelic_start_web_transaction(app, "NAME_YOUR_TRANSACTION");

    For non-web transactions:

    // Example code:
newrelic_txn_t *txn;
/* ... */
txn = newrelic_start_non_web_transaction(app, "NAME_YOUR_TRANSACTION");
  2. Add newrelic_end_transaction() immediately after the web or non-web transaction that you want to monitor, supplying a pointer the transaction, &txn, as a parameter.

Instrument segments

Once you instrument a transaction using the C SDK, you can instrument segments in it. By instrumenting segments, you can monitor the individual functions and calls inside a transaction.

Segments example

You have a transaction associated with a checkout process, which processes both shipping information and credit card information. You can instrument your application to break that transaction up into two segments: one segment for shipping and one segment for payment.

You can instrument segments to monitor the following kinds of calls:

For more information, see the C SDK installation procedures as well as the C SDK libnewrelic.h documentation on GitHub.

Instrument calls to external services

To monitor calls to external services, instrument external segments that are within an instrumented transaction. External segments appear in the New Relic UI in the APM Transactions page's Breakdown table and the External services page.

To instrument an external segment, wrap the New Relic functions that start and stop instrumentation around the function you want to monitor:

  1. Instrument a transaction.
  2. Create a newrelic_external_segment_params_t that describes the external segment, supplying the required parameters.

  3. Add newrelic_start_external_segment() immediately before the function you want to monitor, supplying the required parameters.

  4. Add newrelic_end_segment() immediately after the function you want to monitor, supplying the required parameters.

For more information, see the C SDK installation procedures as well as the C SDK libnewrelic.h documentation on GitHub.

Instrument calls to arbitrary code (custom segments)

To monitor calls to arbitrary code, instrument custom segments that are within an instrumented transaction. Custom segments appear in the Breakdown table on the APM Transactions page.

To instrument a custom segment, wrap the New Relic functions that start and stop instrumentation around the function you want to monitor:

  1. Instrument a transaction.
  2. Add newrelic_start_segment() immediately before the function you want to monitor, supplying the required parameters.

  3. Add newrelic_end_segment() immediately after the function you want to monitor, supplying the required parameters.

For more information, see the C SDK installation procedures as well as the C SDK libnewrelic.h documentation on GitHub.

Instrument calls to datastores

To monitor calls to datastores, instrument the datastore segments within an instrumented transaction. Datastore segments appear in the Breakdown table and Databases tab on the Transactions page in the New Relic UI. You can also view datastore segments in New Relic Insights as a databaseDuration attribute of APM Transaction events.

To instrument a datastore segment, wrap the New Relic functions that start and stop instrumentation around the function you want to monitor:

  1. Instrument a transaction.
  2. Create a newrelic_datastore_segment_params_t that describes the datastore segment.
  3. Add newrelic_start_datastore_segment() immediately before the function you want to monitor, supplying the required parameters.
  4. Add newrelic_end_segment() immediately after the function you want to monitor, supplying the required parameters.

For more information, see the C SDK installation procedures as well as the C SDK libnewrelic.h documentation on GitHub.

To configure how the database name and database instance are reported, use the newrelic_datastore_segment_config_t.

Report slow query traces for datastore segments (SQL only)

You can report slow query traces for SQL databases only.

To report slow query trace data for datastore segments that take longer than the time you specify, enable these settings in your newrelic_app_config_t:

  1. Enable slow query tracing by setting transaction_tracer.datastore_reporting.enabled to true.
  2. To set the threshold, add a length of time in microseconds to transaction_tracer.datastore_reporting.threshold_us.

Then, if a datastore call takes longer than the threshold, the C SDK reports it as a slow query. To view slow query trace details, use the Databases and Slow queries pages in the New Relic UI.

For more information, see the C SDK installation procedures as well as the C SDK libnewrelic.h documentation on GitHub.

Instrument errors

In order to use the C SDK to monitor errors in transactions, you must manually instrument your source code by adding the newrelic_notice_error() function to it.

Transaction errors and error traces appear on the Error analytics page in the New Relic UI. The C SDK reports the total number of errors and up to 100 error traces per minute. You can also view, query, and visualize transaction errors in New Relic Insights as APM TransactionError events.

To include function calls in error traces, use GNU's -rdynamic linker flag to link your apps when compiling. The -rdynamic linker flag gives you more meaningful error traces.

To instrument errors in transactions:

  1. Start a transaction.
  2. Record an error with newrelic_notice_error(), supplying the required parameters.
  3. End the transaction, supplying the required parameters.

For more information, see the C SDK installation procedures as well as the C SDK libnewrelic.h documentation on GitHub.

Avoid metric grouping issues

When an account or application sends many individual metrics that could be better managed in groups, New Relic uses the term metric grouping issue or MGI to describe this situation. If your application sends unnecessarily large amounts of data to New Relic, this reduces the effectiveness of charts, tables, and reports in the New Relic user interface.

Metric grouping issues occur most commonly with web transactions, especially if the name is based on URLs. To help prevent this situation, see Metric grouping issues.

For more help

Recommendations for learning more: