php-native

TelemetryFlow PHP Native SDK

Framework-agnostic TelemetryFlow SDK core for PHP 8.2+. Provides OTLP metrics, logs, and traces with a DDD + CQRS architecture, fluent builder, and PSR-15 / Guzzle auto-instrumentation.

Install

composer require telemetryflow/php-native

The gRPC transport needs the PHP grpc extension. HTTP transport works everywhere.

Quick Start

<?php

declare(strict_types=1);

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

use TelemetryFlow\Core\TelemetryFlow;

$client = TelemetryFlow::newFromEnv();
$client->initialize();

$client->incrementCounter('api.requests', 1, ['method' => 'GET', 'status' => 200]);
$client->logInfo('Application started', ['version' => '1.0.0']);

$spanId = $client->startSpan('process-order', 'internal', ['order_id' => '67890']);
// ... do work ...
$client->endSpan($spanId);

$client->shutdown();

Builder

use TelemetryFlow\Core\Builder;
use TelemetryFlow\Core\TelemetryFlow;

$client = Builder::create()
    ->withApiKey('tfk_...', 'tfs_...')
    ->withEndpoint('api.telemetryflow.id:4317')
    ->withService('my-service', '1.0.0')
    ->withHttp()
    ->withSignals(true, true, true)
    ->withCustomAttribute('team', 'backend')
    ->build();

$client->initialize();

Environment Variables

Variable	Description	Default
TELEMETRYFLOW_API_KEY_ID	API key id (tfk_)	required
TELEMETRYFLOW_API_KEY_SECRET	API key secret (tfs_)	required
TELEMETRYFLOW_ENDPOINT	OTLP endpoint host:port	api.telemetryflow.id:4317
TELEMETRYFLOW_SERVICE_NAME	Service name	unknown-service
TELEMETRYFLOW_SERVICE_VERSION	Service version	1.0.0
TELEMETRYFLOW_SERVICE_NAMESPACE	Service namespace	telemetryflow
TELEMETRYFLOW_ENVIRONMENT	Deployment env	production
TELEMETRYFLOW_PROTOCOL	grpc or http	grpc
TELEMETRYFLOW_INSECURE	Disable TLS	false
TELEMETRYFLOW_COLLECTOR_ID	Collector identifier	empty
TELEMETRYFLOW_COLLECTOR_NAME	Collector name	empty
TELEMETRYFLOW_DATACENTER	Datacenter id	default
TELEMETRYFLOW_USE_V2_API	Enable v2 endpoints	true
TELEMETRYFLOW_V2_ONLY	Reject v1 endpoints	false
TELEMETRYFLOW_ENABLE_EXEMPLARS	Metrics-traces exemplars	true

Auto-Instrumentation

PSR-15 HTTP Server Middleware

use TelemetryFlow\Core\Instrumentation\Http\HttpMiddleware;
use TelemetryFlow\Core\Instrumentation\InstrumentationConfig;

$config = new InstrumentationConfig(serviceName: 'my-app');
$stack->push(new HttpMiddleware($config));

Guzzle Client Middleware

use GuzzleHttp\HandlerStack;
use GuzzleHttp\Client;
use TelemetryFlow\Core\Instrumentation\Http\GuzzleMiddleware;

$stack = HandlerStack::create();
$stack->push(GuzzleMiddleware::factory($config));
$client = new Client(['handler' => $stack]);

Architecture

See ../../docs/ARCHITECTURE.md.