TelemetryFlow PHP SDK

Enterprise-grade PHP SDK for TelemetryFlow — unified metrics, logs, and traces collection following OpenTelemetry standards. Ships as a monorepo with a framework-agnostic core, a first-class Laravel integration, and a Symfony Console code generator.

---

Packages

This repository is a monorepo managed with plain Composer path repositories.

Package	Description	Install
telemetryflow/php-native	Framework-agnostic core SDK. DDD + CQRS architecture, OTLP exporters (gRPC/HTTP), PSR-15 + Guzzle auto-instrumentation. Works with any PHP 8.2+ project.	composer require telemetryflow/php-native
telemetryflow/laravel	Laravel 10/11 integration. Service provider, TelemetryFlow facade, config publish, HTTP middleware, Monolog handler, health route.	composer require telemetryflow/laravel
telemetryflow/generator	Symfony Console CLI (telemetryflow-gen) to scaffold SDK integration, example apps, and config files.	composer require --dev telemetryflow/generator

The Laravel and generator packages depend on telemetryflow/php-native. Installing either pulls in the core automatically.

Features

• 100% OTLP Compliant — full OpenTelemetry Protocol implementation via open-telemetry/exporter-otlp
• DDD Architecture — Domain-Driven Design with clear bounded contexts mirroring the Go SDK
• CQRS Pattern — separate command and query responsibilities with command/query buses
• Two delivery models — native PHP (framework-agnostic) and a dedicated Laravel package
• Auto-instrumentation — PSR-15 HTTP middleware, Guzzle client middleware, Laravel HTTP/DB hooks
• TFO v2 API support — aligned with tfoexporter, tfoauthextension, tfoidentityextension
• Collector identity — name, hostname, datacenter, tags for resource enrichment
• Exemplars support — metrics-to-traces correlation enabled by default
• Easy integration — fluent builder pattern and environment-based configuration
• Code generator — telemetryflow-gen CLI for quick project setup
• Type safe — strict types, readonly properties, backed enums throughout
• Comprehensive testing — unit, integration, and mutation testing

Quick Start

PHP Native

composer require telemetryflow/php-native

<?php

declare(strict_types=1);

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

use TelemetryFlow\Core\TelemetryFlow;

// Create client from environment variables
$client = TelemetryFlow::newFromEnv();
$client->initialize();

// Send a metric
$client->incrementCounter('api.requests', 1, [
    'method' => 'GET',
    'status' => 200,
]);

// Send a log
$client->logInfo('User logged in', ['user_id' => '12345']);

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

// Graceful shutdown
$client->shutdown();

Laravel

composer require telemetryflow/laravel
php artisan vendor:publish --tag=telemetryflow-config

The TelemetryFlowServiceProvider is auto-discovered. Then use the facade:

use TelemetryFlow\Laravel\Facades\TelemetryFlow;

TelemetryFlow::incrementCounter('orders.created', 1, ['status' => 'paid']);
TelemetryFlow::logInfo('Order processed', ['order_id' => $order->id]);

Environment variables (in .env):

TELEMETRYFLOW_API_KEY_ID=tfk_your_key_id
TELEMETRYFLOW_API_KEY_SECRET=tfs_your_key_secret
TELEMETRYFLOW_ENDPOINT=api.telemetryflow.id:4317
TELEMETRYFLOW_SERVICE_NAME=my-laravel-app

Architecture

packages/php-native/src/
├── Domain/           # Domain layer (value objects, aggregate root, enums)
│   ├── Credentials.php
│   ├── TelemetryConfig.php
│   ├── Protocol.php
│   └── SignalType.php
├── Application/      # Application layer (CQRS commands, queries, buses)
│   ├── Commands/
│   └── Queries/
├── Infrastructure/   # Infrastructure layer (OTLP exporters, handlers)
│   ├── OtlpExporterFactory.php
│   ├── TelemetryCommandHandler.php
│   ├── AuthHeaders.php
│   └── ResourceBuilder.php
├── Instrumentation/  # Auto-instrumentation (PSR-15, Guzzle)
│   └── Http/
├── Client.php        # Public API (interface layer)
├── Builder.php       # Fluent builder
└── TelemetryFlow.php # Static factory facade

See docs/ARCHITECTURE.md for the full design.

Docker

Using Docker

# Initialize SDK integration
docker run --rm -v $(pwd):/workspace telemetryflow/telemetryflow-php-sdk:latest \
    init --project myapp --service my-service

# Generate an example application
docker run --rm -v $(pwd):/workspace telemetryflow/telemetryflow-php-sdk:latest \
    example basic --output /workspace/example

Docker Compose

Development environment with a full observability stack:

# Start the OTLP collector only (dev profile)
make docker-up

# Start the collector + Prometheus (full profile)
make docker-full

# Start the dev container + collector
make docker-dev

# Run the SDK examples against the collector
docker-compose --profile example up

# Stop everything
make docker-down

Profile	Services
dev	sdk-dev, otel-collector
full	otel-collector, prometheus
example	example-basic, example-http-server, otel-collector

OTLP endpoints exposed on the host:

• gRPC: localhost:4317
• HTTP: localhost:4318 (/v1/traces, /v1/metrics, /v1/logs)
• Collector health: http://localhost:13133
• Prometheus metrics: http://localhost:8889 / dashboard on :9090

Standalone Phar

Build a dependency-free generator Phar:

make phar
# produces build/telemetryflow-gen.phar
php build/telemetryflow-gen.phar version

Development

This is a monorepo. Clone and install all dependencies at once:

git clone https://github.com/telemetryflow/telemetryflow-php-sdk.git
cd telemetryflow-php-sdk
make install
make test        # run all package suites
make stan        # static analysis
make cs-fix      # format code

CI/CD

Workflow	Trigger	Purpose
ci.yml	push/PR to main	Tests + coverage (PHP 8.2/8.3/8.4) + PHPStan + CS check
docker.yml	tag v*.*.*, push to main	Multi-arch Docker build & push, SBOM, Trivy scan
release.yml	tag v*.*.*	Phar build, SHA256 checksums, GitHub Release

Compatibility

• PHP 8.2+
• Laravel 10 / 11 (optional)
• OpenTelemetry PHP SDK 1.0+
• TFO-Collector v1.2.1 (OCB-native)

Documentation

• Quickstart Guide
• Architecture Guide
• API Reference
• Changelog
• TelemetryFlow Platform

License

Apache License 2.0 — see LICENSE.

Support

• Docs: https://docs.telemetryflow.id
• Issues: GitHub Issues

---

Built with ❤️ by Telemetri Data Indonesia collaboration with Kiro