PHPackages                             fogeto/laravel-server-orchestrator - 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. fogeto/laravel-server-orchestrator

ActiveLibrary[Logging & Monitoring](/categories/logging)

fogeto/laravel-server-orchestrator
==================================

Laravel Prometheus monitoring package for multi-project server orchestration. Compatible with Laravel 9-12.

v1.1.11(1mo ago)21.9k↓42.4%MITPHPPHP ^8.0

Since Feb 10Pushed 1mo agoCompare

[ Source](https://github.com/fogeto/laravel-server-orchestrator)[ Packagist](https://packagist.org/packages/fogeto/laravel-server-orchestrator)[ RSS](/packages/fogeto-laravel-server-orchestrator/feed)WikiDiscussions main Synced 3d ago

READMEChangelog (1)Dependencies (24)Versions (23)Used By (0)

Laravel Server Orchestrator
===========================

[](#laravel-server-orchestrator)

[![Laravel 9.x-12.x](https://camo.githubusercontent.com/0e7c8fcc5ec17df765bf4888fc548bdd7237058d951427b900967440cfb303d6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d392e782d2d31322e782d7265642e737667)](https://laravel.com)[![PHP 8.0+](https://camo.githubusercontent.com/d4b5fa4adf514144779a7864904c5e15236c0e798635240c7f6ce9a455657b80/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e302532422d626c75652e737667)](https://php.net)

Laravel uygulamaları için standart bir metrics ve APM paketi.

Paket üç yüzey üretir:

- `GET /metrics`
- `GET /__apm/errors`
- `GET /apm/errors`

HTTP, SQL ve DB client metric aileleri Prometheus formatında sunulur. APM hata event'leri ise seçilen storage'a (MongoDB veya Redis) yazılır ve limitli JSON feed olarak okunur.

Özellikler
----------

[](#özellikler)

ÖzellikAçıklamaHTTP metrics`http_request_duration_seconds`, `http_requests_received_total`, `http_requests_in_progress`SQL metrics`sql_query_duration_seconds`, `sql_query_errors_total`DB client metrics`db_client_connections_max`, `db_client_connections_usage`, `db_client_connections_pending_requests`APM feed4xx/5xx response event'leri seçilen storage'da 1 gün tutulurMetrics driver seçimi`redis` veya `in_memory`Laravel 9-12 desteğiKernel ve Router akışlarıyla uyumluMigration komutuEski inline entegrasyonları temizlemek için `orchestrator:migrate`Gereksinimler
-------------

[](#gereksinimler)

BileşenGereksinimPHP`^8.0`Laravel`^9.0Prometheus client`promphp/prometheus_client_php ^2.2`Redis`metrics_storage=redis` için gerekliext-mongodbMongo tabanlı APM persistence için gerekliext-redis`ORCHESTRATOR_REDIS_CLIENT=phpredis` için gerekli> Seçilen APM store için gerekli extension/config yoksa package çalışmaya devam eder; sadece APM persistence devre dışı kalır ve `/apm/errors` boş array döner.

Storage modeli
--------------

[](#storage-modeli)

Referans .NET mimarisi metrics için process RAM kullanır. Laravel/FPM altında request'ler process belleğini paylaşmadığı için paket varsayılan olarak Redis-backed metrics driver ile gelir.

Veri tipiVarsayılan storageNotHTTP/SQL/DB metricsRedisFPM için güvenli varsayılanHTTP/SQL/DB metricsInMemoryUzun ömürlü runtime'larda seçilebilirAPM event'leriMongoDB veya RedisTTL 1 günKurulum
-------

[](#kurulum)

### 1. Repository tanımı

[](#1-repository-tanımı)

Packagist yerine doğrudan repo kullanıyorsanız uygulamanın `composer.json` dosyasına ekleyin:

```
{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/fogeto/laravel-server-orchestrator"
        }
    ]
}
```

Lokal geliştirmede `path` repository de kullanılabilir.

### 2. Paketi yükleme

[](#2-paketi-yükleme)

```
composer require fogeto/laravel-server-orchestrator:dev-main
```

Laravel auto-discovery sayesinde provider otomatik kayıt edilir.

### 3. Prefix ayarı

[](#3-prefix-ayarı)

```
ORCHESTRATOR_PREFIX=myapp
```

Redis metrics driver kullanan her proje benzersiz prefix vermelidir.

### 4. Config publish (opsiyonel)

[](#4-config-publish-opsiyonel)

```
php artisan vendor:publish --tag=server-orchestrator-config
```

### 5. Route doğrulama

[](#5-route-doğrulama)

```
php artisan route:list | grep -E "metrics|apm"
```

Beklenen yüzey:

```
GET|HEAD  metrics
GET|HEAD  __apm/errors
GET|HEAD  apm/errors

```

Mevcut projeden geçiş
---------------------

[](#mevcut-projeden-geçiş)

Eski inline Prometheus entegrasyonu olan projelerde:

```
php artisan orchestrator:migrate --dry-run
php artisan orchestrator:migrate --prefix=myapp
php artisan optimize:clear
```

Migration komutu eski middleware/provider/route kalıntılarını temizlemeye yardım eder.

Kullanım
--------

[](#kullanım)

### Metrics

[](#metrics)

```
curl http://localhost:8000/metrics
```

### APM event feed

[](#apm-event-feed)

```
curl http://localhost:8000/apm/errors
curl http://localhost:8000/__apm/errors?limit=50
```

APM feed varsayılan olarak sadece incoming event'leri listeler.

### Test amaçlı hata üretme

[](#test-amaçlı-hata-üretme)

```
curl -i http://localhost:8000/olmayan-endpoint
curl http://localhost:8000/apm/errors
```

Toplanan yüzey
--------------

[](#toplanan-yüzey)

### HTTP metrics

[](#http-metrics)

MetrikTipLabel'lar`http_request_duration_seconds`Histogram`code`, `method`, `controller`, `action`, `endpoint``http_requests_received_total`Counter`code`, `method`, `controller`, `action`, `endpoint``http_requests_in_progress`Gauge`method`, `controller`, `action`, `endpoint`### SQL metrics

[](#sql-metrics)

MetrikTipVarsayılan label'lar`sql_query_duration_seconds`Histogram`query_hash`, `operation`, `table``sql_query_errors_total`Counter`query_hash`, `operation`, `table`> `ORCHESTRATOR_SQL_QUERY_LABEL=true` yapılırsa `sql_query_duration_seconds` metric'ine `query` label'ı eklenir.

### DB client metrics

[](#db-client-metrics)

MetrikTipNot`db_client_connections_max`GaugeMySQL `max_connections` üzerinden`db_client_connections_usage`Gauge`idle` ve `used` label'ları ile`db_client_connections_pending_requests`GaugeLaravel tarafında gözlemlenmediği için varsayılan `0`### PHP / process metrics

[](#php--process-metrics)

MetrikTipNot`php_info`Gauge`version` label'ı ile PHP runtime bilgisi`process_uptime_seconds`GaugeRequest process uptime`process_memory_usage_bytes`GaugeAnlık gerçek PHP bellek kullanımı (`memory_get_usage(false)`)`process_memory_allocated_bytes`GaugePHP allocator tarafından ayrılan anlık bellek (`memory_get_usage(true)`)`process_memory_peak_bytes`GaugePeak gerçek PHP bellek kullanımı (`memory_get_peak_usage(false)`)`process_memory_peak_allocated_bytes`GaugePHP allocator tarafından ayrılan peak bellek (`memory_get_peak_usage(true)`)`process_memory_limit_bytes`GaugePHP `memory_limit` değeri`php_opcache_enabled`GaugeOPcache aktifse `1`, değilse `0``php_opcache_hit_rate`GaugeOPcache hit rate yüzdesi`php_opcache_memory_used_bytes`GaugeOPcache kullanılan bellek### Varsayılan yüzeyde olmayanlar

[](#varsayılan-yüzeyde-olmayanlar)

- `http_requests_total`
- `http_errors_total`
- `db_connections_active`
- `db_connections_max`
- `app_health_status`

Konfigürasyon
-------------

[](#konfigürasyon)

### Temel env değişkenleri

[](#temel-env-değişkenleri)

DeğişkenVarsayılanAçıklama`ORCHESTRATOR_ENABLED``true`Paketi aç/kapat`ORCHESTRATOR_PREFIX``APP_NAME`Redis prefix izolasyonu`ORCHESTRATOR_METRICS_STORAGE``redis``redis` veya `in_memory``ORCHESTRATOR_REDIS_CONNECTION``default`Redis bağlantısı`ORCHESTRATOR_REDIS_CLIENT`Laravel defaultOpsiyonel `predis` veya `phpredis` override`ORCHESTRATOR_METRICS_TTL``86400`Sadece Redis metrics driver için`ORCHESTRATOR_SQL_ENABLED``true`SQL metrics aç/kapat`ORCHESTRATOR_SQL_QUERY_LABEL``false`SQL `query` label'ını aç/kapat`ORCHESTRATOR_SQL_MAX_UNIQUE_QUERIES``100`Benzersiz query hash sınırı`ORCHESTRATOR_APM_ENABLED``true`APM capture aç/kapat`ORCHESTRATOR_APM_STORE``mongo`APM storage: `mongo` veya `redis``ORCHESTRATOR_APM_SERVICE``ORCHESTRATOR_PREFIX`APM event service/proje kimliği`ORCHESTRATOR_APM_SCOPE_BY_SERVICE``true`Mongo okuma/temizlemeyi service ile sınırla`ORCHESTRATOR_APM_TTL``86400`APM TTL, 1 gün`ORCHESTRATOR_APM_DEFAULT_LIMIT``200`Endpoint varsayılan limit`ORCHESTRATOR_APM_MAX_LIMIT``500`Endpoint üst limit`ORCHESTRATOR_APM_BYPASS_THRESHOLD_BYTES``5242880`5MB üstü capture bypass`ORCHESTRATOR_APM_REDIS_CONNECTION``ORCHESTRATOR_REDIS_CONNECTION`Redis APM bağlantısı`ORCHESTRATOR_APM_REDIS_PREFIX``ORCHESTRATOR_PREFIX`Redis APM key prefix### Mongo APM ayarları

[](#mongo-apm-ayarları)

Mongo APM persistence için `ORCHESTRATOR_APM_STORE=mongo` kullanılır:

```
ORCHESTRATOR_APM_STORE=mongo
Logging__MongoDB__ConnectionString=mongodb://user:pass@host:27017/?authSource=admin
Logging__MongoDB__DatabaseName=ecommerce
```

Collection adı sabit olarak `ApmErrors` kullanılır.

Database adı proje bazlı seçilmelidir. Örnek: `ecommerce`, `crm`, `hrportal`.

### Redis APM ayarları

[](#redis-apm-ayarları)

Mongo kullanmak istemeyen kurulumlarda APM event'leri Redis sorted set + TTL'li event key'lerinde tutulabilir:

```
ORCHESTRATOR_APM_STORE=redis
ORCHESTRATOR_REDIS_CONNECTION=default
ORCHESTRATOR_REDIS_CLIENT=predis
# ORCHESTRATOR_REDIS_CLIENT=phpredis
ORCHESTRATOR_APM_TTL=86400
```

Redis APM storage, event'leri `ORCHESTRATOR_PREFIX` veya `ORCHESTRATOR_APM_REDIS_PREFIX` ile izole eder.

APM endpoint'leri paket içinde IP doğrulaması yapmaz. Production'da erişimi gerekiyorsa reverse proxy, firewall veya uygulama dışı auth katmanı ile kısıtlayın.

Çoklu proje yapısı
------------------

[](#çoklu-proje-yapısı)

Redis metrics veya Redis APM driver kullanan birden fazla proje için prefix'leri ayırın:

```
ORCHESTRATOR_PREFIX=ikbackend
ORCHESTRATOR_PREFIX=hrportal
ORCHESTRATOR_PREFIX=crm
```

Mongo APM kullanılıyorsa event'lere `service` alanı yazılır ve varsayılan olarak `/apm/errors` sadece kendi service kayıtlarını döndürür.

Özel metric ekleme
------------------

[](#özel-metric-ekleme)

Package `CollectorRegistry` singleton'ını container'a kaydeder:

```
use Prometheus\CollectorRegistry;

$registry = app(CollectorRegistry::class);

$counter = $registry->getOrRegisterCounter(
        'app',
        'orders_total',
        'Total orders placed',
        ['status']
);

$counter->inc(['completed']);
```

Prometheus scrape örneği
------------------------

[](#prometheus-scrape-örneği)

```
scrape_configs:
    - job_name: 'my-api'
        metrics_path: '/metrics'
        scrape_interval: 15s
        static_configs:
            - targets: ['my-api.example.com']
```

Sorun giderme
-------------

[](#sorun-giderme)

### `/apm/errors` boş dönüyor

[](#apmerrors-boş-dönüyor)

- `ORCHESTRATOR_APM_STORE` doğru mu (`mongo` veya `redis`)?
- Mongo seçildiyse Mongo env'leri dolu ve `ext-mongodb` yüklü mü?
- Redis seçildiyse Redis connection çalışıyor mu, `phpredis` seçildiyse `ext-redis` yüklü mü?
- Gerçekten 4xx/5xx event oluştu mu?

### `/metrics` sayaçları FPM altında sıfırlanıyor

[](#metrics-sayaçları-fpm-altında-sıfırlanıyor)

- `ORCHESTRATOR_METRICS_STORAGE=in_memory` kullanıyorsan FPM altında beklenen davranış budur.
- FPM için `redis` driver kullan.

### Publish edilen config eski kaldı

[](#publish-edilen-config-eski-kaldı)

`vendor:publish` mevcut dosyayı ezmez. `config/server-orchestrator.php` içindeki yeni anahtarları elle merge et veya kontrollü şekilde `--force` kullan.

Lisans
------

[](#lisans)

MIT

### Job/Queue Metriği Örneği

[](#jobqueue-metriği-örneği)

```
// app/Jobs/ProcessPayment.php
class ProcessPayment implements ShouldQueue
{
    public function handle(): void
    {
        $start = microtime(true);

        // ... iş mantığı ...

        $duration = microtime(true) - $start;

        $histogram = app(CollectorRegistry::class)->getOrRegisterHistogram(
            'app', 'job_duration_seconds', 'Job processing time',
            ['job'], [0.1, 0.5, 1, 5, 30, 60]
        );
        $histogram->observe($duration, ['process_payment']);
    }
}
```

---

Route Koruma (Güvenlik)
-----------------------

[](#route-koruma-güvenlik)

Metrics endpoint'ini production'da dışarıya açık bırakmayın!

### Yöntem 1: Auth Middleware

[](#yöntem-1-auth-middleware)

```
// config/server-orchestrator.php
'routes' => [
    'middleware' => ['auth:sanctum'],
],
```

### Yöntem 2: IP Kısıtlama

[](#yöntem-2-ip-kısıtlama)

```
// app/Http/Middleware/MetricsIpWhitelist.php
class MetricsIpWhitelist
{
    public function handle(Request $request, Closure $next): Response
    {
        $allowed = ['127.0.0.1', '10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'];

        foreach ($allowed as $ip) {
            if ($request->ip() === $ip) {
                return $next($request);
            }
        }

        abort(403, 'Forbidden');
    }
}

// config/server-orchestrator.php
'routes' => [
    'middleware' => [\App\Http\Middleware\MetricsIpWhitelist::class],
],
```

### Yöntem 3: Route'ları Devre Dışı Bırakıp Kendiniz Tanımlama

[](#yöntem-3-routeları-devre-dışı-bırakıp-kendiniz-tanımlama)

```
// config/server-orchestrator.php
'routes' => [
    'enabled' => false, // Paketin route'larını kapat
],

// routes/api.php — Kendi tanımınız
Route::middleware(['auth:sanctum'])->group(function () {
    Route::get('/metrics', [\Fogeto\ServerOrchestrator\Http\Controllers\MetricsController::class, 'index']);
});
```

---

Prometheus & Grafana Entegrasyonu
-------------------------------------

[](#prometheus--grafana-entegrasyonu)

### Prometheus Scrape Config

[](#prometheus-scrape-config)

```
# prometheus.yml
scrape_configs:
  - job_name: 'laravel-app'
        metrics_path: '/metrics'
    scrape_interval: 15s
    static_configs:
      - targets: ['your-app.example.com']
    # Auth gerekiyorsa:
    # bearer_token: 'your-token'
```

### Faydalı Grafana Sorguları (PromQL)

[](#faydalı-grafana-sorguları-promql)

```
# Son 5 dakikadaki ortalama response süresi
rate(http_request_duration_seconds_sum[5m]) / rate(http_request_duration_seconds_count[5m])

# Saniyedeki istek sayısı (RPS)
rate(http_requests_received_total[5m])

# p95 response süresi
histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))

# p99 response süresi
histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))

# DB connection kullanım oranı (%)
db_client_connections_usage{state="used"} / db_client_connections_max * 100

# En yavaş endpoint'ler (p95)
histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (endpoint, le))

# SQL hata oranı
rate(sql_query_errors_total[5m])

```

---

Sorun Giderme (SSS)
-------------------

[](#sorun-giderme-sss)

### 1. Metriklerde sadece DB/SQL metrikleri var, HTTP metrikleri yok

[](#1-metriklerde-sadece-dbsql-metrikleri-var-http-metrikleri-yok)

**Sebep:** Henüz uygulama trafiği oluşmamıştır.

**Çözüm:** HTTP metrikleri middleware tarafından istek sırasında kaydedilir. Herhangi bir API endpoint'ine istek atın, ardından `/metrics`'i tekrar kontrol edin.

### 2. `/metrics` endpoint'i çok yavaş (10+ saniye)

[](#2-metrics-endpointi-çok-yavaş-10-saniye)

**Sebep:** DB durum sorguları yavaşlıyor veya MySQL dışı sürücüde sessiz fallback yaşanıyordur.

**Çözüm:** `/metrics` render edilirken PHP/process/opcache metrikleriyle birlikte `db_client_*` metrikleri de toplanır. Gerekirse config'den DB metriklerini kapatın:

```
'system_metrics' => [
    'database' => false,
],
```

### 3. `composer require` sırasında hata alıyorum

[](#3-composer-require-sırasında-hata-alıyorum)

**Sebep:** `predis/predis` versiyon uyumsuzluğu.

**Çözüm:** Paket `predis/predis ^2.0|^3.0` kabul eder. composer.json'ınızdaki predis versiyonunu kontrol edin:

```
composer show predis/predis
```

### 4. Route'lar görünmüyor (`route:list`'te yok)

[](#4-routelar-görünmüyor-routelistte-yok)

**Kontrol edin:**

```
# Config cache'ini temizleyin
php artisan config:clear

# Autoload'u yenileyin
composer dump-autoload

# Paketin keşfedildiğini doğrulayın
php artisan package:discover
```

### 5. Redis'te eski metrikler silinmiyor

[](#5-rediste-eski-metrikler-silinmiyor)

**Sebep:** Redis prefix uyumsuzluğu olabilir.

**Çözüm:** Paket, Laravel'in Redis prefix'ini (`laravel_database_`) otomatik algılar. `config/database.php` içindeki Redis prefix'i ile `ORCHESTRATOR_PREFIX` değerinizin beklediğiniz key setini ürettiğini kontrol edin.

### 6. Aynı Redis'te iki projenin verileri karışıyor

[](#6-aynı-rediste-iki-projenin-verileri-karışıyor)

**Sebep:** İki proje aynı `ORCHESTRATOR_PREFIX` kullanıyordur.

**Çözüm:** Her projenin `.env` dosyasında **benzersiz** bir `ORCHESTRATOR_PREFIX` değeri olmalıdır.

### 7. `ORCHESTRATOR_ENABLED=false` yaptım ama route'lar hâlâ var

[](#7-orchestrator_enabledfalse-yaptım-ama-routelar-hâlâ-var)

**Çözüm:**

```
php artisan config:clear
php artisan route:clear
```

---

Lisans
------

[](#lisans-1)

MIT License — [LICENSE](LICENSE) dosyasına bakın.

---

**Fogeto** tarafından ❤️ ile geliştirilmiştir.

###  Health Score

46

—

FairBetter than 92% of packages

Maintenance91

Actively maintained with recent releases

Popularity24

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~5 days

Total

22

Last Release

44d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/85bdc3325d4158e01f16495c1069a83194ef0b5977c611de23cc5ed728c4977c?d=identicon)[mustafaoguzbaran](/maintainers/mustafaoguzbaran)

---

Top Contributors

[![mustafaoguzbaran](https://avatars.githubusercontent.com/u/53480330?v=4)](https://github.com/mustafaoguzbaran "mustafaoguzbaran (31 commits)")

---

Tags

laravelmonitoringMetricsobservabilityprometheusorchestrator

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/fogeto-laravel-server-orchestrator/health.svg)

```
[![Health](https://phpackages.com/badges/fogeto-laravel-server-orchestrator/health.svg)](https://phpackages.com/packages/fogeto-laravel-server-orchestrator)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k15.1M132](/packages/laravel-pulse)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

77022.3M151](/packages/laravel-mcp)[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)