README

A Laravel package that automatically captures and sends error telemetry data to your Ortic telemetry server. Install, configure two environment variables, and all unhandled exceptions are reported automatically.

Installation

1. Add the package via Composer

composer require ortic/telemetry-client

For local development with a path repository:

{
    "repositories": [
        {
            "type": "path",
            "url": "../telemetry-client"
        }
    ]
}

composer require ortic/telemetry-client:@dev

2. Publish the config (optional)

php artisan vendor:publish --tag=telemetry-config

This creates config/telemetry.php where you can customize ignored exceptions, timeout, etc.

3. Configure environment variables

Add these to your .env file (get these values from the Ortic telemetry project setup wizard):

TELEMETRY_DSN=your-dsn-token-here
TELEMETRY_ENDPOINT=https://your-ortic-instance.com/api/telemetry/ingest

That's it! All unhandled exceptions will now be reported automatically.

Optional Configuration

# Disable telemetry (e.g. for local dev)
TELEMETRY_ENABLED=false

# Override the environment name (defaults to APP_ENV)
TELEMETRY_ENVIRONMENT=staging

# Set a custom server name (defaults to hostname)
TELEMETRY_SERVER_NAME=web-01

# HTTP timeout in seconds (default: 5)
TELEMETRY_TIMEOUT=5

# Enable performance tracing (default: false)
TELEMETRY_TRACING_ENABLED=true

# Fraction of requests to trace: 1.0 = all, 0.1 = 10% (default: 1.0)
TELEMETRY_TRACING_SAMPLE_RATE=1.0

# Only send transactions longer than this (in ms, default: 0 = all)
TELEMETRY_TRACING_MIN_DURATION=0

Manual Reporting

You can also manually report exceptions or caught errors:

use Ortic\TelemetryClient\Facades\Telemetry;

try {
    // risky operation
} catch (\Exception $e) {
    Telemetry::reportException($e, [
        'order_id' => $order->id,
        'payment_method' => 'stripe',
    ]);
}

What Gets Sent

Each error report includes:

• Exception class and message
• File and line where the exception occurred
• Stack trace (up to 50 frames)
• Request URL, method, and user agent
• Server name and environment
• Authenticated user ID and email (if available)
• Custom extra data you attach manually

Ignored Exceptions

By default, these exception types are not reported (configurable in config/telemetry.php):

• NotFoundHttpException (404s)
• MethodNotAllowedHttpException (405s)
• ValidationException
• AuthenticationException

How It Works

1. The package registers a singleton TelemetryClient via Laravel's service container
2. During boot, it hooks into Laravel's exception handler using reportable()
3. When an unhandled exception occurs, the client builds a JSON payload and sends it via HTTP POST to your telemetry endpoint
4. The telemetry server groups errors by fingerprint (sha256(class + message + file + line)) and tracks frequency
5. All HTTP errors are caught silently — telemetry will never break your application

Requirements

• PHP 8.1+
• Laravel 10, 11, or 12
• Guzzle 7+