PHP Example for AWS Timestream

Introduction

Although the AWS documentation is fairly extensive, I found it a little difficult to use the AWS Timestream Database product from PHP. I couldn’t find much help, so I thought I’d publish this article in the hope it saves someone a few wasted hours.

Pre-requisite

A functioning PHP environment with the AWS SDK installed.

Client Setup

The following is all the code that is needed to get the client object setup:

$client = new \Aws\TimestreamWrite\TimestreamWriteClient([    
        'version' => 'latest',
        'region' => 'eu-west-1',  
        'credentials' => new \Aws\Credentials\Credentials('**KEY**',
                             '**SECRET**')
    ]);

Note: You should not specify an endpoint for the client.

Writing a Record

This example shows the minimum required to write a record to Timestream. I have used a timestamp of time(), so you should be able to copy and paste this directly into your code, assuming you have a myTestDB and myTestTable in the region you defined in setting up the client (see above).

$result = $client->writeRecords([
    'DatabaseName' => 'myTestDB',
    'TableName' => 'myTestTable',
    'Records' => [
        [
            'Dimensions' => [
                [
                    'DimensionValueType' => 'VARCHAR',
                    'Name' => 'Server', 
                    'Value' => 'Node01',
                ],
             ],
             'MeasureName' => 'CPU_utilization',
             'MeasureValue' => '0.9',
             'MeasureValueType' => 'DOUBLE',
             'Time' => strVal(time()),
             'TimeUnit' => 'SECONDS',
        ]
    ]
]);

Executing the above should write a record to Timestream, which will be visible in the Console like so:

During development, specify a sensible Time for the records you are writing. Timestream isn’t quite like other databases, as you will struggle to write the database records (or subsequently query them) if the timestamp provided is not within the time window for the table created, which is usually between Now and the Magnetic store retention time.

For more information, see the Data Ingestion topic in the Best Practices section of the Developer Guide.

Writing Multiple Records, using Common Attributes

The Developer Guide discusses Cost Optimization and recommends:

• Batch multiple time series events per write to reduce the number of write requests.
• Use common attributes with batching to batch more time-series events per write to reduce the number of write requests further.

A simple example of how to achieve that is as follows:

$result = $client->writeRecords([
    'DatabaseName' => 'myTestDB',
    'TableName' => 'myTestTable',
    'CommonAttributes' => [
        'Dimensions' => [
            [
                'DimensionValueType' => 'VARCHAR',
                'Name' => 'Server',
                'Value' => 'VM01',
            ],
            [
                'DimensionValueType' => 'VARCHAR',
                'Name' => 'App',
                'Value' => 'Web',
            ],
        ],
        'Time' => strval(time()),
        'TimeUnit' => 'SECONDS',
     ],
     'Records' => [
         [
             'MeasureName' => 'CPU_utilization',
             'MeasureValue' => '1.1',
             'MeasureValueType' => 'DOUBLE',
         ],
         [
             'MeasureName' => 'Disk_space',
             'MeasureValue' => '79',
             'MeasureValueType' => 'BIGINT',
         ],
     ]
 ]);

In the above example, the ingested records use the same timestamp; hence Time is included in the CommonAttributes section. You can batch records with different timestamps by having the timestamp in the Records array rather than in CommonAttributes.

Additionally, the performance is allegedly better if the Records array is ordered by timestamp as recommended here: https://docs.aws.amazon.com/timestream/latest/developerguide/data-ingest.html

Multi-measure Timestream Records

Amazon Timestream offers the ability to write data using two types of records, namely, single-measure records and multi-measure records.

It is likely considerably cheaper if you can structure your data for ingestion with multi-measure records, as shown below:

$result = $client->writeRecords([
    'DatabaseName' => 'myTestDB',
    'TableName' => 'myTestTableMulti',
    'Records' => [
        [
            'Dimensions' => [
                [
                    'DimensionValueType' => 'VARCHAR',
                    'Name' => 'Server',
                    'Value' => 'VM01',
                ],
                [
                    'DimensionValueType' => 'VARCHAR',
                    'Name' => 'App',
                    'Value' => 'Web',
                ],
            ],
            'MeasureName' => 'MultiStats',
            'MeasureValueType' => 'MULTI',
            'MeasureValues' => [
                [
                    'Name' => 'CPU_utilization',
                    'Type' => 'DOUBLE',
                    'Value' => '2.1',
                ],
                [
                    'Name' => 'Disk_space',
                    'Type' => 'BIGINT',
                    'Value' => '76',
                ],
            ],
            'Time' => strval(time()),
            'TimeUnit' => 'SECONDS',
        ],
        [
            'Dimensions' => [
                [
                    'DimensionValueType' => 'VARCHAR',
                    'Name' => 'Server',
                    'Value' => 'VM01',
                ],
                [
                    'DimensionValueType' => 'VARCHAR',
                    'Name' => 'App',
                    'Value' => 'Voip',
                ],
            ],
            'MeasureName' => 'VoipStats',
            'MeasureValueType' => 'MULTI',
            'MeasureValues' => [
                [
                    'Name' => 'CPU_utilization',
                    'Type' => 'DOUBLE',
                    'Value' => '1.4',
                ],
                [
                    'Name' => 'Channels_in_use',
                    'Type' => 'BIGINT',
                    'Value' => '45',
                ],
            ],
            'Time' => strval(time()),
            'TimeUnit' => 'SECONDS',
        ],
    ]
]);

Hope this Helps!

Any feedback is welcome.