🇸🇦 العربية | 🇬🇧 English

📈 eidcloud-telemetry

Ultra-lightweight zero-dependency observability stack for logs, metrics, and waterfall distributed traces in pure PHP 8.2+ (Sub-50KB).

eidcloud-telemetry provides an enterprise-ready alternative to bloated, heavy APM agents and complex OpenTelemetry setups. Designed specifically for high-throughput PHP services, serverless microservices, and CLI workers that require instant observability without adding hundreds of external vendor packages.

---

🚀 Architecture Overview

flowchart TD
    App[PHP 8.2+ Application] -->|trace / span| Tracer[Structured Tracer]
    App -->|inc / set / record| Metrics[Metrics Registry]
    App -->|context-correlated log| Logger[JSON Structured Logger]

    subgraph EidCloud Telemetry Engine
        Tracer --> Context[Context Propagation]
        Context --> SpanTree[Span Hierarchy & Timing]
        Metrics --> Stats[p50 / p95 / p99 Percentiles & Buckets]
        Logger --> Correlator[Trace & Span Correlation]
    end

    SpanTree --> Exporters{Telemetry Exporters}
    Stats --> PromExporter[Prometheus Metrics Endpoint]
    Correlator --> StdoutStream[stdout / JSON File]

    Exporters -->|CLI Flame-Graph| CLI[bin/eidcloud-telemetry]
    Exporters -->|Persistence| JSONFile[JSON File Exporter]
    Exporters -->|Queryable Store| SQLite[SQLite Exporter]
    Exporters -->|OTLP Protocol| OTel[OpenTelemetry Collector]

Loading

---

✨ Features & Capabilities

• Zero External Dependencies: Standard PHP 8.2+ with PSR-4 autoloading or standalone autoloader (src/autoload.php). Entire codebase is sub-50KB.
• Distributed Tracing:
  • High-precision nanosecond timestamps (hrtime).
  • Automatic parent-child span hierarchy and context propagation.
  • Tagging, status codes (OK, ERROR), and structured span events.
  • Automatic error and exception capture via callable wrapping ($telemetry->trace(...)).
• Real-Time Metrics Collection:
  • Counters: Monotonically increasing values with multidimensional labels.
  • Gauges: Arbitrary float values with increment/decrement capabilities.
  • Histograms: Latency and size distribution analysis with configurable buckets and linear interpolated percentile calculations ($p50, p90, p95, p99$).
  • Built-in Prometheus text exposition format export ($registry->toPrometheus()).
• Structured JSON Logging:
  • Context-correlated logs automatically inheriting ambient trace_id and span_id.
  • Configurable stream target (php://stdout, files, or in-memory buffer).
• Flexible Exporters:
  • CLI Waterfall Flame-Graph: ANSI-colored terminal waterfall timeline for immediate visual debugging.
  • JSON File Exporter: High-throughput file dumping with automatic array merging.
  • SQLite Exporter: Zero-configuration relational storage with indexed trace queries.
  • OTLP Exporter: OpenTelemetry Protocol v1 JSON format ready for Grafana Tempo, SigNoz, Jaeger, or Datadog.
• CLI Executable (bin/eidcloud-telemetry):
  • php bin/eidcloud-telemetry view <file>: Render full terminal waterfall timeline.
  • php bin/eidcloud-telemetry waterfall --file=<file> --trace-id=<id>: Deep dive into individual traces.
  • php bin/eidcloud-telemetry stats <file>: Analyze span counts, errors, and percentile metrics.

---

📦 Installation

Install via Composer into your PHP 8.2+ project:

composer require eidcloud/telemetry

Or clone directly with zero dependencies:

git clone https://github.com/eidcloud/eidcloud-telemetry.git

---

⚡ Quick Start

1. Unified Telemetry Usage

<?php

require_once __DIR__ . '/vendor/autoload.php';

use EidCloud\Telemetry\Telemetry;
use EidCloud\Telemetry\Exporter\JsonFileExporter;
use EidCloud\Telemetry\Tracer\Span;

// Initialize telemetry facade
$telemetry = Telemetry::init('order-service');
$telemetry->addExporter(new JsonFileExporter(__DIR__ . '/traces.json'));

// Execute traced operation with automatic nested spans
$telemetry->trace('http.handle_order', function (Span $rootSpan) use ($telemetry) {
    $rootSpan->setTag('http.method', 'POST');
    $rootSpan->setTag('order.id', 'ord_12345');

    // Child span 1
    $telemetry->trace('auth.verify_token', function () {
        usleep(5000); // 5ms
    });

    // Child span 2
    $telemetry->trace('db.save_order', function (Span $span) {
        $span->setTag('db.table', 'orders');
        usleep(12000); // 12ms
    });

    // Record metrics
    $telemetry->counter('orders_placed_total')->inc(1, ['status' => 'success']);
    $telemetry->histogram('order_latency_ms')->record(17.5);

    // Correlated log entry (automatically attaches active trace_id and span_id)
    $telemetry->info('Order successfully created', ['order_id' => 'ord_12345']);
});

// Flush spans to configured exporters
$telemetry->flush();

// Render CLI waterfall directly
echo $telemetry->renderWaterfall();

---

🖥️ CLI Usage

The bundled CLI tool bin/eidcloud-telemetry provides instant visualization and APM metrics in your terminal:

# View trace waterfall from JSON or SQLite file
php bin/eidcloud-telemetry view traces.json

# Filter specific trace ID
php bin/eidcloud-telemetry waterfall --file=traces.json --trace-id=4f3a8b2c1d0e4f5a6b7c8d9e0f1a2b3c

# Compute latency statistics and percentiles
php bin/eidcloud-telemetry stats traces.json

CLI Terminal Output Sample

┌──────────────────────────────────────────────────────────────────────────────┐
│ TRACE WATERFALL: 4f3a8b2c1d0e4f5a (Total: 17.52 ms, 3 spans)                 │
├──────────────────────────────────────────────────────────────────────────────┤
 http.handle_order                  │ ████████████████████████████████████ │ 17.52ms  
 └─ auth.verify_token               │ ████████                             │  5.12ms  
 └─ db.save_order                   │             ████████████████████     │ 12.38ms  
└──────────────────────────────────────────────────────────────────────────────┘

=== EidCloud Telemetry Span Summary ===
 Total Traces:     1
 Total Spans:      3
 Failed Spans:     0 (0.0%)
 Average Duration: 11.67 ms
 Min Duration:     5.12 ms
 Max Duration:     17.52 ms
 Latency p50:      12.38 ms
 Latency p95:      17.52 ms
 Latency p99:      17.52 ms

---

📊 Metrics Exposition (Prometheus)

Expose metrics for Prometheus scraping in one line:

header('Content-Type: text/plain; version=0.0.4');
echo $telemetry->getMetrics()->toPrometheus();

Output:

# HELP orders_placed_total Total placed orders
# TYPE orders_placed_total counter
orders_placed_total{status="success"} 1
# HELP order_latency_ms Order processing latency
# TYPE order_latency_ms histogram
order_latency_ms_bucket{le="10"} 0
order_latency_ms_bucket{le="25"} 1
order_latency_ms_bucket{le="+Inf"} 1
order_latency_ms_sum 17.5
order_latency_ms_count 1

---

🧪 Testing

Run the zero-dependency test runner:

php tests/run_tests.php

---

👤 Author & Maintainer

Eng. MHD. Shadi AL-Hasan

• Role: Executive CTO & Enterprise Solutions Architect
• Email: mhd.shadi.alhasan@gmail.com
• Phone / WhatsApp: +963934005922
• Location: Damascus, Syria
• GitHub: shadialhasan

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.
Copyright (c) 2026 MHD. Shadi AL-Hasan. All rights reserved.