README

Complete telemetry and observability suite for Pixielity applications - Sentry, Pulse, Telescope, Horizon, Debugbar, and Health

Features • Installation • Sub-packages • Quick Start • Architecture • Configuration

📑 Table of Contents

Overview
Features
Sub-packages
Requirements
Installation
Quick Start
Components & Attributes
Architecture
Configuration
Real-World Examples
Performance
Security
Contributing
Credits
License

🌟 Overview

Telemetry is a production-ready observability suite that consolidates the best-in-class Laravel monitoring tools into a single, cohesive package. It eliminates the manual boilerplate of registering watchers, collectors, and health checks by leveraging an attribute-based discovery system.

Why Telemetry?

Traditional Approach:

// Manual registration across multiple config files
// Sentry middleware setup...
// Telescope watchers in TelescopeServiceProvider...
// Horizon tags in AppServiceProvider...
// Manual Health check registration...

With Telemetry:

// Automatic discovery - just add attributes to your classes
#[AsHealthCheck(name: 'database')]
class DatabaseCheck extends Check { ... }

#[AsSentryContext]
class UserContext { ... }

#[AsMetric]
class OrderMetrics { ... }

✨ Features

🎯 Unified Observability

Centralized Management - One package to rule them all. Manage Sentry, Pulse, Telescope, and more from a single entry point.
Attribute-Driven - Zero-config registration using PHP 8 attributes.
Monorepo Ready - Automatically scans all your packages for monitoring components.

⚡ Performance & Quality

Discovery Caching - Blazing fast attribute scanning with built-in caching.
Strict Typing - Full PHP 8.3+ type safety across the entire suite.
PSR-12 Compliant - Follows modern PHP coding standards.

🏗️ Flexible Integration

Pick and Choose - Use the full suite or individual sub-packages.
Extensible - Easily add your own custom collectors or watchers.
Laravel 12 Support - Built for the latest versions of the Laravel framework.

📦 Sub-packages

Telemetry is composed of several specialized sub-packages that can be used together or independently:

Package	Description	Integration
Sentry	Error tracking and context discovery	`sentry/sentry-laravel`
Pulse	Real-time dashboards and metrics	`laravel/pulse`
Telescope	Advanced application debugging	`laravel/telescope`
Horizon	Queue monitoring and metrics	`laravel/horizon`
Debugbar	Development-time debugging toolbar	`barryvdh/laravel-debugbar`
Health	System diagnostics and uptime monitoring	`spatie/laravel-health`

📋 Requirements

PHP: 8.3 or higher
Laravel: 11.0 or 12.0
Composer: 2.0 or higher

📦 Installation

Install the complete suite via Composer:

composer require pixielity/telemetry

Or install individual packages as needed:

composer require pixielity/telemetry-sentry
composer require pixielity/telemetry-pulse

🚀 Quick Start

Tag your classes: Use attributes like #[AsHealthCheck], #[AsRecorder], or #[AsSentryContext] on your components.
Automatic Registration: Telemetry will automatically discover and register these components during the application boot process.
View Data: Check your Sentry dashboard, Pulse dashboard, or Telescope UI to see your telemetry data flowing.

🎯 Components & Attributes

1. Sentry Contexts

Enrich error reports with custom user data, tags, and extra context.

Attribute: #[AsSentryContext]
Target: Classes (must be invokable)

2. Pulse Cards & Recorders

Extend your real-time dashboard with custom cards and recorders.

Attributes: #[AsCard], #[AsRecorder], #[AsFilter]
Target: Livewire components (cards) or recorder classes.

3. Telescope Watchers

Define custom application debug watchers.

Attribute: #[AsWatcher]
Target: Watcher classes.

4. Horizon Metrics & Tags

Monitor queue performance and organize jobs with tags.

Attributes: #[AsMetric], #[HorizonTag]
Target: Metric collectors or Job classes.

5. Health Checks

Monitor system uptime and resource usage.

Attribute: #[AsHealthCheck]
Target: Classes extending Spatie\Health\Checks\Check.

🏗️ Architecture

Telemetry uses a Manager Pattern for each sub-package. Each manager utilizes a shared discovery system to scan for relevant attributes across your entire application. This means you can distribute your monitoring logic across multiple packages in a monorepo, and Telemetry will find them all.

⚙️ Configuration

Publish all sub-package configurations at once:

php artisan vendor:publish --provider="Pixielity\Providers\TelemetryServiceProvider"

Individual configs can also be published using specific tags (e.g., telemetry-sentry-config).

🧪 Performance

Telemetry leverages composer-attribute-collector and internal caching to ensure that even large monorepos are scanned efficiently.

Operation	Performance
Attribute Discovery	< 5ms (Cached)
Registration Overhead	Negligible
Memory Footprint	Low

🛡️ Security

Telemetry collects sensitive application data. We recommend:

Protecting monitoring UIs with authentication.
Masking sensitive fields (passwords, PII) in Sentry and Telescope.
Only enabling Debugbar in local development.

🤝 Contributing

Please see CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

⬆ Back to Top

📜 License

Telemetry is proprietary software. See LICENSE for more information.

pixielity / telemetry

Maintainers

Details