---
title: newrelic_record_datastore_segment (PHP agent API)
source: https://docs.newrelic.com/docs/apm/agents/php-agent/php-agent-api/newrelic_record_datastore_segment
---

## Syntax

```php
newrelic_record_datastore_segment(callable $func, array $parameters)
```

Records a datastore segment.

## Requirements [#require]

Agent version [7.5.0.199](https://docs.newrelic.com/docs/release-notes/agent-release-notes/php-release-notes/php-agent-750199) or higher.

## Description [#desc]

Records a datastore segment. Datastore segments appear in the **Breakdown table** and **Databases** tab of the [Transactions page](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/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](https://docs.newrelic.com/docs/agents/php-agent/getting-started/php-agent-compatibility-requirements#databases).

## Parameters [#para]

| 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.                                                                                                                                                                                         |

> #### ⚠️ IMPORTANT
>
> The _string_ arguments used in the `$parameters` array should not contain the special character '/'.

## Return values [#return]

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.

## Examples [#examples]

### Instrumenting an unsupported NoSQL datastore [#unsupported-nosql]

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:

```php
$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 [#unspported-sql]

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

```php
$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,
));
```