Skip to content

Commit c4f4e38

Browse files
author
CodeXpedite
committed
Initial release of Laravel Supabase Logger
0 parents  commit c4f4e38

14 files changed

+1730
-0
lines changed

‎CHANGELOG.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Changelog
2+
3+
All notable changes to `laravel-supabase-logger` will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.0.0] - 2025-07-29
9+
10+
### Added
11+
- Initial release of Laravel Supabase Logger
12+
- Core logging functionality with Supabase integration
13+
- Log deduplication using MD5 hashing
14+
- Occurrence tracking for duplicate logs
15+
- Smart auto-tagging based on context, routes, users, and exceptions
16+
- Batch processing for optimized API usage
17+
- Fallback logging to local files when Supabase is unavailable
18+
- Comprehensive error handling and retry logic
19+
- Management Artisan commands:
20+
- `supabase-logger:test` - Test connection and configuration
21+
- `supabase-logger:tail` - View recent logs
22+
- `supabase-logger:flush` - Force flush pending logs
23+
- Eloquent model for interacting with logs
24+
- Configurable sensitive data sanitization
25+
- Support for Laravel 10.x, 11.x, and 12.x
26+
- Comprehensive documentation and setup instructions
27+
- Production-ready performance optimizations
28+
29+
### Features
30+
- **Log Deduplication**: Automatically groups identical log messages
31+
- **Occurrence Tracking**: Counts how many times each unique log has occurred
32+
- **Smart Auto-Tagging**: Automatically tags logs based on routes, users, exceptions, and context
33+
- **Batch Processing**: Efficiently processes logs in configurable batches
34+
- **Fallback Logging**: Graceful error handling with automatic fallback to local file logging
35+
- **High Performance**: Built with performance in mind using efficient HTTP client with retry logic
36+
- **Management Commands**: Artisan commands for testing, flushing, and tailing logs
37+
- **Security**: Configurable sensitive data sanitization
38+
- **Production Ready**: Robust error handling and comprehensive logging
39+
40+
### Configuration
41+
- Extensive configuration options in `config/supabase-logger.php`
42+
- Environment variable support for all major settings
43+
- Configurable batch sizes, retry attempts, and timeouts
44+
- Auto-tagging preferences
45+
- Security and sanitization settings
46+
- Fallback logging configuration
47+
48+
### Requirements
49+
- PHP 8.2 or higher
50+
- Laravel 10.x, 11.x, or 12.x
51+
- Supabase project with PostgreSQL database
52+
- Guzzle HTTP 7.0+
53+
- Monolog 3.0+
54+
55+
### Documentation
56+
- Comprehensive README with installation and usage instructions
57+
- Database schema and setup instructions
58+
- Configuration examples and best practices
59+
- Troubleshooting guide
60+
- API documentation for all classes and methods

‎LICENSE.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 CodeXpedite
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
# Laravel Supabase Logger
2+
3+
[![Latest Version on Packagist](https://img.shields.io/packagist/v/codexpedite/laravel-supabase-logger.svg?style=flat-square)](https://packagist.org/packages/codexpedite/laravel-supabase-logger)
4+
[![Total Downloads](https://img.shields.io/packagist/dt/codexpedite/laravel-supabase-logger.svg?style=flat-square)](https://packagist.org/packages/codexpedite/laravel-supabase-logger)
5+
[![License](https://img.shields.io/packagist/l/codexpedite/laravel-supabase-logger.svg?style=flat-square)](https://packagist.org/packages/codexpedite/laravel-supabase-logger)
6+
7+
A powerful, modular Laravel package for logging to Supabase (PostgreSQL) with advanced features including deduplication, occurrence tracking, smart tagging, and batch processing.
8+
9+
## Features
10+
11+
- 🔄 **Log Deduplication**: Automatically deduplicates identical log messages using MD5 hashing
12+
- 📊 **Occurrence Tracking**: Counts how many times each unique log has occurred
13+
- 🏷️ **Smart Auto-Tagging**: Automatically tags logs based on routes, users, exceptions, and context
14+
- 📦 **Batch Processing**: Efficiently processes logs in configurable batches to optimize API usage
15+
- 🔄 **Fallback Logging**: Graceful error handling with automatic fallback to local file logging
16+
- ⚡ **High Performance**: Built with performance in mind using efficient HTTP client with retry logic
17+
- 🛠️ **Management Commands**: Artisan commands for testing, flushing, and tailing logs
18+
- 🔒 **Security**: Configurable sensitive data sanitization
19+
- 🎯 **Production Ready**: Robust error handling and comprehensive logging
20+
21+
## Requirements
22+
23+
- PHP 8.2 or higher
24+
- Laravel 10.x, 11.x, or 12.x
25+
- Supabase project with PostgreSQL database
26+
27+
## Installation
28+
29+
Install the package via Composer:
30+
31+
```bash
32+
composer require codexpedite/laravel-supabase-logger
33+
```
34+
35+
Publish the configuration file:
36+
37+
```bash
38+
php artisan vendor:publish --tag=supabase-logger-config
39+
```
40+
41+
## Database Setup
42+
43+
Create the `laravel_logs` table in your Supabase database:
44+
45+
```sql
46+
CREATE TABLE laravel_logs (
47+
id BIGSERIAL PRIMARY KEY,
48+
hash VARCHAR(32) NOT NULL UNIQUE,
49+
level VARCHAR(20) NOT NULL,
50+
message TEXT NOT NULL,
51+
context JSONB,
52+
app VARCHAR(100) NOT NULL,
53+
environment VARCHAR(50) NOT NULL,
54+
occurred_at TIMESTAMP WITH TIME ZONE NOT NULL,
55+
first_occurred_at TIMESTAMP WITH TIME ZONE NOT NULL,
56+
last_occurred_at TIMESTAMP WITH TIME ZONE NOT NULL,
57+
occurrences INTEGER DEFAULT 1,
58+
tags TEXT[],
59+
status VARCHAR(20) DEFAULT 'new',
60+
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
61+
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
62+
);
63+
64+
-- Create indexes for better performance
65+
CREATE INDEX idx_laravel_logs_hash ON laravel_logs(hash);
66+
CREATE INDEX idx_laravel_logs_level ON laravel_logs(level);
67+
CREATE INDEX idx_laravel_logs_app_env ON laravel_logs(app, environment);
68+
CREATE INDEX idx_laravel_logs_occurred_at ON laravel_logs(occurred_at);
69+
CREATE INDEX idx_laravel_logs_status ON laravel_logs(status);
70+
CREATE INDEX idx_laravel_logs_tags ON laravel_logs USING GIN(tags);
71+
```
72+
73+
## Configuration
74+
75+
Add your Supabase credentials to your `.env` file:
76+
77+
```env
78+
SUPABASE_URL=https://your-project.supabase.co
79+
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
80+
```
81+
82+
Add the Supabase logging channel to your `config/logging.php`:
83+
84+
```php
85+
'channels' => [
86+
// ... other channels
87+
88+
'supabase' => [
89+
'driver' => 'custom',
90+
'via' => \Codexpedite\LaravelSupabaseLogger\SupabaseLoggerCreator::class,
91+
'level' => env('LOG_LEVEL', 'debug'),
92+
],
93+
],
94+
```
95+
96+
## Basic Usage
97+
98+
```php
99+
use Illuminate\Support\Facades\Log;
100+
101+
// Basic logging
102+
Log::channel('supabase')->info('User logged in', ['user_id' => 123]);
103+
104+
// Error logging with context
105+
Log::channel('supabase')->error('Payment failed', [
106+
'user_id' => 456,
107+
'order_id' => 789,
108+
'amount' => 99.99,
109+
'error' => $exception->getMessage()
110+
]);
111+
112+
// Warning with tags
113+
Log::channel('supabase')->warning('High memory usage detected', [
114+
'memory_usage' => '512MB',
115+
'tags' => ['performance', 'monitoring']
116+
]);
117+
```
118+
119+
## Management Commands
120+
121+
### Test Connection
122+
123+
Test your Supabase connection and configuration:
124+
125+
```bash
126+
php artisan supabase-logger:test
127+
```
128+
129+
### View Recent Logs
130+
131+
Display recent logs from Supabase:
132+
133+
```bash
134+
php artisan supabase-logger:tail
135+
136+
# With options
137+
php artisan supabase-logger:tail --limit=100 --level=error
138+
```
139+
140+
### Force Flush Logs
141+
142+
Force flush any pending logs from memory buffer:
143+
144+
```bash
145+
php artisan supabase-logger:flush
146+
```
147+
148+
## Configuration Options
149+
150+
The package provides extensive configuration options in `config/supabase-logger.php`:
151+
152+
```php
153+
return [
154+
// Supabase connection
155+
'supabase_url' => env('SUPABASE_URL'),
156+
'supabase_key' => env('SUPABASE_SERVICE_ROLE_KEY'),
157+
'table_name' => 'laravel_logs',
158+
159+
// Performance settings
160+
'batch_size' => 50,
161+
'flush_interval' => 60, // seconds
162+
'timeout' => 30,
163+
'retry_attempts' => 3,
164+
'retry_delay' => 1000, // milliseconds
165+
166+
// Auto-tagging
167+
'auto_tag_routes' => true,
168+
'auto_tag_users' => true,
169+
'auto_tag_ips' => true,
170+
'auto_tag_exceptions' => true,
171+
172+
// Security
173+
'sanitize_sensitive_data' => true,
174+
'sensitive_keys' => ['password', 'token', 'secret', 'key'],
175+
176+
// Fallback logging
177+
'fallback_to_file' => true,
178+
'fallback_path' => storage_path('logs/supabase-fallback.log'),
179+
];
180+
```
181+
182+
## Features in Detail
183+
184+
### Log Deduplication
185+
186+
The package automatically deduplicates identical log messages using MD5 hashing. When a duplicate log is detected:
187+
188+
- The `occurrences` count is incremented
189+
- The `last_occurred_at` timestamp is updated
190+
- No new database row is created
191+
192+
### Smart Auto-Tagging
193+
194+
Logs are automatically tagged based on:
195+
- **Route**: `route:user.profile`
196+
- **User**: `user:123` (when authenticated)
197+
- **Exception**: `exception:ValidationException`
198+
- **IP Address**: `ip:192.168.1.1`
199+
- **Custom Tags**: Via context `tags` array
200+
201+
### Batch Processing
202+
203+
Logs are collected in memory and sent in configurable batches to reduce API calls and improve performance.
204+
205+
### Error Handling & Fallback
206+
207+
If Supabase is unavailable, the package will:
208+
1. Attempt to retry the request (configurable retry attempts)
209+
2. Fall back to local file logging if enabled
210+
3. Log errors to Laravel's default log channel
211+
4. Continue operation without breaking your application
212+
213+
## Model Usage
214+
215+
Interact with logs using the provided Eloquent model:
216+
217+
```php
218+
use Codexpedite\LaravelSupabaseLogger\Models\LaravelLog;
219+
220+
// Find logs by criteria
221+
$criticalLogs = LaravelLog::level('error')
222+
->forApp('my-app')
223+
->forEnvironment('production')
224+
->recent(24) // last 24 hours
225+
->get();
226+
227+
// Update log status
228+
$log = LaravelLog::find($id);
229+
$log->acknowledge(); // Mark as acknowledged
230+
$log->resolve(); // Mark as resolved
231+
$log->reopen(); // Reopen (mark as new)
232+
```
233+
234+
## Testing
235+
236+
```bash
237+
# Test connection and configuration
238+
php artisan supabase-logger:test
239+
240+
# Run package tests
241+
composer test
242+
```
243+
244+
## Contributing
245+
246+
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
247+
248+
## Security Vulnerabilities
249+
250+
If you discover a security vulnerability, please send an e-mail to [email protected].
251+
252+
## Credits
253+
254+
- [CodeXpedite](https://github.com/codeXpedite)
255+
- [All Contributors](../../contributors)
256+
257+
## License
258+
259+
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
260+
261+
## Changelog
262+
263+
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
264+
265+
## Support
266+
267+
- 📖 [Documentation](https://github.com/codeXpedite/laravel-supabase-logger)
268+
- 🐛 [Issue Tracker](https://github.com/codeXpedite/laravel-supabase-logger/issues)
269+
- 💬 [Discussions](https://github.com/codeXpedite/laravel-supabase-logger/discussions)
270+
271+
---
272+
273+
Made with ❤️ by CodeXpedite

0 commit comments

Comments
 (0)