Skip to content

Commit 0c9bc0e

Browse files
belisarhbelisarh
committed
docs: Update readme
1 parent 98162f5 commit 0c9bc0e

File tree

1 file changed

+153
-33
lines changed

1 file changed

+153
-33
lines changed

‎README.md‎

Lines changed: 153 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,9 @@
77
![Static Analysis](https://github.com/kirschbaum-development/monitor/actions/workflows/static-analysis.yml/badge.svg)
88
![Code Style](https://github.com/kirschbaum-development/monitor/actions/workflows/style-check.yml/badge.svg)
99

10-
Laravel Monitor is an observability helper / toolkit for Laravel applications. .
10+
Laravel Monitor is an observability helper / toolkit for Laravel applications.
11+
12+
> This package is active development and its API can change abruptly without any notice. Please reach out if you plan to use it in a production environment.
1113
1214
## Table of Contents
1315

@@ -18,7 +20,10 @@ Laravel Monitor is an observability helper / toolkit for Laravel applications. .
1820
- [Distributed Tracing](#distributed-tracing)
1921
- [HTTP Middleware](#http-middleware)
2022
- [Performance Timing](#performance-timing)
23+
- [Circuit Breaker Direct Access](#circuit-breaker-direct-access)
24+
- [Log Redactor Direct Access](#log-redactor-direct-access)
2125
- [Log Redaction](#log-redaction)
26+
- [Complete API Reference](#complete-api-reference)
2227
- [Configuration](#configuration)
2328
- [Output Examples](#output-examples)
2429
- [Testing](#testing)
@@ -53,7 +58,7 @@ class UserController extends Controller
5358
public function login(LoginRequest $request)
5459
{
5560
// Automatic origin resolution from full namespace
56-
Monitor::from($this)->info('User login attempt', [
61+
Monitor::log($this)->info('User login attempt', [
5762
'email' => $request->email,
5863
'ip' => $request->ip()
5964
]);
@@ -66,22 +71,22 @@ class StripePaymentService
6671
public function processPayment($amount)
6772
{
6873
// Origin automatically resolved to clean, readable format
69-
Monitor::from($this)->info('Processing payment', [
74+
Monitor::log($this)->info('Processing payment', [
7075
'amount' => $amount,
7176
'processor' => 'stripe'
7277
]);
7378
}
7479
}
7580
```
7681

77-
**Note:** While you can override with `Monitor::from('CustomName')`, using `from($this)` is preferred as it automatically provides meaningful, consistent origin tracking from your actual class structure.
82+
**Note:** While you can override with `Monitor::log('CustomName')`, using `log($this)` is preferred as it automatically provides meaningful, consistent origin tracking from your actual class structure.
7883

7984
**What it logs:**
8085
```json
8186
{
8287
"level": "info",
83-
"event": "Api:UserController:info",
84-
"message": "[Api:UserController] User login attempt",
88+
"event": "Monitor:Http:Controllers:Api:UserController:info",
89+
"message": "[Monitor:Http:Controllers:Api:UserController] User login attempt",
8590
"trace_id": "9d2b4e8f-3a1c-4d5e-8f2a-1b3c4d5e6f7g",
8691
"context": {
8792
"email": "[REDACTED]",
@@ -93,24 +98,27 @@ class StripePaymentService
9398
}
9499
```
95100

101+
**Note:** The `event` field uses the raw origin name (after path replacers but before wrapper), while the `message` field uses the wrapped origin name for readability.
102+
96103
**Configuration:** Origin path replacers, separators, and wrappers control how class names appear in logs:
97104

98105
```php
99106
// config/monitor.php
100107
'origin_path_replacers' => [
101-
'App\\Http\\Controllers\\' => '', // Remove controller namespace
102-
'App\\Services\\Payment\\' => 'Pay\\', // Shorten payment services
103-
'App\\Services\\' => 'Svc\\', // General service shortening
108+
'App\\' => 'Monitor\\', // Default: Replace App\ with Monitor\
109+
// 'App\\Http\\Controllers\\' => '', // Example: Remove controller namespace
110+
// 'App\\Services\\Payment\\' => 'Pay\\', // Example: Shorten payment services
111+
// 'App\\Services\\' => 'Svc\\', // Example: General service shortening
104112
],
105-
'origin_separator' => ':', // App\Http\Controllers\Api\UserController → Api:UserController
106-
'origin_path_wrapper' => 'square', // Api:UserController → [Api:UserController]
113+
'origin_separator' => ':', // App\Http\Controllers\Api\UserController → Monitor:Http:Controllers:Api:UserController
114+
'origin_path_wrapper' => 'square', // Monitor:Http:Controllers:Api:UserController → [Monitor:Http:Controllers:Api:UserController]
107115
```
108116

109117
### Controlled Execution Blocks
110118

111119
**What it does:** Monitors critical operations with automatic start/end logging, exception-specific handling, DB transactions, circuit breakers, and true escalation for uncaught exceptions.
112120

113-
**Note:** The second parameter `$origin` (usually `$this`) is optional and automatically provides origin context to the structured logger used by the controlled block, eliminating the need for a separate `->from()` call.
121+
**Note:** The second parameter `$origin` (usually `$this`) is optional and automatically provides origin context to the structured logger used by the controlled block, eliminating the need for a separate `->log()` call.
114122

115123
#### **Factory & Execution**
116124

@@ -282,21 +290,21 @@ class PaymentService
282290

283291
**Success:**
284292
```json
285-
{"message": "[PaymentProcessor] STARTED", "controlled_block": "payment_processing", "controlled_block_id": "01HK..."}
286-
{"message": "[PaymentProcessor] ENDED", "status": "ok", "duration_ms": 1250}
293+
{"message": "[Monitor:Services:PaymentService] STARTED", "controlled_block": "payment_processing", "controlled_block_id": "01HK..."}
294+
{"message": "[Monitor:Services:PaymentService] ENDED", "status": "ok", "duration_ms": 1250}
287295
```
288296

289297
**Caught Exception (Recovery):**
290298
```json
291-
{"message": "[PaymentProcessor] STARTED", "controlled_block": "payment_processing"}
292-
{"message": "[PaymentProcessor] CAUGHT", "exception": "PaymentDeclinedException", "duration_ms": 500}
293-
{"message": "[PaymentProcessor] RECOVERED", "recovery_value": "array"}
299+
{"message": "[Monitor:Services:PaymentService] STARTED", "controlled_block": "payment_processing"}
300+
{"message": "[Monitor:Services:PaymentService] CAUGHT", "exception": "PaymentDeclinedException", "duration_ms": 500}
301+
{"message": "[Monitor:Services:PaymentService] RECOVERED", "recovery_value": "array"}
294302
```
295303

296304
**Uncaught Exception (Escalation):**
297305
```json
298-
{"message": "[PaymentProcessor] STARTED", "controlled_block": "payment_processing"}
299-
{"message": "[PaymentProcessor] UNCAUGHT", "exception": "RuntimeException", "uncaught": true, "duration_ms": 300}
306+
{"message": "[Monitor:Services:PaymentService] STARTED", "controlled_block": "payment_processing"}
307+
{"message": "[Monitor:Services:PaymentService] UNCAUGHT", "exception": "RuntimeException", "uncaught": true, "duration_ms": 300}
300308
```
301309

302310
#### **API Reference**
@@ -327,7 +335,7 @@ class OrderController extends Controller
327335
// Start trace (typically via middleware)
328336
Monitor::trace()->start();
329337

330-
Monitor::from($this)->info('Processing order');
338+
Monitor::log($this)->info('Processing order');
331339

332340
// All subsequent operations share the same trace ID
333341
$this->paymentService->charge($amount);
@@ -342,20 +350,27 @@ class PaymentService
342350
public function charge($amount)
343351
{
344352
// Automatically includes trace ID from OrderController
345-
Monitor::from($this)->info('Charging card', ['amount' => $amount]);
353+
Monitor::log($this)->info('Charging card', ['amount' => $amount]);
346354
}
347355
}
348356
```
349357

350358
**Trace Management:**
351359
```php
352360
// Manual control
353-
Monitor::trace()->start(); // Generate new UUID
354-
Monitor::trace()->override($traceId); // Use specific ID
355-
Monitor::trace()->id(); // Get current ID
361+
Monitor::trace()->start(); // Generate new UUID (throws if already started)
362+
Monitor::trace()->override($traceId); // Use specific ID (overwrites existing)
363+
Monitor::trace()->pickup($traceId); // Start if not started, optionally with specific ID
364+
Monitor::trace()->id(); // Get current ID (throws if not started)
356365
Monitor::trace()->hasStarted(); // Check if active
366+
Monitor::trace()->hasNotStarted(); // Check if not active
357367
```
358368

369+
**Key Differences:**
370+
- `start()` - Throws exception if trace already exists
371+
- `override()` - Always sets trace ID, replacing any existing one
372+
- `pickup()` - Safe method that starts only if not already started
373+
359374
### HTTP Middleware
360375

361376
**What it does:** Automatically manages trace IDs for HTTP requests, enabling seamless distributed tracing across services.
@@ -403,7 +418,7 @@ class DataProcessor
403418

404419
$elapsed = $timer->elapsed(); // Milliseconds
405420

406-
Monitor::from($this)->info('Processing complete', [
421+
Monitor::log($this)->info('Processing complete', [
407422
'duration_ms' => $elapsed
408423
]);
409424
}
@@ -412,6 +427,74 @@ class DataProcessor
412427

413428
**Note:** All Monitor logging automatically includes `duration_ms` from service start.
414429

430+
### Circuit Breaker Direct Access
431+
432+
**What it does:** Provides direct access to circuit breaker state management for advanced use cases.
433+
434+
```php
435+
use Kirschbaum\Monitor\Facades\Monitor;
436+
437+
// Check circuit breaker state
438+
$isOpen = Monitor::breaker()->isOpen('payment_gateway');
439+
$state = Monitor::breaker()->getState('payment_gateway');
440+
441+
// Manual state management
442+
Monitor::breaker()->recordFailure('api_service', 300); // Record failure with 300s decay
443+
Monitor::breaker()->recordSuccess('api_service'); // Record success (resets failures)
444+
Monitor::breaker()->reset('api_service'); // Force reset
445+
Monitor::breaker()->forceOpen('api_service'); // Force open state
446+
```
447+
448+
**Usage in Custom Logic:**
449+
```php
450+
class ExternalApiService
451+
{
452+
public function makeRequest()
453+
{
454+
if (Monitor::breaker()->isOpen('external_api')) {
455+
return $this->getCachedResponse();
456+
}
457+
458+
try {
459+
$response = $this->performApiCall();
460+
Monitor::breaker()->recordSuccess('external_api');
461+
return $response;
462+
} catch (Exception $e) {
463+
Monitor::breaker()->recordFailure('external_api', 120);
464+
throw $e;
465+
}
466+
}
467+
}
468+
```
469+
470+
### Log Redactor Direct Access
471+
472+
**What it does:** Provides direct access to the redactor for custom redaction needs.
473+
474+
```php
475+
use Kirschbaum\Monitor\Facades\Monitor;
476+
477+
// Direct redaction using configured profile
478+
$redactedData = Monitor::redactor()->redact($sensitiveData);
479+
480+
// Custom profile redaction
481+
$redactedData = Monitor::redactor()->redact($sensitiveData, 'strict');
482+
483+
// Example usage
484+
class UserDataProcessor
485+
{
486+
public function processUserData(array $userData)
487+
{
488+
// Redact before logging or storing
489+
$safeData = Monitor::redactor()->redact($userData);
490+
491+
Monitor::log($this)->info('Processing user data', $safeData);
492+
493+
return $this->process($userData); // Use original for processing
494+
}
495+
}
496+
```
497+
415498
### Log Redaction
416499

417500
**What it does:** Automatically scrubs sensitive data from log context using [Kirschbaum Redactor](https://github.com/kirschbaum-development/redactor) to ensure compliance and security while preserving important data.
@@ -428,7 +511,7 @@ class DataProcessor
428511
**Usage:** Redaction is automatically applied to all Monitor log context:
429512

430513
```php
431-
Monitor::from($this)->info('User data', [
514+
Monitor::log($this)->info('User data', [
432515
'id' => 123,
433516
'email' => '[email protected]', // → '[REDACTED]' based on profile rules
434517
'password' => 'secret123', // → '[REDACTED]' based on profile rules
@@ -439,24 +522,60 @@ Monitor::from($this)->info('User data', [
439522

440523
For detailed redaction configuration, rules, patterns, and profiles, see the [Kirschbaum Redactor documentation](https://github.com/kirschbaum-development/redactor).
441524

525+
## Complete API Reference
526+
527+
The Monitor facade provides access to all monitoring components:
528+
529+
```php
530+
use Kirschbaum\Monitor\Facades\Monitor;
531+
532+
// Structured logging
533+
Monitor::log($origin)->info('message', $context);
534+
535+
// Controlled execution blocks
536+
Monitor::controlled($name, $origin)->run($callback);
537+
538+
// Distributed tracing
539+
Monitor::trace()->start();
540+
Monitor::trace()->pickup($traceId);
541+
542+
// Performance timing
543+
Monitor::time()->elapsed();
544+
545+
// Circuit breaker management
546+
Monitor::breaker()->isOpen($name);
547+
548+
// Log redaction
549+
Monitor::redactor()->redact($data);
550+
```
551+
552+
All components integrate seamlessly and share trace context automatically when used together.
553+
442554
## Configuration
443555

444556
**Environment Variables:**
445557
```bash
446558
# Core settings
447559
MONITOR_ENABLED=true
448560

449-
# Exception tracing
561+
# Exception tracing (applies to Controlled blocks only)
450562
MONITOR_TRACE_ENABLED=true
451563
MONITOR_TRACE_FULL_ON_DEBUG=true
564+
MONITOR_TRACE_FORCE_FULL_TRACE=false
452565
MONITOR_TRACE_MAX_LINES=15
453566

454567
# Auto-trace console commands
455568
MONITOR_CONSOLE_AUTO_TRACE_ENABLED=true
569+
MONITOR_CONSOLE_AUTO_TRACE_ENABLE_IN_TESTING=false
456570

457571
# HTTP trace header
458572
MONITOR_TRACE_HEADER=X-Trace-Id
459573

574+
# Circuit breaker defaults
575+
MONITOR_CIRCUIT_BREAKER_DECAY_SECONDS=300
576+
MONITOR_CIRCUIT_BREAKER_RETRY_AFTER=300
577+
MONITOR_CIRCUIT_BREAKER_CORS_HEADERS=false
578+
460579
# Log redaction
461580
MONITOR_REDACTOR_ENABLED=true
462581
MONITOR_REDACTOR_PROFILE=default
@@ -485,8 +604,8 @@ MONITOR_REDACTOR_PROFILE=default
485604
```json
486605
{
487606
"level": "info",
488-
"event": "UserController:info",
489-
"message": "[UserController] User login successful",
607+
"event": "Monitor:Http:Controllers:UserController:info",
608+
"message": "[Monitor:Http:Controllers:UserController] User login successful",
490609
"trace_id": "9d2b4e8f-3a1c-4d5e-8f2a-1b3c4d5e6f7g",
491610
"context": {
492611
"user_id": 123,
@@ -501,14 +620,14 @@ MONITOR_REDACTOR_PROFILE=default
501620

502621
**Controlled Block Execution:**
503622
```json
504-
{"message": "[PaymentService] STARTED", "controlled_block": "payment_processing", "controlled_block_id": "01HK4...", "trace_id": "9d2b4e8f..."}
505-
{"message": "[PaymentService] ENDED", "controlled_block": "payment_processing", "status": "ok", "duration_ms": 1250}
623+
{"message": "[Monitor:Services:PaymentService] STARTED", "controlled_block": "payment_processing", "controlled_block_id": "01HK4...", "trace_id": "9d2b4e8f..."}
624+
{"message": "[Monitor:Services:PaymentService] ENDED", "controlled_block": "payment_processing", "status": "ok", "duration_ms": 1250}
506625
```
507626

508627
**Failure with Exception:**
509628
```json
510629
{
511-
"message": "[PaymentService] FAILED",
630+
"message": "[Monitor:Services:PaymentService] UNCAUGHT",
512631
"controlled_block": "payment_processing",
513632
"exception": {
514633
"class": "RuntimeException",
@@ -517,7 +636,8 @@ MONITOR_REDACTOR_PROFILE=default
517636
"line": 45,
518637
"trace": ["...", "..."]
519638
},
520-
"duration_ms": 500
639+
"duration_ms": 500,
640+
"uncaught": true
521641
}
522642
```
523643

0 commit comments

Comments
 (0)