README

**Complete telemetry and observability suite for Pixielity applications - Sentry, Pulse, Telescope, Horizon, Debugbar, and Health** [](https://packagist.org/packages/pixielity/laravel-telemetry) [](https://packagist.org/packages/pixielity/laravel-telemetry) [](https://github.com/pixielity-co/laravel-telemetry/actions/workflows/tests.yml) [](https://phpstan.org/) [](https://packagist.org/packages/pixielity/laravel-telemetry) [](https://packagist.org/packages/pixielity/laravel-telemetry) [Features](#-features) • [Installation](#-installation) • [Sub-packages](#-sub-packages) • [Quick Start](#-quick-start) • [Architecture](#-architecture) • [Configuration](#-configuration)

📑 Table of Contents

• Overview
• Features
• Sub-packages
• Requirements
• Installation
• Quick Start
• Components & Attributes
  • Sentry Contexts
  • Pulse Cards & Recorders
  • Telescope Watchers
  • Horizon Metrics & Tags
  • Health Checks
  • Debugbar Collectors
• 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/laravel-telemetry

Or install individual packages as needed:

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

🚀 Quick Start

1. Tag your classes: Use attributes like #[AsHealthCheck], #[AsRecorder], or #[AsSentryContext] on your components.
2. Automatic Registration: Telemetry will automatically discover and register these components during the application boot process.
3. 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.