PHPackages junixlabs/laravel-observatory - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Logging & Monitoring](/categories/logging) 4. / 5. junixlabs/laravel-observatory ActiveLibrary[Logging & Monitoring](/categories/logging) junixlabs/laravel-observatory ============================= Observability toolkit for Laravel applications - Monitor HTTP requests, outbound calls, queue jobs, and scheduled tasks with Prometheus and SidMonitor support 2.1.0(2mo ago)01.0k↓29.2%1[1 issues](https://github.com/junixlabs/laravel-observatory/issues)MITPHPPHP ^8.0CI passing Since Jan 17Pushed 2mo agoCompare [ Source](https://github.com/junixlabs/laravel-observatory)[ Packagist](https://packagist.org/packages/junixlabs/laravel-observatory)[ Docs](https://github.com/junixlabs/laravel-observatory)[ RSS](/packages/junixlabs-laravel-observatory/feed)WikiDiscussions main Synced 3d ago READMEChangelog (3)Dependencies (39)Versions (15)Used By (0) Laravel Observatory =================== [](#laravel-observatory) [![Latest Version on Packagist](https://camo.githubusercontent.com/fcec408479748ccc4900f5af951fa1fca9a79cc797400810310164345a115c09/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a756e69786c6162732f6c61726176656c2d6f627365727661746f72792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/junixlabs/laravel-observatory)[![GitHub Tests Action Status](https://camo.githubusercontent.com/0527ed628921480485fed2cfafdf42d270c4d3aaae7e321e0d4c177d5471c15d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6a756e69786c6162732f6c61726176656c2d6f627365727661746f72792f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/junixlabs/laravel-observatory/actions?query=workflow%3Arun-tests+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/b60826a8296bd2c5ccbcec40250a9c0c00bfaa42204f810490911652b4b1b094/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a756e69786c6162732f6c61726176656c2d6f627365727661746f72792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/junixlabs/laravel-observatory)[![License](https://camo.githubusercontent.com/64194b6c84c9cf5fcec38fb7f3074665f48b9e66cbf9bb7c797c112542b99411/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6a756e69786c6162732f6c61726176656c2d6f627365727661746f72792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/junixlabs/laravel-observatory)[![PHP Version](https://camo.githubusercontent.com/853f5fdaade6fda364216001c0ac62f1d66878db943bbc72b58fb473b0de7dec/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6a756e69786c6162732f6c61726176656c2d6f627365727661746f72792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/junixlabs/laravel-observatory) A comprehensive observability toolkit for Laravel applications. Monitor HTTP requests, outbound API calls, queue jobs, scheduled tasks, and exceptions with structured logging and optional Prometheus or SidMonitor metrics. Features -------- [](#features) - **Inbound Request Logging** - Automatically log all incoming HTTP requests - **Outbound HTTP Logging** - Log external API calls with service detection - **Queue Job Logging** - Track job execution with duration and memory usage - **Scheduled Task Logging** - Monitor artisan scheduled tasks lifecycle (start, finish, fail, skip) - **Exception Logging** - Structured exception logging with stack traces - **Request ID Tracking** - Correlation IDs for distributed tracing - **Sensitive Data Masking** - Automatic masking of passwords, tokens, and PII - **Dual Exporter Support** - Choose between Prometheus (pull) or SidMonitor (push) metrics - **Circuit Breaker** - Resilient push-based exporting with automatic backoff - **Zero Configuration** - Works out of the box with sensible defaults - **Grafana Dashboards** - Pre-built dashboard templates included Requirements ------------ [](#requirements) - PHP 8.0+ - Laravel 9.0, 10.0, 11.0, or 12.0 Installation ------------ [](#installation) ``` composer require junixlabs/laravel-observatory ``` The package auto-registers and works immediately - no configuration needed! Quick Start ----------- [](#quick-start) After installation, Observatory automatically: 1. Logs all incoming HTTP requests to `storage/logs/observatory.log` 2. Logs outbound HTTP calls via Laravel's HTTP client 3. Logs queue job execution 4. Logs scheduled task execution 5. Logs exceptions with context ### View Your Logs [](#view-your-logs) ``` tail -f storage/logs/observatory.log | jq ``` Configuration ------------- [](#configuration) ### Publish Config (Optional) [](#publish-config-optional) ``` php artisan vendor:publish --tag=observatory-config ``` ### Environment Variables [](#environment-variables) All features are **enabled by default**. Only set these if you need to change defaults: ``` # Disable Observatory entirely OBSERVATORY_ENABLED=false # Change log channel (default: 'observatory' -> storage/logs/observatory.log) # Use 'stderr' for Docker/K8s OBSERVATORY_LOG_CHANNEL=stderr # Disable specific loggers OBSERVATORY_INBOUND_ENABLED=false OBSERVATORY_OUTBOUND_ENABLED=false OBSERVATORY_JOBS_ENABLED=false OBSERVATORY_SCHEDULED_TASKS_ENABLED=false OBSERVATORY_EXCEPTIONS_ENABLED=false # Log request/response bodies (disabled by default - can be large) OBSERVATORY_LOG_BODY=true # Only log slow requests (0 = log all) OBSERVATORY_SLOW_THRESHOLD_MS=1000 ``` Exporters --------- [](#exporters) Observatory supports two metrics exporters. Set via `OBSERVATORY_EXPORTER` env var. ### Prometheus (default, pull-based) [](#prometheus-default-pull-based) ``` OBSERVATORY_EXPORTER=prometheus OBSERVATORY_PROMETHEUS_ENABLED=true OBSERVATORY_PROMETHEUS_STORAGE=apcu # or 'redis', 'memory' ``` Exposes a `/metrics` endpoint scraped by Prometheus. ### SidMonitor (push-based) [](#sidmonitor-push-based) ``` OBSERVATORY_EXPORTER=sidmonitor SIDMONITOR_ENDPOINT=https://api.sidmonitor.com SIDMONITOR_API_KEY=your-api-key ``` Buffers data in-memory and flushes in batches to the SidMonitor backend. Includes a circuit breaker that pauses sending after consecutive failures to avoid blocking your application. ``` # Batch settings SIDMONITOR_BATCH_SIZE=100 SIDMONITOR_BATCH_INTERVAL=10 # Circuit breaker SIDMONITOR_CIRCUIT_BREAKER_THRESHOLD=3 # failures before opening SIDMONITOR_CIRCUIT_BREAKER_COOLDOWN=30 # seconds before retry ``` Log Channel ----------- [](#log-channel) Observatory auto-registers the `observatory` log channel: - **File**: `storage/logs/observatory.log` - **Format**: JSON (Loki/ELK compatible) - **Rotation**: Daily, 14 days retention For Docker/Kubernetes, use stderr: ``` OBSERVATORY_LOG_CHANNEL=stderr ``` Custom Headers -------------- [](#custom-headers) Extract custom headers into logs (multi-tenant, workspace, etc.): ``` // config/observatory.php 'inbound' => [ 'custom_headers' => [ 'X-Workspace-Id' => 'workspace_id', 'X-Tenant-Id' => 'tenant_id', 'X-Correlation-Id' => 'correlation_id', ], ], ``` Result in logs: ``` { "request_id": "abc-123", "method": "POST", "path": "/api/users", "workspace_id": "ws-456", "tenant_id": "tenant-789" } ``` Service Detection ----------------- [](#service-detection) Identify external services in outbound logs: ``` // config/observatory.php 'outbound' => [ 'services' => [ '*.stripe.com' => 'stripe', '*.amazonaws.com' => 'aws', '*.sendgrid.com' => 'sendgrid', 'api.myservice.com' => 'my_service', ], ], ``` Excluding Paths/Jobs/Tasks -------------------------- [](#excluding-pathsjobstasks) ``` // config/observatory.php 'inbound' => [ 'exclude_paths' => [ 'telescope*', 'horizon*', 'health', 'metrics', ], ], 'jobs' => [ 'exclude_jobs' => [ 'App\Jobs\InternalHealthCheck', ], ], 'scheduled_tasks' => [ 'exclude_commands' => [ 'schedule:run', ], ], ``` Structured Log Examples ----------------------- [](#structured-log-examples) ### Inbound Request [](#inbound-request) ``` { "message": "HTTP_REQUEST", "context": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "type": "inbound", "method": "POST", "url": "https://example.com/api/v1/orders", "path": "api/v1/orders", "route": "orders.store", "status_code": 201, "duration_ms": 145.23, "ip": "192.168.1.1", "user_agent": "Mozilla/5.0...", "user_id": 123, "memory_mb": 45.2, "environment": "production" } } ``` ### Outbound Request [](#outbound-request) ``` { "message": "HTTP_OUTBOUND", "context": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "type": "outbound", "service": "stripe", "method": "POST", "url": "https://api.stripe.com/v1/charges", "host": "api.stripe.com", "status_code": 200, "duration_ms": 523.45, "environment": "production" } } ``` ### Job Processed [](#job-processed) ``` { "message": "JOB_PROCESSED", "context": { "job_id": "123", "job_name": "App\\Jobs\\ProcessOrder", "queue": "orders", "status": "processed", "duration_ms": 1234.56, "attempts": 1, "memory": { "used_mb": 12.5, "peak_mb": 45.2 }, "environment": "production" } } ``` ### Scheduled Task [](#scheduled-task) ``` { "message": "SCHEDULED_TASK", "context": { "command": "reports:generate", "description": "Generate daily reports", "expression": "0 2 * * *", "status": "completed", "duration_ms": 4523.12, "exit_code": 0, "memory": { "used_mb": 32.1, "peak_mb": 64.5 }, "environment": "production" } } ``` ### Exception [](#exception) ``` { "message": "EXCEPTION", "context": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "exception_class": "App\\Exceptions\\PaymentException", "message": "Payment declined", "code": 402, "file": "/app/Services/PaymentService.php", "line": 145, "request": { "method": "POST", "url": "https://example.com/api/orders", "path": "api/orders" }, "user": { "id": 123 }, "trace": ["..."], "environment": "production" } } ``` Prometheus Metrics (Optional) ----------------------------- [](#prometheus-metrics-optional) ``` OBSERVATORY_PROMETHEUS_ENABLED=true OBSERVATORY_PROMETHEUS_STORAGE=apcu # or 'redis', 'memory' ``` Visit `http://your-app.test/metrics` to see metrics. ### Available Metrics [](#available-metrics) MetricTypeDescription`{app}_http_requests_total`CounterTotal HTTP requests`{app}_http_request_duration_seconds`HistogramRequest latency`{app}_http_outbound_requests_total`CounterOutbound HTTP requests`{app}_jobs_processed_total`CounterQueue jobs processed`{app}_scheduled_tasks_total`CounterScheduled tasks executed`{app}_exceptions_total`CounterExceptions count### Prometheus Auth [](#prometheus-auth) ``` OBSERVATORY_METRICS_AUTH=true OBSERVATORY_METRICS_USER=prometheus OBSERVATORY_METRICS_PASS=secret ``` Grafana Dashboards ------------------ [](#grafana-dashboards) Import pre-built dashboards from the `dashboards/` directory: DashboardData SourceDescription`observatory-dashboard.json`LokiRequest logs, user analytics, exceptions`prometheus-dashboard.json`PrometheusMetrics overview, latency percentiles### LogQL Query Examples [](#logql-query-examples) ``` # All requests {job="laravel-observatory"} | json | message="HTTP_REQUEST" # Errors only {job="laravel-observatory"} | json | status_code >= 400 # By user {job="laravel-observatory"} | json | user_id="123" # Slow requests (>1s) {job="laravel-observatory"} | json | duration_ms > 1000 # External service calls {job="laravel-observatory"} | json | type="outbound" | service="stripe" # Scheduled tasks {job="laravel-observatory"} | json | message="SCHEDULED_TASK" # Exceptions {job="laravel-observatory"} | json | message="EXCEPTION" ``` Kubernetes Deployment --------------------- [](#kubernetes-deployment) See [k8s/README.md](k8s/README.md) for Kubernetes deployment with Loki stack. Upgrading from v1.x ------------------- [](#upgrading-from-v1x) ### Breaking Changes in v2.0 [](#breaking-changes-in-v20) 1. **SidMonitor env vars renamed**: `OBSERVATORY_SIDMONITOR_*` is now `SIDMONITOR_*` 2. **ExporterInterface**: New `recordScheduledTask()` method required for custom exporters Update your `.env` file if using SidMonitor: ``` # Before (v1.x) OBSERVATORY_SIDMONITOR_ENDPOINT=... OBSERVATORY_SIDMONITOR_API_KEY=... # After (v2.0) SIDMONITOR_ENDPOINT=... SIDMONITOR_API_KEY=... ``` Re-publish config if upgrading: ``` php artisan vendor:publish --tag=observatory-config --force ``` Testing ------- [](#testing) ``` composer test ``` Changelog --------- [](#changelog) See [CHANGELOG](CHANGELOG.md) for recent changes. Contributing ------------ [](#contributing) See [CONTRIBUTING](CONTRIBUTING.md) for details. Security -------- [](#security) Report security issues to instead of the issue tracker. Credits ------- [](#credits) - [JunixLabs](https://github.com/junixlabs) - [All Contributors](../../contributors) License ------- [](#license) MIT License. See [LICENSE](LICENSE) for details. ### Health Score 43 — FairBetter than 89% of packages Maintenance84 Actively maintained with recent releases Popularity20 Limited adoption so far Community10 Small or concentrated contributor base Maturity47 Maturing project, gaining track record Bus Factor1 Top contributor holds 54.5% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~8 days Recently: every ~21 days Total 11 Last Release 82d ago Major Versions v1.3.3 → 2.0.0-beta.12026-03-19 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/248264452?v=4)[junixlabs](/maintainers/junixlabs)[@junixlabs](https://github.com/junixlabs) --- Top Contributors [![chuongld20](https://avatars.githubusercontent.com/u/128578760?v=4)](https://github.com/chuongld20 "chuongld20 (54 commits)")[![Dchuong03](https://avatars.githubusercontent.com/u/95289961?v=4)](https://github.com/Dchuong03 "Dchuong03 (41 commits)")[![junixlabs](https://avatars.githubusercontent.com/u/248264452?v=4)](https://github.com/junixlabs "junixlabs (4 commits)") --- Tags laravelloggingmonitoringMetricsapmtracingobservabilityprometheus ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/junixlabs-laravel-observatory/health.svg) ``` [![Health](https://phpackages.com/badges/junixlabs-laravel-observatory/health.svg)](https://phpackages.com/packages/junixlabs-laravel-observatory) ``` ### Alternatives [roots/acorn Framework for Roots WordPress projects built with Laravel components. 9762.4M131](/packages/roots-acorn)[psalm/plugin-laravel Psalm plugin for Laravel 3355.3M346](/packages/psalm-plugin-laravel)[laravel/cashier Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services. 2.6k29.9M148](/packages/laravel-cashier)[laravel/mcp Rapidly build MCP servers for your Laravel applications. 77022.3M151](/packages/laravel-mcp)[laravel/pulse Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application. 1.7k15.1M132](/packages/laravel-pulse)[api-platform/laravel API Platform support for Laravel 58171.6k14](/packages/api-platform-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)