• EnglishEspañol日本語한국어Português
  • Log inStart now

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


Start timing a non-web transaction


Stop timing a transaction


Prevent a transaction from reporting to New Relic


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


Stop timing a 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:

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


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.

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.


Timestamp and add the custom event to the current transaction so you can query or visualize it.


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.


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.


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.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.