PHPackages                             mumzworld/laravel-opentelemetry - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. mumzworld/laravel-opentelemetry

ActiveLibrary[Logging & Monitoring](/categories/logging)

mumzworld/laravel-opentelemetry
===============================

OpenTelemetry integration package for Laravel applications with complete observability stack

v1.2.3(2mo ago)0240↓50%MITPHPPHP ^8.2

Since Sep 9Pushed 2mo agoCompare

[ Source](https://github.com/mumzworld-tech/laravel-opentelemetry-pkg)[ Packagist](https://packagist.org/packages/mumzworld/laravel-opentelemetry)[ RSS](/packages/mumzworld-laravel-opentelemetry/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (14)Versions (7)Used By (0)

Laravel OpenTelemetry Package
=============================

[](#laravel-opentelemetry-package)

A comprehensive OpenTelemetry integration package for Laravel applications that provides complete observability through distributed tracing, metrics collection, and visualization. This package enables you to monitor your application's performance, track requests across microservices, and identify bottlenecks in your Laravel application.

**Learn more about OpenTelemetry:**

- [OpenTelemetry Official Documentation](https://opentelemetry.io/docs/)
- [OpenTelemetry PHP Documentation](https://opentelemetry.io/docs/languages/php/)

🚀 Features
----------

[](#-features)

- **Easy Integration**: Single composer require + artisan publish
- **Environment-Driven**: All settings configurable via .env variables
- **Complete Observability Stack**: Includes OpenTelemetry Collector, Tempo, and Grafana
- **Custom Tracing**: Simple TracerService for business logic tracing
- **Docker Ready**: Complete observability stack with Docker Compose
- **Laravel Integration**: Automatic service provider registration
- **Production Ready**: Configurable sampling, batching, and resource limits
- **Automatic Instrumentation**: PHP extension support for zero-code tracing
- **Error Tracking**: Automatic exception recording in traces
- **Test Routes**: Built-in test endpoints to verify integration

📋 Prerequisites
---------------

[](#-prerequisites)

- **PHP 8.4+** (Laravel 11 with latest Symfony dependencies requires PHP 8.4)
- **Laravel 11.0+**
- **Docker & Docker Compose** (for observability stack)
- **OpenTelemetry PHP Extension** (required for automatic instrumentation)
- **Composer** (for package installation)

🛠️ Installation
---------------

[](#️-installation)

> ⚠️ **CRITICAL**: The OpenTelemetry PHP extension must be installed BEFORE running `composer require`. The package installation will fail without it.

### Docker Environment (Recommended)

[](#docker-environment-recommended)

> **For Fresh Laravel Projects**: If you don't have Docker setup yet, create these files first:

**Create `Dockerfile`:**

```
FROM php:8.4-fpm

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    curl \
    libpng-dev \
    libonig-dev \
    libxml2-dev \
    zip \
    unzip

# Install PHP extensions
RUN docker-php-ext-install pdo_mysql mbstring exif pcntl bcmath gd

# Install OpenTelemetry extension
RUN pecl install opentelemetry && docker-php-ext-enable opentelemetry

# Install Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Set working directory
WORKDIR /var/www

# Copy application files
COPY . .

# Install dependencies
RUN composer install

# Set permissions
RUN chown -R www-data:www-data /var/www
```

**Create `docker-compose.yml`:**

```
services:
  app:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - .:/var/www
    command: php artisan serve --host=0.0.0.0 --port=8000
    networks:
      - app-network

networks:
  app-network:
    driver: bridge
```

#### Step 1: Add Extension to Dockerfile (If Docker Already Exists)

[](#step-1-add-extension-to-dockerfile-if-docker-already-exists)

Add the OpenTelemetry extension to your Dockerfile:

```
# Install OpenTelemetry extension
RUN pecl install opentelemetry && docker-php-ext-enable opentelemetry

# Or copy the provided PHP configuration
COPY docker/php/20-otel.ini /usr/local/etc/php/conf.d/
```

#### Step 2: Rebuild Docker Container

[](#step-2-rebuild-docker-container)

```
docker-compose build app
```

#### Step 3: Install the Package

[](#step-3-install-the-package)

```
# Start the container
docker-compose up -d app

# Install the package inside the container
docker-compose exec app composer require mumzworld/laravel-opentelemetry
```

*Note: The service provider is automatically registered via Laravel's package auto-discovery.*

### Non-Docker Environment

[](#non-docker-environment)

#### Step 1: Install OpenTelemetry PHP Extension

[](#step-1-install-opentelemetry-php-extension)

**Using PECL (Most Common):**

```
# Install the extension
pecl install opentelemetry

# Add to your php.ini
echo "extension=opentelemetry" >> /path/to/php.ini

# Restart your web server
sudo systemctl restart apache2  # or nginx/php-fpm
```

**Verify Installation:**

```
php -m | grep opentelemetry
# Should output: opentelemetry
```

#### Step 2: Install the Package

[](#step-2-install-the-package)

```
composer require mumzworld/laravel-opentelemetry
```

*Note: The service provider is automatically registered via Laravel's package auto-discovery.*

#### Step 4: Publish Configuration Files

[](#step-4-publish-configuration-files)

> **Note**: The publish command creates a `.env.opentelemetry.example` file as a reference. You can safely delete this file after copying the variables to your `.env` file.

**For Docker Environment:**

```
# Publish all OpenTelemetry files
docker-compose exec app php artisan vendor:publish --provider="Mumzworld\LaravelOpenTelemetry\LaravelOpenTelemetryServiceProvider"

# Or publish specific components
docker-compose exec app php artisan vendor:publish --tag=opentelemetry-config
docker-compose exec app php artisan vendor:publish --tag=opentelemetry-docker
docker-compose exec app php artisan vendor:publish --tag=opentelemetry-bootstrap
docker-compose exec app php artisan vendor:publish --tag=opentelemetry-env
docker-compose exec app php artisan vendor:publish --tag=opentelemetry-test-routes
```

**For Non-Docker Environment:**

```
# Publish all OpenTelemetry files
php artisan vendor:publish --provider="Mumzworld\LaravelOpenTelemetry\LaravelOpenTelemetryServiceProvider"

# Or publish specific components
php artisan vendor:publish --tag=opentelemetry-config
php artisan vendor:publish --tag=opentelemetry-docker
php artisan vendor:publish --tag=opentelemetry-bootstrap
php artisan vendor:publish --tag=opentelemetry-env
php artisan vendor:publish --tag=opentelemetry-test-routes
```

#### Step 5: Configure Environment Variables

[](#step-5-configure-environment-variables)

Add these variables to your `.env` file:

```
# Core OpenTelemetry Settings
OTEL_ENABLED=true
OTEL_SERVICE_NAME=${APP_NAME}
OTEL_SERVICE_VERSION=1.0.0
OTEL_ENVIRONMENT=${APP_ENV}

# Trace Export Settings
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_PROPAGATORS=baggage,tracecontext

# Sampling Configuration (adjust for production)
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=1.0

# PHP Extension Settings
OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_INSTRUMENTATION_ENABLED=true
OTEL_ATTR_HOOKS_ENABLED=true

# Debug Settings (disable in production)
OTEL_DEBUG=false
```

#### Step 6: Setup Docker Observability Stack

[](#step-6-setup-docker-observability-stack)

Add the OpenTelemetry services to your `docker-compose.yml`:

```
# Include the OpenTelemetry stack
include:
  - docker/opentelemetry/docker-compose.opentelemetry.yml

services:
  app:
    environment:
      # OpenTelemetry configuration for your Laravel app
      OTEL_SERVICE_NAME: ${OTEL_SERVICE_NAME:-my-laravel-app}
      OTEL_TRACES_EXPORTER: ${OTEL_TRACES_EXPORTER:-otlp}
      OTEL_EXPORTER_OTLP_ENDPOINT: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://otel-collector:4318}
      OTEL_EXPORTER_OTLP_PROTOCOL: ${OTEL_EXPORTER_OTLP_PROTOCOL:-http/protobuf}
      OTEL_PROPAGATORS: ${OTEL_PROPAGATORS:-baggage,tracecontext}
      OTEL_PHP_AUTOLOAD_ENABLED: ${OTEL_PHP_AUTOLOAD_ENABLED:-true}
    networks:
      - app-network
    depends_on:
      - otel-collector

networks:
  app-network:
    driver: bridge
```

#### Step 7: Start the Observability Stack

[](#step-7-start-the-observability-stack)

```
# Create the external network (required for Docker services)
docker network create app-network

# Start the observability stack
docker-compose up -d otel-collector tempo grafana

# Start your application
docker-compose up -d app
```

#### Step 8: Verify Installation

[](#step-8-verify-installation)

```
# Check if services are running
docker-compose ps otel-collector tempo grafana

# Check Grafana is accessible
curl http://localhost:3000

# Test the integration (if test routes are published and enabled)
curl http://localhost:8000/api/opentelemetry/test
curl http://localhost:8000/api/opentelemetry/config
```

**If test routes return 404:**

1. Ensure you've added the test route inclusion to `routes/api.php`
2. Clear route cache: `docker-compose exec app php artisan route:clear`
3. Restart the app container: `docker-compose restart app`

🔍 Troubleshooting
-----------------

[](#-troubleshooting)

### Common Issues

[](#common-issues)

**1. No traces appearing in Grafana**

Check if services are running:

```
docker-compose ps otel-collector tempo grafana
```

Check collector logs:

```
docker-compose logs otel-collector
```

**2. PHP Extension not loading**

Verify OpenTelemetry extension is installed:

```
php -m | grep opentelemetry
```

Check PHP configuration:

```
php --ini
php -i | grep opentelemetry
```

**3. Traces not being exported**

Check environment variables:

```
php artisan tinker
>>> config('opentelemetry.enabled')
>>> config('opentelemetry.service.name')
>>> config('opentelemetry.exporter.otlp.endpoint')
```

Test with debug mode:

```
# Add to .env
OTEL_DEBUG=true
APP_DEBUG=true

# Check logs
tail -f storage/logs/laravel.log
```

**4. High memory usage**

Adjust sampling rate:

```
OTEL_TRACES_SAMPLER_ARG=0.1  # Sample 10% of traces
```

🎯 Usage Examples
----------------

[](#-usage-examples)

### Basic Custom Tracing

[](#basic-custom-tracing)

```