README

Smart, zero-config auto-tagging for Laravel Telescope.

Out of the box, Telescope's tag system is powerful but manual. This package automatically enriches every entry with meaningful, filterable tags — by HTTP status, exception type, response time, route group, and more — so you can instantly find what matters.

# Instead of scrolling through hundreds of requests...
# Just filter by tag:

validation-failed    → all 422 responses
error:5xx            → all server errors
slow:critical        → requests over 3s
carrier:dhl          → your custom domain tags
family:database      → all DB-related exceptions

Features

• HTTP Status Tags — http:422, error:4xx, validation-failed, rate-limited, server-error, and more
• Exception Tags — exception:QueryException, family:database, family:auth, family:validation
• Slow Request Tags — slow:warn and slow:critical with configurable thresholds
• Slow Query Tags — slow-query:warn and slow-query:critical on DB watcher entries
• Route Group Tags — group:api, group:webhook, group:admin via URI prefix matching
• Auth Context Tags — auth:authenticated vs auth:guest
• Custom Resolvers — plug in your own domain logic (e.g. carrier:dhl, tenant:acme)
• Fully configurable — enable/disable each resolver independently, tune thresholds, extend semantic maps

Requirements

Installation

composer require imezied/telescope-smart-tags --dev

That's it. The package auto-discovers and registers itself via Laravel's service provider. All resolvers are active by default with sensible defaults.

Publish the config (optional)

php artisan vendor:publish --tag=telescope-smart-tags-config

This creates config/telescope-smart-tags.php where you can tune every resolver.

Tags Reference

HTTP Status Tags

Applied to every Request entry.

Exception Tags

Applied to every Exception entry.

Slow Request Tags

Applied to Request entries exceeding configured thresholds.

Slow Query Tags

Applied to Query entries exceeding configured thresholds.

Auth Context Tags

Configuration

// config/telescope-smart-tags.php

return [

    'enabled' => env('TELESCOPE_SMART_TAGS_ENABLED', true),

    'resolvers' => [
        'http_status'   => true,
        'exceptions'    => true,
        'slow_requests' => true,
        'slow_queries'  => true,
        'route_groups'  => false, // opt-in
        'auth_context'  => false, // opt-in
    ],

    'http_status' => [
        'include_exact'    => true,
        'include_family'   => true,
        'include_semantic' => true,
        'custom_map' => [
            // 418 => 'im-a-teapot',
        ],
    ],

    'exceptions' => [
        'include_class'     => true,
        'include_family'    => true,
        'custom_family_map' => [
            // 'App\Exceptions\PaymentGatewayException' => 'family:payment',
        ],
    ],

    'slow_requests' => [
        'warn_ms'     => env('TELESCOPE_SLOW_REQUEST_WARN_MS', 1000),
        'critical_ms' => env('TELESCOPE_SLOW_REQUEST_CRITICAL_MS', 3000),
    ],

    'slow_queries' => [
        'warn_ms'     => env('TELESCOPE_SLOW_QUERY_WARN_MS', 500),
        'critical_ms' => env('TELESCOPE_SLOW_QUERY_CRITICAL_MS', 2000),
    ],

    'route_groups' => [
        'prefix_map' => [
            // 'api/v2'  => 'group:api-v2',
            // 'api'     => 'group:api',
            // 'webhook' => 'group:webhook',
            // 'admin'   => 'group:admin',
        ],
        'route_name_map' => [
            // 'api.'   => 'group:api',
            // 'admin.' => 'group:admin',
        ],
    ],

    'custom_resolvers' => [
        // App\Telescope\CarrierTagResolver::class,
        // App\Telescope\TenantTagResolver::class,
    ],
];

Environment Variables

TELESCOPE_SMART_TAGS_ENABLED=true

TELESCOPE_SLOW_REQUEST_WARN_MS=1000
TELESCOPE_SLOW_REQUEST_CRITICAL_MS=3000

TELESCOPE_SLOW_QUERY_WARN_MS=500
TELESCOPE_SLOW_QUERY_CRITICAL_MS=2000

Custom Resolvers

Build domain-specific resolvers by implementing TagResolverInterface:

namespace App\Telescope;

use Laravel\Telescope\EntryType;
use Laravel\Telescope\IncomingEntry;
use imezied\TelescopeSmartTags\TagResolvers\TagResolverInterface;

class CarrierTagResolver implements TagResolverInterface
{
    public function supports(IncomingEntry $entry): bool
    {
        return $entry->type === EntryType::REQUEST;
    }

    public function resolve(IncomingEntry $entry): array
    {
        $carrier = $entry->content['payload']['carrier'] ?? null;

        return $carrier ? ["carrier:{$carrier}"] : [];
    }
}

Register in your config:

'custom_resolvers' => [
    App\Telescope\CarrierTagResolver::class,
],

Your resolver is resolved through the Laravel service container, so constructor injection works:

class TenantTagResolver implements TagResolverInterface
{
    public function __construct(private TenantRepository $tenants) {}

    public function supports(IncomingEntry $entry): bool
    {
        return $entry->type === EntryType::REQUEST;
    }

    public function resolve(IncomingEntry $entry): array
    {
        $host   = $entry->content['headers']['host'][0] ?? null;
        $tenant = $host ? $this->tenants->findByDomain($host) : null;

        return $tenant ? ["tenant:{$tenant->slug}"] : [];
    }
}

Manipulating the Registry at Runtime

You can also interact with the TagRegistry directly in a service provider:

use imezied\TelescopeSmartTags\TagRegistry;

public function boot(): void
{
    $this->app->make(TagRegistry::class)
        ->add(new MyCustomResolver())
        ->add(new AnotherResolver());
}

How It Works

The package hooks into Telescope's Telescope::tag() callback during the boot phase:

Request/Exception/Query
        │
        ▼
  TagRegistry::resolve()
        │
        ├── HttpStatusTagResolver::resolve()   → ['http:422', 'error:4xx', 'validation-failed']
        ├── SlowRequestTagResolver::resolve()  → ['slow', 'slow:warn']
        ├── RouteGroupTagResolver::resolve()   → ['group:api']
        └── [your custom resolvers]            → ['carrier:dhl', 'tenant:acme']
        │
        ▼
  Merged + Deduplicated Tags
        │
        ▼
  Telescope Entry (searchable in dashboard)

Each resolver is independently toggled, zero overhead if disabled.

Testing Your Custom Resolver

use imezied\TelescopeSmartTags\Tests\TestCase;
use App\Telescope\CarrierTagResolver;

class CarrierTagResolverTest extends TestCase
{
    public function test_tags_carrier_from_payload(): void
    {
        $resolver = new CarrierTagResolver();

        $entry = $this->makeRequestEntry([
            'payload' => ['carrier' => 'dhl'],
        ]);

        $tags = $resolver->resolve($entry);

        $this->assertContains('carrier:dhl', $tags);
    }

    public function test_returns_empty_without_carrier(): void
    {
        $resolver = new CarrierTagResolver();
        $entry    = $this->makeRequestEntry(['payload' => []]);

        $this->assertEmpty($resolver->resolve($entry));
    }
}

Changelog

Please see CHANGELOG.md for recent changes.

Contributing

Pull requests are welcome. For major changes, please open an issue first.

1. Fork the repo
2. Create your branch (git checkout -b feature/my-resolver)
3. Add tests for your resolver
4. Run composer test — all tests must pass
5. Run composer lint — code style must pass
6. Submit your PR

License

MIT — see LICENSE for details.