newrelic_record_datastore_segment

newrelic_record_datastore_segment(callable $func, array $parameters)
Records a datastore segment.

Requirements

Agent version 7.5.0.199 or higher.

Description

Records a datastore segment. Datastore segments appear in the Breakdown table and Databases tab of the Transactions page in the New Relic UI.

This function allows an unsupported datastore to be instrumented in the same way as the PHP agent automatically instruments its supported datastores.

Parameters

Parameter Description

$callback

callable

Required. The function that should be timed to create the datastore segment.

$parameters

array

Required. An associative array of parameters describing the datastore call.

The supported keys in the $parameters array are as follows:

Key Description

product

string

Required. The name of the datastore product being used: for example, MySQL to indicate that the segment represents a query against a MySQL database.

collection

string

Optional. The table or collection being used or queried against.

operation

string

Optional. The operation being performed: for example, select for an SQL SELECT query, or set for a Memcached set operation.

While operations may be specified with any case, New Relic suggests using lowercase to better line up with the operation names used by the PHP agent's automated datastore instrumentation.

host

string

Optional. The datastore host name.

portPathOrId

string

Optional. The port or socket used to connect to the datastore.

databaseName

string

Optional. The database name or number in use.

query

string

Optional. The query that was sent to the server.

For security reasons, this value is only used if you set product to a supported datastore. This allows the agent to correctly obfuscate the query. The supported product values (which are matched in a case insensitive manner) are: MySQL, MSSQL, Oracle, Postgres, SQLite, Firebird, Sybase, and Informix.

inputQueryLabel

string

Optional. The name of the ORM in use (for example: Doctrine).

inputQuery

string

Optional. The input query that was provided to the ORM.

For security reasons, and as with the query parameter, this value will be ignored if the product is not a supported datastore.

Return value(s)

The return value of $callback is returned. If an error occurs, false is returned, and an error at the E_WARNING level will be triggered.

Example(s)

Instrumenting an unsupported NoSQL datastore

To instrument a hypothetical NoSQL datastore called Bucket that exposes a get method, the following code would create a datastore metric that would show up in the New Relic UI:

$bucket = new Bucket($host, $port);
$id = 12345;

$value = newrelic_record_datastore_segment(function () use ($bucket, $id) {
    return $bucket->get($id);
}, array(
    'product'      => 'Bucket',
    'collection'   => $id,
    'operation'    => 'get',
    'host'         => $host,
    'portPathOrId' => $port,
));

Instrumenting an unsupported SQL client library

To record a query for an unsupported MySQL client library with the query obfuscated and attached to the segment:

$sql = 'SELECT * FROM table';
$stmt = $db->prepare($sql);

$result = newrelic_record_datastore_segment(function () use ($stmt) {
    return $stmt->execute();
}, array(
    'product'      => 'MySQL',
    'collection'   => 'table',
    'operation'    => 'select',
    'host'         => $host,
    'portPathOrId' => $port,
    'databaseName' => 'dbname',
    'query'        => $query,
));

For more help

Recommendations for learning more: