Set Up Agent Tracing

With Sentry Agent Tracing, you can monitor and debug your Laravel agents with full-stack context. You'll be able to track key insights like token usage, latency, tool usage, and error rates. Agent Tracing data is connected to your other Sentry data like logs, errors, and traces.

npx @sentry/ai install

Requirements

• sentry/sentry-laravel version 4.27.0 or later
• Laravel 12.x or later
• laravel/ai installed and configured
• Tracing enabled in your Sentry configuration

Configure

Laravel AI tracing is enabled by default when laravel/ai is installed and tracing is active.

SENTRY_TRACES_SAMPLE_RATE=1.0

SENTRY_TRACES_SAMPLE_RATE=1.0

You can opt out of all AI spans, or individual AI span types, in config/sentry.php:

'tracing' => [
    // Master switch for all AI spans (requires laravel/ai)
    'gen_ai' => env('SENTRY_TRACE_GEN_AI_ENABLED', true),

    // Individual span types
    'gen_ai_invoke_agent' => env('SENTRY_TRACE_GEN_AI_INVOKE_AGENT_ENABLED', true),
    'gen_ai_chat' => env('SENTRY_TRACE_GEN_AI_CHAT_ENABLED', true),
    'gen_ai_execute_tool' => env('SENTRY_TRACE_GEN_AI_EXECUTE_TOOL_ENABLED', true),
    'gen_ai_embeddings' => env('SENTRY_TRACE_GEN_AI_EMBEDDINGS_ENABLED', true),
],

'tracing' => [
    // Master switch for all AI spans (requires laravel/ai)
    'gen_ai' => env('SENTRY_TRACE_GEN_AI_ENABLED', true),

    // Individual span types
    'gen_ai_invoke_agent' => env('SENTRY_TRACE_GEN_AI_INVOKE_AGENT_ENABLED', true),
    'gen_ai_chat' => env('SENTRY_TRACE_GEN_AI_CHAT_ENABLED', true),
    'gen_ai_execute_tool' => env('SENTRY_TRACE_GEN_AI_EXECUTE_TOOL_ENABLED', true),
    'gen_ai_embeddings' => env('SENTRY_TRACE_GEN_AI_EMBEDDINGS_ENABLED', true),
],

Automatic Instrumentation

The Laravel SDK automatically instruments the Laravel AI package. Once enabled, Sentry captures:

• Agent invocations
• LLM requests
• Tool executions
• Embeddings
• Token usage
• Model and provider metadata

For package-specific details, see the Laravel AI integration.

Supported Providers and Custom URLs

Sentry creates gen_ai.chat spans by matching Laravel AI's outgoing HTTP requests to the provider URL. Built-in URL detection supports these Laravel AI provider drivers:

• Anthropic
• DeepSeek
• Gemini
• Groq
• Mistral
• Ollama
• OpenAI
• OpenRouter
• Voyage AI
• xAI

If you use a custom provider, or override a provider's endpoint, include a url value in config/ai.php so Sentry can identify those requests:

'providers' => [
    'my-llm' => [
        'driver' => 'openai-compatible',
        'url' => env('MY_LLM_URL'),
        'key' => env('MY_LLM_API_KEY'),
    ],
],

'providers' => [
    'my-llm' => [
        'driver' => 'openai-compatible',
        'url' => env('MY_LLM_URL'),
        'key' => env('MY_LLM_API_KEY'),
    ],
],

The provider key (my-llm in this example) is what Laravel AI passes to Sentry as the provider name. Sentry looks for ai.providers.my-llm.url and uses that value as the URL prefix for chat span detection.

Verify

Prompt one of your Laravel agents. For example, from a route:

use App\Ai\Agents\TimeAgent;

Route::get('/debug-ai', function () {
    $response = (new TimeAgent)->prompt('What time is it?');

    return $response->text;
});

use App\Ai\Agents\TimeAgent;

Route::get('/debug-ai', function () {
    $response = (new TimeAgent)->prompt('What time is it?');

    return $response->text;
});

Visiting this route triggers an agent invocation that Sentry captures. It may take a couple of moments for the data to appear in sentry.io.

Conversations

If your agent uses Laravel AI's remembering conversations feature, Sentry automatically tracks the conversationId returned by Laravel AI. The integration adds it to AI spans as gen_ai.conversation.id, which lets Sentry group multiple prompts into the same conversation in Explore > Agents.

For CLI commands and other non-HTTP entry points, create a transaction around each agent call so the AI spans are captured.