README

Automatically track cURL API response times and publish metrics to AWS CloudWatch or Prometheus PushGateway.

Quick Start

Installation

composer require uengage/curl-tracker

PushGateway Backend Setup

<?php
require_once 'vendor/autoload.php';
use CurlTracker\CurlHook;

CurlHook::init([
    'backend' => 'pushgateway',
    'pushgateway' => [
        'url' => 'http://localhost:9091',
        'job_name' => 'my_application'
    ]
]);

CloudWatch Backend Setup

<?php
require_once 'vendor/autoload.php';
use CurlTracker\CurlHook;

CurlHook::init([
    'backend' => 'cloudwatch',
    'cloudwatch' => [
        'aws_region' => 'us-east-1',
        'namespace' => 'MyApp/APIMetrics'
    ]
]);

CodeIgniter 4 Setup

Add to app/Config/Events.php:

<?php
use CurlTracker\CurlHook;

Events::on('pre_system', function() {
    if (class_exists('CurlTracker\CurlHook')) {
        $tracker = CurlHook::init([
            'backend' => env('METRICS_BACKEND', 'pushgateway'),
            'sample_rate' => env('METRICS_SAMPLE_RATE', 100),
            'pushgateway' => [
                'url' => env('PUSHGATEWAY_URL', 'http://localhost:9091'),
                'job_name' => env('APP_NAME', 'codeigniter_app')
            ],
            'cloudwatch' => [
                'aws_region' => env('AWS_REGION', 'us-east-1'),
                'namespace' => env('CLOUDWATCH_NAMESPACE', 'MyApp/Metrics')
            ]
        ]);

        // Enable automatic cURL hooking
        $tracker->enable();
    }
});

Custom Metrics

Push custom business metrics alongside cURL tracking:

use CurlTracker\CurlHook;

// Initialize CurlHook first
$tracker = CurlHook::init([
    'backend' => 'pushgateway',
    'pushgateway' => ['url' => 'http://localhost:9091']
]);

// Example: Track CI database query performance
$start = microtime(true);
$result = $this->db->query("SELECT COUNT(*) FROM users WHERE active = 1");
$duration = (microtime(true) - $start) * 1000;

// Publish custom metric
$tracker->publishMetric('db_query_duration', $duration, [
    'query_type' => 'user_count',
    'database' => 'primary'
]);

Backend Configuration

PushGateway

'pushgateway' => [
    'url' => 'http://localhost:9091',
    'job_name' => 'my_app',
    'timeout' => 5,
    'auth' => [
        'username' => 'user',
        'password' => 'pass'
    ]
]

CloudWatch

'cloudwatch' => [
    'aws_region' => 'us-east-1',
    'namespace' => 'MyApp/Metrics',
    'aws' => [
        'credentials' => [...] // Optional
    ]
]

Sample Rate Control

CurlHook::init([
    'sample_rate' => 25, // Track only 25% of requests
    'backend' => 'pushgateway'
]);

Requirements

PHP 7.1+
ext-curl
ext-uopz (for automatic cURL hooking with CurlHook)
For CloudWatch: aws/aws-sdk-php ^3.0

Usage Modes

1. Automatic Hooking (Zero Code Changes)

Requires uopz extension. All native curl_* functions are automatically tracked:

use CurlTracker\CurlHook;

CurlHook::init($config)->enable();

// Your existing code works unchanged
$ch = curl_init('https://api.example.com');
curl_exec($ch);
curl_close($ch);

2. Manual Wrapper (Works Everywhere)

No extensions required. Use CurlWrapper::curl_* instead of native functions:

use CurlTracker\CurlWrapper;

CurlWrapper::init($config);

// Replace curl_* with CurlWrapper::curl_*
$ch = CurlWrapper::curl_init('https://api.example.com');
CurlWrapper::curl_exec($ch);
CurlWrapper::curl_close($ch);

Both modes support the same configuration interface.

License

MIT License. See LICENSE for details.

uengage / curl-tracker

Maintainers

Details