README

Comprehensive observability package for the Nexus ERP monorepo
Production-grade monitoring with metrics, health checks, alerting, and automated retention.

📋 Table of Contents

Overview
Features
Installation
Quick Start
Core Components
Advanced Usage
Available Interfaces
Testing
Documentation
Architecture
Contributing

Overview

The Nexus\Telemetry package provides a complete observability solution for the Nexus ERP system. Built with framework-agnostic design principles, it offers:

Telemetry Tracking - Record metrics with cardinality protection and multi-tenancy support
Health Checks - Monitor system components with built-in checks and custom implementations
Alerting - Evaluate and dispatch alerts with deduplication and severity mapping
SLO Tracking - Automatic Service Level Objective instrumentation
Metric Retention - Automated cleanup with configurable policies
Easy Integration - Trait-based pattern for seamless adoption

Design Philosophy

Framework Agnostic - Pure PHP with PSR interfaces
Test-Driven - 188 tests with 476 assertions (100% passing)
Zero Infrastructure Coupling - Implementations injected via interfaces
Production Ready - Battle-tested patterns with comprehensive error handling

Features

✅ Metric Tracking

Multiple metric types: Counter, Gauge, Timer, Histogram
Cardinality protection: Prevent tag explosion
Sampling support: Reduce storage costs for high-volume metrics
Multi-tenancy: Automatic tenant context tagging
Trace context: OpenTelemetry-compatible trace/span IDs

✅ Health Checks

Built-in checks: Database, Cache, Disk Space, Memory
Template method pattern: Easy custom check creation
Priority-based execution: Critical checks first
Timeout handling: Graceful degradation
Result caching: Configurable TTL per check

✅ Alerting

Exception-to-severity mapping: Automatic alert classification
Fingerprint deduplication: Prevent alert storms
Time-window deduplication: Configurable silence periods
Metadata enrichment: Stack traces, exception details
Channel dispatching: Email, SMS, Slack, PagerDuty

✅ Utilities

SLO Wrapper: Automatic success/failure/latency tracking
Monitoring Trait: 6 convenience methods for quick integration
Custom Exceptions: Domain-specific error handling
Retention Service: Automated metric cleanup with policies

Available Interfaces

The package provides 15 interfaces for complete flexibility and framework agnosticism:

Core Tracking & Storage

TelemetryTrackerInterface - Record metrics (counter, gauge, timing, histogram)
MetricStorageInterface - Store and query metrics with aggregation
MetricRetentionInterface - Define retention policies for metric cleanup

Health Monitoring

HealthCheckerInterface - Register and execute health checks
HealthCheckInterface - Implement custom health checks
ScheduledHealthCheckInterface - Health checks with cron-like scheduling

Alerting

AlertGatewayInterface - Evaluate exceptions and dispatch alerts
AlertDispatcherInterface - Send alerts to notification channels

Cardinality Protection

CardinalityGuardInterface - Prevent metric tag explosion
CardinalityStorageInterface - Track unique tag values (HyperLogLog recommended)

Configuration & Context

SLOConfigurationInterface - Define Service Level Objectives
SamplingStrategyInterface - Implement metric sampling (probabilistic, deterministic, adaptive)
CacheRepositoryInterface - Cache health check results
TenantContextInterface - Multi-tenancy support (optional, from Nexus\Tenant)

Additional Utilities

MonitoringAwareTrait - Convenience methods for quick integration (6 helper methods)

Installation

Requirements

PHP 8.3 or higher
Composer

Install via Composer

composer require azaharizaman/nexus-telemetry:"*@dev"

Note: Package is currently in development. Use @dev stability flag.

Quick Start

1. Basic Metric Tracking

use Nexus\Telemetry\Services\TelemetryTracker;
use Psr\Log\LoggerInterface;

// Inject dependencies
$tracker = new TelemetryTracker(
    $metricStorage,      // Your storage implementation
    $cardinalityGuard,   // Cardinality protection
    $logger,             // PSR-3 logger
    $tenantContext,      // Optional: multi-tenancy
    $samplingStrategy    // Optional: sampling
);

// Record metrics
$tracker->increment('api.requests', tags: ['endpoint' => '/users']);
$tracker->gauge('memory.usage', 128.5, tags: ['unit' => 'MB']);
$tracker->timing('db.query', 45.2, tags: ['table' => 'users']);
$tracker->histogram('response.size', 1024, tags: ['endpoint' => '/api']);

2. Health Checks

use Nexus\Telemetry\Services\HealthCheckRunner;
use Nexus\Telemetry\HealthChecks\DatabaseHealthCheck;

// Register health checks
$runner = new HealthCheckRunner($cache, $logger);
$runner->register(new DatabaseHealthCheck($pdo));

// Execute all checks
$results = $runner->runAll();

// Check specific component
$dbHealth = $runner->runCheck('database');
echo $dbHealth->getStatus()->value; // HEALTHY, DEGRADED, OFFLINE, CRITICAL

3. Easy Integration with Trait

use Nexus\Telemetry\Traits\MonitoringAwareTrait;

class OrderService
{
    use MonitoringAwareTrait;
    
    public function __construct(TelemetryTrackerInterface $telemetry)
    {
        $this->setTelemetry($telemetry);
    }
    
    public function processOrder(Order $order): void
    {
        // Automatic SLO tracking
        $this->trackOperation('order.process', function() use ($order) {
            // Your business logic
            $this->saveOrder($order);
            $this->notifyCustomer($order);
        }, tags: ['payment_method' => $order->paymentMethod]);
        
        // Manual metrics
        $this->recordIncrement('orders.completed');
        $this->recordGauge('orders.value', $order->total);
    }
}

4. Automated Metric Retention

use Nexus\Telemetry\Services\MetricRetentionService;
use Nexus\Telemetry\Core\TimeBasedRetentionPolicy;

// Create retention policy
$policy = TimeBasedRetentionPolicy::days(30);

$retentionService = new MetricRetentionService(
    $metricStorage,
    $policy,
    $logger
);

// Schedule cleanup (e.g., Laravel)
$schedule->call(function() use ($retentionService) {
    if ($retentionService->needsCleanup(threshold: 10000)) {
        $pruned = $retentionService->pruneExpiredMetrics(batchSize: 1000);
        Log::info("Pruned {$pruned} expired metrics");
    }
})->daily();

Core Components

TelemetryTracker

Records metrics with protection and enrichment.

Key Features:

Cardinality limit enforcement
Automatic tenant tagging
OpenTelemetry trace context
Sampling for high-volume metrics

Methods:

increment(string $key, float $value = 1.0, array $tags = []): void
gauge(string $key, float $value, array $tags = []): void
timing(string $key, float $milliseconds, array $tags = []): void
histogram(string $key, float $value, array $tags = []): void

HealthCheckRunner

Orchestrates health checks with intelligent execution.

Key Features:

Priority-based ordering (critical first)
Timeout protection with circuit breaking
Result caching with configurable TTL
Scheduled vs on-demand execution

Methods:

register(HealthCheckInterface $check): void
runAll(): array<HealthCheckResult>
runCheck(string $name): HealthCheckResult

AlertEvaluator

Processes exceptions into alerts with deduplication.

Key Features:

Automatic severity mapping
Fingerprint-based deduplication
Time-window silence periods
Metadata enrichment (stack traces)

Methods:

evaluate(\Throwable $exception, array $context = []): void

MetricRetentionService

Manages metric lifecycle and cleanup.

Key Features:

Policy-driven retention (time-based, tiered)
Batch pruning with size limits
Threshold-based automatic cleanup
Comprehensive statistics

Methods:

pruneExpiredMetrics(?int $batchSize = null): int
pruneMetric(string $metricKey): int
getRetentionStats(): array
needsCleanup(int $threshold = 1000): bool

Advanced Usage

Custom Health Check

use Nexus\Telemetry\HealthChecks\AbstractHealthCheck;
use Nexus\Telemetry\ValueObjects\HealthStatus;

class RedisHealthCheck extends AbstractHealthCheck
{
    public function __construct(
        private readonly \Redis $redis,
        string $name = 'redis',
        int $priority = 8,
        int $timeoutSeconds = 3,
        int $cacheTtlSeconds = 60
    ) {
        parent::__construct($name, $priority, $timeoutSeconds, $cacheTtlSeconds);
    }
    
    protected function performCheck(): HealthStatus
    {
        $startTime = microtime(true);
        
        // Test connectivity
        $this->redis->ping();
        
        // Test read/write
        $testKey = 'health_check_' . uniqid();
        $this->redis->set($testKey, '1', 10);
        $this->redis->get($testKey);
        $this->redis->del($testKey);
        
        $duration = (microtime(true) - $startTime) * 1000;
        
        return match(true) {
            $duration > 500 => $this->degraded("Slow response: {$duration}ms"),
            default => $this->healthy()
        };
    }
}

Custom Retention Policy

use Nexus\Telemetry\Contracts\MetricRetentionInterface;

class TieredRetentionPolicy implements MetricRetentionInterface
{
    public function __construct(
        private readonly array $tiers = [
            'critical.*' => 86400 * 90,  // 90 days
            'business.*' => 86400 * 30,  // 30 days
            'debug.*' => 86400 * 7,      // 7 days
        ],
        private readonly int $defaultPeriod = 86400 * 14
    ) {}
    
    public function getRetentionPeriod(): int
    {
        return $this->defaultPeriod;
    }
    
    public function shouldRetain(string $metricKey, int $timestamp): bool
    {
        foreach ($this->tiers as $pattern => $period) {
            if (fnmatch($pattern, $metricKey)) {
                return $timestamp >= (time() - $period);
            }
        }
        
        return $timestamp >= (time() - $this->defaultPeriod);
    }
}

SLO Tracking Pattern

use Nexus\Telemetry\Core\SLOWrapper;

class PaymentGateway
{
    public function charge(Payment $payment): void
    {
        $wrapper = SLOWrapper::for(
            $this->telemetry,
            'payment.charge',
            tags: ['gateway' => $payment->gateway]
        );
        
        // Automatically tracks:
        // - slo.payment.charge.success (on success)
        // - slo.payment.charge.failure (on exception)
        // - slo.payment.charge.latency (always)
        // - slo.payment.charge.total (always)
        $wrapper->execute(function() use ($payment) {
            return $this->gateway->processPayment($payment);
        });
    }
}

Testing

Run All Tests

cd packages/Monitoring
vendor/bin/phpunit

Run Specific Test Suite

# Services only
vendor/bin/phpunit tests/Unit/Services/

# Health checks only
vendor/bin/phpunit tests/Unit/Core/

# With coverage (requires xdebug)
vendor/bin/phpunit --coverage-html coverage-report

Test Statistics

Total Tests: 188
Total Assertions: 476
Coverage: Comprehensive (all production code tested)
Runtime: ~2 seconds
Status: ✅ All passing

See TEST_SUITE_SUMMARY.md for detailed breakdown.

Architecture

Package Structure

packages/Monitoring/
├── src/
│   ├── Contracts/           # 15 interfaces (framework-agnostic)
│   ├── Services/            # 4 core services
│   ├── HealthChecks/        # Built-in health checks
│   ├── Core/                # Utilities (SLOWrapper, Policies)
│   ├── ValueObjects/        # Immutable data objects
│   ├── Exceptions/          # 5 custom exceptions
│   └── Traits/              # MonitoringAwareTrait
├── tests/
│   └── Unit/                # 188 comprehensive tests
├── composer.json
├── phpunit.xml
└── README.md

Key Design Patterns

Dependency Injection - All dependencies via constructor
Interface Segregation - Small, focused contracts
Template Method - AbstractHealthCheck pattern
Strategy Pattern - Pluggable sampling, retention policies
Decorator Pattern - SLOWrapper for cross-cutting concerns
Trait Composition - MonitoringAwareTrait for easy integration

Framework Integration

The package is framework-agnostic by design. Integration examples:

Laravel:

// app/Providers/MonitoringServiceProvider.php
$this->app->singleton(MetricStorageInterface::class, RedisMetricStorage::class);
$this->app->singleton(TelemetryTrackerInterface::class, TelemetryTracker::class);

Symfony:

# config/services.yaml
services:
  Nexus\Telemetry\Contracts\MetricStorageInterface:
    class: App\Infrastructure\RedisMetricStorage
  
  Nexus\Telemetry\Services\TelemetryTracker:
    autowire: true

Contributing

Development Setup

# Clone monorepo
git clone https://github.com/azaharizaman/atomy.git
cd atomy/packages/Monitoring

# Install dependencies
composer install

# Run tests
vendor/bin/phpunit

# Run static analysis (if configured)
vendor/bin/phpstan analyse

Coding Standards

PHP Version: 8.3+
Style Guide: PSR-12
Type Safety: Strict types enabled (declare(strict_types=1))
Modern PHP: Property promotion, readonly properties, enums
Testing: TDD approach with comprehensive coverage

Pull Request Process

Create feature branch from main
Write tests first (TDD)
Implement feature with strict types
Ensure all tests pass
Update documentation
Submit PR with clear description

Documentation

Package Documentation

Getting Started - Quick start guide with installation and basic examples
API Reference - Complete API documentation for all 15 interfaces
Integration Guide - Framework integration (Laravel, Symfony, vanilla PHP)
Examples - Working code examples
- Basic Usage - Metric tracking, health checks, querying
- Advanced Usage - Multi-tenancy, cardinality protection, SLO tracking

Implementation Documentation

Implementation Summary - Development phases, metrics, design decisions
Requirements - Complete requirements traceability (52 requirements)
Test Suite Summary - Test coverage and results
Valuation Matrix - Package valuation and ROI analysis

Architecture Documentation

Architecture - Monorepo design principles
Metric Retention Guide - Retention policies deep dive

Testing

The package has comprehensive test coverage with 188 tests and 476 assertions (100% passing).

Test Statistics

Total Tests: 188
Assertions: 476
Success Rate: 100%
Execution Time: ~2 seconds
PHPUnit Version: 11.0
Coverage: All public interfaces, services, value objects, enums, exceptions

Test Breakdown

TelemetryTracker: 17 tests (all metric types, cardinality protection, multi-tenancy)
HealthCheckRunner: 14 tests (priority execution, timeout handling, caching)
AlertEvaluator: 15 tests (severity mapping, deduplication, dispatching)
MetricRetentionService: 12 tests (pruning, stats, policy enforcement)
Built-in Health Checks: 130+ tests (Database, Cache, DiskSpace, Memory)

Running Tests

# Run all tests
composer test

# Run with coverage report
composer test:coverage

# Run specific test suite
vendor/bin/phpunit tests/Unit/Services/TelemetryTrackerTest.php

Documentation

Architecture - Monorepo design principles
Implementation Summary - Detailed feature breakdown
Test Suite Summary - Test coverage details
Metric Retention Guide - Retention policies

License

MIT License - see LICENSE file for details.

Roadmap

Completed ✅

TelemetryTracker with cardinality protection
HealthCheckRunner with priority-based execution
AlertEvaluator with deduplication
Built-in health checks (Database, Cache, DiskSpace, Memory)
SLOWrapper utility
MonitoringAwareTrait
Custom exceptions with factory methods
MetricRetentionService with time-based policies

Planned 🎯

Additional health checks (Queue, Storage, External APIs)
Metric aggregation service (hourly → daily → monthly)
Dashboard data export (Grafana, Prometheus format)
Anomaly detection with ML
Distributed tracing integration
Custom alert channels (Teams, Discord, Telegram)

Support

For issues, questions, or contributions:

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: docs/

Built with ❤️ for the Nexus ERP ecosystem

azaharizaman / nexus-telemetry

Maintainers

Package info

Statistics

Security

README

📋 Table of Contents

Overview

Design Philosophy

Features

✅ Metric Tracking

✅ Health Checks

✅ Alerting

✅ Utilities

Available Interfaces

Core Tracking & Storage

Health Monitoring

Alerting

Cardinality Protection

Configuration & Context

Additional Utilities

Installation

Requirements

Install via Composer

Quick Start

1. Basic Metric Tracking

2. Health Checks

3. Easy Integration with Trait

4. Automated Metric Retention

Core Components

TelemetryTracker

HealthCheckRunner

AlertEvaluator

MetricRetentionService

Advanced Usage

Custom Health Check

Custom Retention Policy

SLO Tracking Pattern

Testing

Run All Tests

Run Specific Test Suite

Test Statistics

Architecture

Package Structure

Key Design Patterns

Framework Integration

Contributing

Development Setup

Coding Standards

Pull Request Process

Documentation

Package Documentation

Implementation Documentation

Architecture Documentation

Testing

Test Statistics

Test Breakdown

Running Tests

Documentation

License

Roadmap

Completed ✅

Planned 🎯

Support