In order to monitor any application on Linux using a language that can import C libraries, you must:
- Create a config using
newrelic_new_app_config()
, connect to the daemon usingnewrelic_init()
, and connect your application usingnewrelic_create_app()
. For more information, see the C SDK installation procedures. - 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 New Relic. You can also instrument segments of a transaction and errors.
Instrument a transaction
To instrument a transaction so you can monitor it, 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.
-
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");
- 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:
- External services using external segments
- Custom segments for arbitrary code
- Datastores using datastore segments
- Slow query traces (SQL databases only)
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 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:
- Instrument a transaction.
- Create a
newrelic_external_segment_params_t
that describes the external segment, supplying the required parameters. -
Add
newrelic_start_external_segment()
immediately before the function you want to monitor, supplying the required parameters. - 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 Transactions page.
To instrument a custom segment, wrap the New Relic functions that start and stop instrumentation around the function you want to monitor:
- Instrument a transaction.
- Add
newrelic_start_segment()
immediately before the function you want to monitor, supplying the required parameters. -
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 New Relic. You can also view datastore segments as a
databaseDuration
attribute of APMTransaction
events.To instrument a datastore segment, wrap the New Relic functions that start and stop instrumentation around the function you want to monitor:
- Instrument a transaction.
- Create a
newrelic_datastore_segment_params_t
that describes the datastore segment. - Add
newrelic_start_datastore_segment()
immediately before the function you want to monitor, supplying the required parameters. - 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:
- Enable slow query tracing by setting
transaction_tracer.datastore_reporting.enabled
totrue
. - 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 New Relic.
For more information, see the C SDK installation procedures as well as the C SDK
libnewrelic.h
documentation on GitHub. - Enable slow query tracing by setting
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 New Relic. 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 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:
- Start a transaction.
- Record an error with
newrelic_notice_error()
, supplying the required parameters. - 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.
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.