| title | tags | metaDescription | redirects | freshnessValidatedDate | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
Guide to using the C SDK API |
|
Quick reference of New Relic C SDK API calls you can use to manually instrument your application's code. |
|
never |
<Callout variant="important" title="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.
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:
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.
<th>
Use this method...
</th>
</tr>
<td>
[`newrelic_start_web_transaction()`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#adbf7c1fa57482f6e0a7f291e0b5ec80f)
</td>
</tr>
<tr>
<td>
Start timing a non-web transaction
</td>
<td>
[`newrelic_start_non_web_transaction()`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#a88648cc287f8d7e371139dc3809b7afb)
</td>
</tr>
<tr>
<td>
Stop timing a transaction
</td>
<td>
`newrelic_end_transaction()`
</td>
</tr>
<tr>
<td>
Prevent a transaction from reporting to New Relic
</td>
<td>
[`newrelic_ignore_transaction()`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#a7b41f8690c3b2b7e024a16fa4bb59320)
</td>
</tr>
| If you want to... |
|---|
| Start timing a web transaction |
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)
<th>
Use this method...
</th>
</tr>
<td>
```c
newrelic_start_datastore_segment()
newrelic_start_external_segment()
newrelic_start_segment()
```
</td>
</tr>
<tr>
<td>
Stop timing a segment
</td>
<td>
`newrelic_end_segment()`
</td>
</tr>
<tr id="async">
<td>
Manually parent segments
</td>
<td>
`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](https://github.com/newrelic/c-sdk/blob/master/GUIDE.md#manual-segment-parenting).
</td>
</tr>
| If you want to... |
|---|
| Start timing a segment |
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().
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.
<th>
Use this method...
</th>
</tr>
<td>
Add custom attributes to your transaction based on their type:
* [`newrelic_add_attribute_int()`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#a1f0fe987526c023a2101111b7ee557b3)
* [`newrelic_add_attribute_string()`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#a9eac445521cecdd046520d2178f232a0)
* [`newrelic_add_attribute_long()`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#a2a082a144cff6c805c6373d9d4f1f551)
* [`newrelic_add_attribute_double()`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#abfe6f64a8eec7d60d8588f8969781d34)
</td>
</tr>
| If you want to... |
|---|
| Add metadata (such as your customer's account name or subscription level) to your transaction |
Use these methods to collect data about your app's connections to other apps or databases:
<th>
Use this method...
</th>
</tr>
<td>
Follow the procedures to enable and instrument [distributed tracing](/docs/agents/c-sdk/instrumentation/enable-distributed-tracing-your-c-applications).
</td>
</tr>
<tr>
<td>
Time a call to an external resource (such as an external service, database server, or message queue)
</td>
<td>
Follow the procedures to [Instrument calls to external segments](/docs/instrument-your-app-c-sdk#external-segments).
</td>
</tr>
| If you want to... |
|---|
| See the path that a request takes as it travels through a distributed system |
The C SDK detects errors automatically. If you want to change the way it reports errors to New Relic, change the error collector configuration.
<th>
Use this method...
</th>
</tr>
<td>
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](/docs/generate-logs-troubleshooting-c-sdk).
</td>
</tr>
<tr>
<td>
Report an error
</td>
<td>
[`newrelic_notice_error()`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#a02a9a959015a0ca68ce11c750f690475)
</td>
</tr>
| If you want to... |
|---|
| Set logging levels for 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.
```
// 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](/docs/insights/insights-data-sources/custom-data/insights-custom-data-requirements-limits) for guidance on what values are and are not allowed inside your custom event. For more information, see [Custom events in APM](/docs/insights/insights-data-sources/custom-data/insert-custom-events-new-relic-apm-agents).
<Callout variant="tip">
If you created a custom event but need to remove it before the transaction has ended, use `newrelic_discard_custom_event(&custom_event);`.
</Callout>
<Collapser id="custom-attributes" title="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:
<a href="https://newrelic.github.io/c-sdk/libnewrelic_8h.html#add4646ef16f4f0c9b75934cf96909655">newrelic_custom_event_t</a>* custom_event=0;
custom_event = newrelic_create_custom_event("aTypeForYourEvent");
<a href="https://newrelic.github.io/c-sdk/libnewrelic_8h.html#a1f0fe987526c023a2101111b7ee557b3">newrelic_custom_event_add_attribute_int</a>(custom_event, "keya", 42);
<a href="https://newrelic.github.io/c-sdk/libnewrelic_8h.html#a2a082a144cff6c805c6373d9d4f1f551">newrelic_custom_event_add_attribute_long</a>(custom_event, "keyb", 84);
<a href="https://newrelic.github.io/c-sdk/libnewrelic_8h.html#abfe6f64a8eec7d60d8588f8969781d34">newrelic_custom_event_add_attribute_double</a>(custom_event, "keyc", 42.42);
<a href="https://newrelic.github.io/c-sdk/libnewrelic_8h.html#a9eac445521cecdd046520d2178f232a0">newrelic_custom_event_add_attribute_string</a>(custom_event, "keyd", "A string");
<a href="https://newrelic.github.io/c-sdk/libnewrelic_8h.html#a4af935da4651e398e3773c148e8db814">newrelic_record_custom_event</a>(txn, &custom_event);
```
For more information, see the documentation about [custom attributes](/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes).
<Collapser id="custom-metrics" title="Custom metrics"
The C SDK provides the [`newrelic_record_custom_metric()`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#aee71182588ace508cc816044d2024ff3) 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.
<Callout variant="important">
Always prefix custom metric names with `Custom/`.
</Callout>
For example:
```c
// 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](/docs/agents/manage-apm-agents/agent-data/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.
<th>
Use this method...
</th>
</tr>
<td>
[`newrelic_create_custom_event()`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#a83b5b78623bcefda6d4e1e6d207f7b7a)
</td>
</tr>
<tr>
<td>
Timestamp and add the custom event to the current transaction so you can query or visualize it.
</td>
<td>
[`newrelic_record_custom_event()`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#a4af935da4651e398e3773c148e8db814)
</td>
</tr>
<tr>
<td>
Enhance your custom event with additional metadata.
</td>
<td>
Add custom event attributes to your custom event based on type:
* [`newrelic_custom_event_add_attribute_double()`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#af84bdcea08fbefb2023b47907a304188)
* [`newrelic_custom_event_add_attribute_int()`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#ade406683e960b53a1b4a2d832872ab1a)
* [`newrelic_custom_event_add_attribute_long()`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#a0ee8f438644f7699c8427fe231d7ffc1)
* [`newrelic_custom_event_add_attribute_string()`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#aa59111072aaa6d539adf6745c5dbfaa4)
</td>
</tr>
<tr>
<td>
Discard a custom event after it was created, but before its transaction has ended, to avoid reporting it to New Relic.
</td>
<td>
[`newrelic_discard_custom_event`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#a15aa71f0d4fac8fec8f4105c2c1d8dde)
This is necessary to free the allocated memory for your unwanted custom event in order to avoid leaks in your program.
</td>
</tr>
<tr>
<td>
Report a custom performance duration that you can search or chart.
</td>
<td>
[`newrelic_record_custom_metric()`](https://newrelic.github.io/c-sdk/libnewrelic_8h.html#aee71182588ace508cc816044d2024ff3)
</td>
</tr>
| If you want to... |
|---|
| Create a custom event to populate with a timestamp and attributes. |
To monitor desktop browser performance for your application, install the browser agent using the copy/paste method.
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.