DEV Community

Ronal Daniel LUPACA MAMANI
Ronal Daniel LUPACA MAMANI

Posted on

# 🔍 Observability with Prometheus in PHP

Observability is a key property of modern systems that allows understanding what is happening inside an application by collecting signals such as metrics, logs, and traces. Unlike simple monitoring (which only detects symptoms), observability lets us diagnose root causes.

In distributed environments, having observability tools is essential for detecting bottlenecks, performance drops, hidden errors, and unexpected behaviors. One of the most popular and accessible solutions is Prometheus, an open-source metrics collector originally created by SoundCloud, which allows querying data in real-time using its own query language: PromQL.

In this article, I will show you how to implement a complete observability flow in PHP, using only Prometheus.

🎯 What will you learn?

  • What observability is and why it matters
  • How to generate custom metrics using PHP
  • How to configure Prometheus to collect them
  • How to visualize metrics directly in Prometheus dashboard

🧰 Tools used

Tool Purpose
PHP (CLI) Metric simulation and exposure
Prometheus Metric collection and querying
Windows Local development environment

🧪 Step 1: Generate metrics from PHP

We create two PHP files: one to simulate metrics and another to expose them for Prometheus.

📄 generator.php 

<?php
$counter = 0;

while (true) {
    $start = microtime(true);
    sleep(rand(1, 3));

    $counter++;
    $duration = microtime(true) - $start;

    file_put_contents("metrics.txt", 
        "# HELP uploads_total Total uploads
" .
        "# TYPE uploads_total counter
" .
        "uploads_total {$counter}
" .
        "# HELP upload_processing_seconds Processing time
" .
        "# TYPE upload_processing_seconds gauge
" .
        "upload_processing_seconds {$duration}
"
    );

    sleep(1);
}
Enter fullscreen mode Exit fullscreen mode

📄 metrics.php 

<?php
header('Content-Type: text/plain');
readfile("metrics.txt");
Enter fullscreen mode Exit fullscreen mode

▶️ Step 2: Run the scripts

  1. Open a terminal and run the generator: 
php generator.php
Enter fullscreen mode Exit fullscreen mode
  1. In another terminal, start the PHP server: 
php -S localhost:8000 metrics.php
Enter fullscreen mode Exit fullscreen mode
  1. Verify everything works by visiting: 👉 http://localhost:8000

⚙️ Step 3: Configure Prometheus

  1. Download Prometheus from: https://prometheus.io/download
  2. Extract the ZIP and create prometheus.yml: 
global:
  scrape_interval: 5s

scrape_configs:
  - job_name: 'php_metrics'
    static_configs:
      - targets: ['localhost:8000']

  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']
Enter fullscreen mode Exit fullscreen mode

▶️ Step 4: Run Prometheus

In PowerShell or CMD, run:

.\prometheus.exe --config.file=prometheus.yml
Enter fullscreen mode Exit fullscreen mode

Open: 👉 http://localhost:9090

📈 Step 5: Query metrics in Prometheus

  1. In the dashboard, go to “Status → Targets” and check if it's UP
  2. In the “Graph” tab, run: 
uploads_total
Enter fullscreen mode Exit fullscreen mode

then:

upload_processing_seconds
Enter fullscreen mode Exit fullscreen mode

Press Execute to see the PHP-generated metrics.

Image description

📊 1. upload_processing_seconds 

upload_processing_seconds{instance="localhost:8000", job="php_metrics"} 3.0004351139069
Enter fullscreen mode Exit fullscreen mode

Description:
This metric shows the time it took to process a file upload in PHP. In this example, it took about 3 seconds.

Labels:

  • instance="localhost:8000": Source endpoint (metrics.php on port 8000)
  • job="php_metrics": Job name defined in prometheus.yml

📦 2. uploads_total 

uploads_total{instance="localhost:8000", job="php_metrics"} 1
Enter fullscreen mode Exit fullscreen mode

Description:
This metric is a counter of how many times the upload process ran. In this case, it only ran once.

Labels:

  • instance="localhost:8000": Metric source endpoint.
  • job="php_metrics": Registered job for that metric.

📦 GitHub Repository

https://github.com/daniellupaca/php_Prometheus-/tree/main

🧠 Conclusion

Prometheus allows you to instrument any modern app without much complexity. By integrating real-time metrics from PHP, you get an accessible solution for academic projects, performance testing, or production systems without needing external tools like Grafana.

This approach can easily be extended to Node.js, Python, Java, etc.

❤️ Was this useful?

If you liked this article, share it or comment your experience using Prometheus and PHP.

Top comments (0)