README

A comprehensive OpenTelemetry integration bundle for Symfony applications that provides automatic instrumentation, custom span creation, and distributed tracing capabilities.

Features

• Automatic Instrumentation - Built-in instrumentations for HTTP requests, database operations, and more
• Custom Instrumentations - Easy-to-use framework for creating custom instrumentations
• Middleware System - Extensible middleware system for span customization
• Exception Handling - Automatic span cleanup and error recording
• Docker Support - Complete development environment with Tempo and Grafana
• Performance Optimized - Support for both HTTP and gRPC transport protocols
• OpenTelemetry Compliant - Follows OpenTelemetry specifications and semantic conventions

Quick Overview

This bundle provides a configured OpenTelemetry integration for Symfony applications, offering:

• Automatic telemetry collection via kernel event listeners
• Custom instrumentation framework for business logic
• Built-in support for distributed tracing
• Complete testing and development environment

Bundle Overview

This bundle is a wrapper around the official OpenTelemetry PHP SDK bundle that simplifies integration and provides additional instrumentation capabilities for Symfony applications.

Key characteristics:

• Transport-agnostic - Uses standard OpenTelemetry SDK environment variables for transport configuration
• Framework-focused - Provides Symfony-specific instrumentation and middleware
• Extensible - Easy to add custom instrumentations and span processors

Built-in Features

• Request Execution Time Tracking - Automatic HTTP request timing
• Exception Handling - Automatic span cleanup and error recording
• Custom Instrumentations - Framework for creating custom telemetry collection

For detailed instrumentation guide, see Instrumentation Guide.

Environment Variables

The bundle supports all standard OpenTelemetry SDK environment variables. For complete configuration reference, see Configuration Guide.

Essential variables:

• OTEL_SERVICE_NAME - Your service name
• OTEL_TRACER_NAME - Tracer name
• OTEL_EXPORTER_OTLP_ENDPOINT - Collector endpoint
• OTEL_EXPORTER_OTLP_PROTOCOL - Transport protocol (grpc/http/protobuf)

Transport Configuration

Important: This bundle is transport-agnostic - it doesn't handle transport configuration directly. All transport settings are managed through standard OpenTelemetry SDK environment variables.

Recommended for production:

# Install gRPC support
composer require open-telemetry/transport-grpc
pecl install grpc # may take a time to compile - 30-40 minutes

# Configure gRPC endpoint
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc

Default HTTP endpoint: http://collector:4318

Transport protocols supported:

• grpc - High performance, recommended for production
• http/protobuf - Standard HTTP with protobuf encoding
• http/json - HTTP with JSON encoding (slower)

Note: Our bundle supports all transport protocols supported by the OpenTelemetry PHP SDK since we don't decorate the transport layer. For complete transport configuration options, see the official OpenTelemetry PHP Exporters documentation.

For detailed Docker setup and development environment configuration, see Docker Development Guide.

Documentation

• Installation Guide - Complete installation and setup instructions

• Configuration Reference - Bundle configuration and environment variables

• Instrumentation Guide - Built-in instrumentations and custom development

• Docker Development - Local development environment setup

• Testing Guide - Testing, trace visualization, and troubleshooting

• OpenTelemetry Basics - OpenTelemetry concepts and fundamentals

• Contributing Guide - How to contribute to the project

Quick Start

1. Install the bundle:

   composer require macpaw/symfony-otel-bundle

2. Enable in your application:

   // config/bundles.php
   return [
       Macpaw\SymfonyOtelBundle\SymfonyOtelBundle::class => ['all' => true],
   ];

3. Configure environment variables:

   OTEL_SERVICE_NAME=your-service-name
   OTEL_TRACER_NAME=your-tracer-name
   OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

4. Start testing:

   make up
   open http://localhost:8080

Usage

For detailed usage instructions, see Testing Guide.