Eloquent syntax for store and retrieve logs from Aws CloudWatch Logs.
Via Composer
$ composer require matteomeloni/aws-cloudwatch-logs
Run
$ php artisan vendor:publish --provider 'Matteomeloni\CloudwatchLogs\CloudwatchLogsServiceProvider'
Update AWS CloudWatch Logs config in config/aws-cloudwatch-logs.php
Extends your model with Matteomeloni\CloudwatchLogs\CloudWatchLogs
<?php
namespace App\Models;
use Matteomeloni\CloudwatchLogs\CloudWatchLogs;
class Log extends CloudWatchLogs
{
protected string $logGroupName = 'LOG GROUP NAME';
protected string $logStreamName = 'LOG STREAM NAME';
}
An accessor transforms an attribute value when it is accessed. To define an accessor, create a get {Attribute} Attribute method on your model where {Attribute} is the "studly" cased name of the column you wish to access.
<?php
namespace App\Models;
use Matteomeloni\CloudwatchLogs\CloudWatchLogs;
class Log extends CloudWatchLogs
{
public function getFooAttribute($value)
{
return ucfirst($value);
}
}
A mutator transforms an attribute value when it is set. To define a mutator, define a set{Attribute}Attribute
method on your model where {Attribute}
is the "studly" cased name of the column you wish to access.
<?php
namespace App\Models;
use Matteomeloni\CloudwatchLogs\CloudWatchLogs;
class Log extends CloudWatchLogs
{
public function setFooAttribute($value)
{
$this->attributes['foo'] = strtolower($value);
}
}
Your model's $casts property provides a convenient method of converting attributes to common data types.
The $casts property should be an array where the key is the name of the attribute being cast and the value is the type you wish to cast the column to.
See the Laravel documentation to learn more.
<?php
namespace App\Models;
use Matteomeloni\CloudwatchLogs\CloudWatchLogs;
class Log extends CloudWatchLogs
{
protected $casts = [
'foo' => 'boolean',
];
}
The model's all
method will retrieve all of the logs from the model's associated logGroupName and logStreamName.
By default, all logs generated on the current day will be extracted.
If you want to change the time interval, then just use the whereBetween
method
<?php
use App\Models\Log;
// All logs generated on the current day...
foreach(Logs::all() as $log) {
echo $log->attributeOne;
}
// All logs generated on custom time interval...
$logs = Logs::whereBetween('timestamp', ['Y-m-d H:i:s', 'Y-m-d H:i:s'])->get();
This package support the "CloudWatch Logs Insights" feature.
For more information of this feature, you can see the Aws CloudWatch Logs Insight Documentation
To start a new query you can use the query
method and the result of this operation is the queryId
string, to be used to retrieve the query results:
<?php
use App\Models\Log;
// Start a new query and retrieve the queryId string...
$queryId = Log::query()
->where('foo','bar')
->get();
// Retrieve the query results...
$logs = Log::query($queryId)->get();
// Retrieve last started query...
$logs = Log::queries();
The select
method allows you to specify which columns to show in the query result.
<?php
use App\Models\Log;
$logs = Log::query()
->select(['column1', 'column2'])
->get();
$logs = Log::query()
->select('column1', 'column2')
->get();
Avaialable comparison operators: =
!=
<
<=
>
>=
<?php
use App\Models\Log;
// Chainable for 'AND'.
Log::query()
->where('column', 'operator', 'value')
->where('column', 'operator', 'value')
->get();
// Chainable for 'OR'.
Log::query()
->where('column', 'operator', 'value')
->orWhere('column', 'operator', 'value')
->get();
// Other types of conditions
Log::whereIn('column', [1, 2, 3])->get();
Log::orWhereIn('column', [1, 2, 3])->get();
Log::whereNotIn('column', [1, 2, 3])->get();
Log::orWhereNotIn('column', [1, 2, 3])->get();
Log::whereBetween('column', [1, 100])->get();
Log::orWhereBetween('column', [1, 100])->get();
Log::whereNull('column')->get();
Log::orWhereNull('column')->get();
Log::whereNotNull('column')->get();
Log::orWhereNotNull('column')->get();
Sometimes it may be necessary to group several "where" clauses in parentheses to achieve logical grouping in the query.
To accomplish this, you may pass a closure to the where
method:
<?php
use App\Models\Log;
Log::query()
->where('column', 'operator', 'value')
->where(function ($query) {
$query->where('column', 'operator', 'value')
->orWhere('column', 'operator', 'value');
})
->get();
The orderBy
method allows sorting of the query by a given column.
The first argument accepted by this metod, should be the column you wish to sort by and the second argument, determines the direction of the sort, asc
or desc
<?php
use App\Models\Log;
//Ordering log by column asc...
Log::query()->orderBy('column')->get();
//Ordering log by column desc...
Log::query()->orderBy('column','desc')->get();
//Ordering log by column desc...
Log::query()->orderByDesc('column')->get();
The take
or limit
method allows to limit the number of results returned from the query.
<?php
use App\Models\Log;
Log::query()->take(10)->get();
Log::query()->limit(10)->get();
This library also provides a variety of methods for retrieving aggregate values like count
, min
, max
, sum
, and avg
.
For more information of this feature, you can see the Aws CloudWatch Logs Insigiht Documentation
You may call any of these methods after constructing your query:
<?php
use App\Models\Log;
$count = Log::query()
->where('level_code', 500)
->count();
//Other types of aggregates
Log::query()->min('column');
Log::query()->max('column');
Log::query()->sum('column');
Log::query()->avg('column');
Log::query()->average('column'); //Alias for the "avg" method
It is possible to group and aggregate the results through the groupBy
method.
In this case the result of the operation will be a collection.
In addition to a specific column, it is also possible to group for all the functions offered by the AWS CloudWatch Logs Insights service.
<?php
use App\Models\Log;
Log::query()
->groupBy('column')
->groupBy('bin (1m)')
->count();
In addition to retrieving all of the records matching a given query, you may also retrieve single records using the find
or first
methods.
<?php
use App\Models\Log;
/**
* Retrieve a log by its logRecordPointer
* (you can retrieve that from the response of insight query)...
*/
$log = Log::find($ptr);
// Retrieve the first model matching the query constraints...
$log = Log::all()->first();
// Find a model by its ptr or throw an exception...
$log = Log::findOrFail($ptr);
// Find multiple models by their ptr.
$logs = Log::findMany([$ptr1,$ptr2,$ptr3]);
To insert a new record into AWS CloudWatch Log, you should instantiate a new model instance and set attributes on the model.
Then, call the save method on the model instance:
<?php
use App\Models\Log;
$log = new Log();
$log->attributeOne = 'foo';
$log->attributeTwo = 'bar';
$log->save();
Alternatively, you may use the create method to "save" a new log using a single PHP statement. The inserted log instance will be returned to you by the create method:
<?php
use App\Models\Log;
$log = Log::create([
'attributeOne' => 'foo',
'attributeTwo' => 'bar'
]);
-
php 7.4 or later
-
Laravel 7 or later
Please see the changelog for more information on what has changed recently.
$ composer test
Please see contributing.md for details and a todolist.
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.