Download the PHP package azaharizaman/nexus-telemetry without Composer
On this page you can find all versions of the php package azaharizaman/nexus-telemetry. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download azaharizaman/nexus-telemetry
More information about azaharizaman/nexus-telemetry
Files in azaharizaman/nexus-telemetry
Package nexus-telemetry
Short Description Framework-agnostic monitoring, telemetry tracking, health checks, and alert management package for the Nexus ERP system
License MIT
Informations about the package nexus-telemetry
Nexus\Telemetry
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 aggregationMetricRetentionInterface- Define retention policies for metric cleanup
Health Monitoring
HealthCheckerInterface- Register and execute health checksHealthCheckInterface- Implement custom health checksScheduledHealthCheckInterface- Health checks with cron-like scheduling
Alerting
AlertGatewayInterface- Evaluate exceptions and dispatch alertsAlertDispatcherInterface- Send alerts to notification channels
Cardinality Protection
CardinalityGuardInterface- Prevent metric tag explosionCardinalityStorageInterface- Track unique tag values (HyperLogLog recommended)
Configuration & Context
SLOConfigurationInterface- Define Service Level ObjectivesSamplingStrategyInterface- Implement metric sampling (probabilistic, deterministic, adaptive)CacheRepositoryInterface- Cache health check resultsTenantContextInterface- 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
Note: Package is currently in development. Use @dev stability flag.
Quick Start
1. Basic Metric Tracking
2. Health Checks
3. Easy Integration with Trait
4. Automated Metric Retention
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:
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:
AlertEvaluator
Processes exceptions into alerts with deduplication.
Key Features:
- Automatic severity mapping
- Fingerprint-based deduplication
- Time-window silence periods
- Metadata enrichment (stack traces)
Methods:
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:
Advanced Usage
Custom Health Check
Custom Retention Policy
SLO Tracking Pattern
Testing
Run All Tests
Run Specific Test Suite
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
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:
Symfony:
Contributing
Development Setup
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
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 ✅
- [x] TelemetryTracker with cardinality protection
- [x] HealthCheckRunner with priority-based execution
- [x] AlertEvaluator with deduplication
- [x] Built-in health checks (Database, Cache, DiskSpace, Memory)
- [x] SLOWrapper utility
- [x] MonitoringAwareTrait
- [x] Custom exceptions with factory methods
- [x] 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