Guide to using the C SDK API

EOL NOTICE

From April 2022, we don't support the C SDK capability. For more details, see our Support Forum post.

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:

Check the C SDK compatibility and requirements for your app.
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 New Relic, 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.

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 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: `newrelic_add_attribute_int()` `newrelic_add_attribute_string()` `newrelic_add_attribute_long()` `newrelic_add_attribute_double()`

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. Typically metric data has a longer retention period than event data.

The C SDK provides a custom events API that allows you to send custom events to New Relic. 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 custom data requirements and limits for guidance on what values are and are not allowed inside your custom event. For more information, see Custom events in APM.

Tip

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

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.

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.
Important
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.	`newrelic_record_custom_event()`
Enhance your custom event with additional metadata.	Add custom event attributes to your custom event based on type: `newrelic_custom_event_add_attribute_double()` `newrelic_custom_event_add_attribute_int()` `newrelic_custom_event_add_attribute_long()` `newrelic_custom_event_add_attribute_string()`
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.	`newrelic_record_custom_metric()`

Monitor desktop browser performance

To monitor desktop browser performance for your application, install the browser agent 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.