Guide to using the C SDK API

New Relic's C SDK monitors your applications and microservices to help you identify and solve performance issues. C applications run from a compiled, native binary file. In order to monitor transactions, you must manually instrument your code by adding New Relic methods to it.

This guide helps you to decide which method to use. The method's code, required parameters, and examples reside in New Relic's C SDK documentation on GitHub.

Ensure your customization is thread-safe

The C SDK supports instrumentation of multi-threaded applications, but it must be initialized before instrumenting multiple threads. When calling any of the following functions, ensure that they are called on the main thread before any other C SDK functions are called:

Monitor transactions

Before you manually instrument your code to monitor transactions:

  1. Check the C SDK compatibility and requirements for your app.
  2. Make sure you are using the latest version of the C SDK library, and update as needed.
If you want to... Use this method...
Start timing a web transaction newrelic_start_web_transaction()
Start timing a non-web transaction newrelic_start_non_web_transaction()
Stop timing a transaction newrelic_end_transaction()
Prevent a transaction from reporting to New Relic newrelic_ignore_transaction()

Time specific methods using segments

If a transaction is already visible in the New Relic UI, but you do not have enough data about a particular method that was called during that transaction, you can instrument segments. For example, if you want to time a method that has complex logic, you can create a segment for each of the methods in the transaction.

To instrument a method within an existing transaction, create segments for any of the following:

  • External services
  • Functions or other arbitrary blocks of code (using custom segments)
  • Datastores
  • Slow query traces (SQL datastores only)
If you want to... Use this method...
Start timing a segment newrelic_start_datastore_segment()
newrelic_start_external_segment()
newrelic_start_segment()
Stop timing a segment newrelic_end_segment()
Manually parent segments

newrelic_set_segment_parent() and newrelic_set_segment_parent_root()

This is useful, for example, with an asynchronous process when you want to visualize a segment as a child of the transaction's top-level call. For more information, see the manual segment parenting documentation on GitHub.

Segments are recorded on the active transaction. When adding a segment to an active transaction, you need access to the newrelic_txn_t* or transaction pointer, returned by newrelic_start_web_transaction() or newrelic_start_non_web_transaction().

Enhance the metadata of a transaction

You can manage the metadata that New Relic reports for transactions. This is useful when you want a different level of detail for your transactions. For example:

  • If you are experiencing a metric grouping issue, you can change the default names for your transactions to make them more identifiable.
  • If you want to create dashboards for your transactions, you can add custom attributes.
If you want to... Use this method...
Add metadata (such as your customer's account name or subscription level) to your transaction

Add custom attributes to your transaction based on their type:

Instrument calls to external services

Use these methods to collect data about your app's connections to other apps or databases:

If you want to... Use this method...
See the path that a request takes as it travels through a distributed system Follow the procedures to enable and instrument distributed tracing.
Time a call to an external resource (such as an external service, database server, or message queue) Follow the procedures to Instrument calls to external segments.

Collect or log errors

The C SDK detects errors automatically. If you want to change the way it reports errors to New Relic, change the error collector configuration.

If you want to... Use this method...
Set logging levels for your app

Use newrelic_configure_log() to configure the C SDK logs and command-line flags to configure the C daemon logs. For more information, see the C SDK logging documentation.

Report an error newrelic_notice_error()

Send custom data from your app

To record custom data with the C SDK, you can use any of the following methods:

  • Custom events: At New Relic, event data is a fundamental data type. Event data represents a record of a single event at a particular moment in time. This is useful to view or query specific details.
  • Custom event attributes: To include additional metadata about the event, you can add key/value pairs (custom-attributes) to your custom event.
  • Custom metrics: Metric timeslice data is the statistical measure of data that New Relic aggregates so that you can view it in the UI and chart it in Insights. Typically metric data has a longer retention period than event data.
Custom events

The C SDK provides a custom events API that allows you to send custom events to New Relic Insights. To send an event, start a transaction and use the newrelic_create_custom_event and newrelic_record_custom_event functions. For example:

   // txn is a newrelic_txn_t*, created via newrelic_start_web_transaction
   newrelic_custom_event_t* custom_event=0;
   custom_event = newrelic_create_custom_event("aTypeForYourEvent");
   newrelic_record_custom_event(txn, &custom_event);

Be sure to review the Insights custom data requirements and limits for guidance on what values are and are not allowed inside your custom event. For more information, see the documentation about custom events in APM.

If you created a custom event but need to remove it before the transaction has ended, use newrelic_discard_custom_event(&custom_event);.

Custom event attributes

You can also add int, long, double, and char* (string) attributes to your custom event by using the newrelic_custom_event_add_* family of functions. For example:

// Example custom attributes:
newrelic_custom_event_t* custom_event=0;
custom_event = newrelic_create_custom_event("aTypeForYourEvent");

newrelic_custom_event_add_attribute_int(custom_event, "keya", 42);
newrelic_custom_event_add_attribute_long(custom_event, "keyb", 84);
newrelic_custom_event_add_attribute_double(custom_event, "keyc", 42.42);
newrelic_custom_event_add_attribute_string(custom_event, "keyd", "A string");

newrelic_record_custom_event(txn, &custom_event);

For more information, see the documentation about custom attributes.

Custom metrics

The C SDK provides the newrelic_record_custom_metric() function. This allows you to record time-based performance data using an API call, such as:

  • Transaction timing data
  • Computer resource data
  • Subscription or purchasing data

To create a custom metric, provide a name or other identifier and an amount of time in milliseconds to the function, along with the active transaction.

Always prefix custom metric names with Custom/.

For example:

// txn is a newrelic_txn_t*, created via newrelic_start_web_transaction

// Record a metric value of 100ms in the transaction txn
    newrelic_record_custom_metric(txn, "Custom/MyMetric/My_label", 100);

For more information, see Collect custom metrics.

Here are some ways to use your custom data. For code details and examples for these options, see the New Relic globals documentation on GitHub.

If you want to... Use this method...
Create a custom event to populate with a timestamp and attributes. newrelic_create_custom_event()
Timestamp and add the custom event to the current transaction so you can query or visualize it in Insights.

newrelic_record_custom_event()

Enhance your custom event with additional metadata.

Add custom event attributes to your custom event based on type:

Discard a custom event after it was created, but before its transaction has ended, to avoid reporting it to New Relic.

newrelic_discard_custom_event

This is necessary to free the allocated memory for your unwanted custom event in order to avoid leaks in your program.

Report a custom performance duration that you can search or chart in Insights. newrelic_record_custom_metric()

Monitor desktop browser performance

To monitor desktop browser performance for your application, install New Relic Browser using the copy/paste method.

Change configuration settings

Typically the default settings for your application's configuration do not need to be changed. However, when necessary, you can adjust some of the settings. For more information, see the C SDK configuration documentation.

For more help

Recommendations for learning more: