Telemetry
Prism emits Laravel events for the generation lifecycle, including steps, tool calls, completion and failure. Telemetry is disabled by default.
Use it to trace and measure generations — latency, token usage, cost, finish reasons, tool calls — wired into your own logging and metrics, or exported to an OpenTelemetry backend such as Arize Phoenix with the companion bridge.
Stream failures#
Event-signalled stream failures emit Prism\Prism\Events\Telemetry\GenerationErrored. Its status is error; its optional failureUsage contains provider-reported, provisional usage for the failed attempt. It carries no prompt, generated content, provider diagnostics or raw body. A foreign read exception with reported usage also produces this event after its final stream error event, then reaches the existing GenerationFailed path. Without reported usage, no synthetic error event is added. Existing provider HTTP exception mapping is preserved, and mapped SDK exceptions retain the snapshot. SDK exceptions thrown by a provider handler supply their optional failure usage on GenerationFailed directly.
Failed streams no longer emit GenerationCompleted, including streams that end normally at the iterator level with an Error finish reason. Consumers counting successful completions must use this distinction. StepCompleted includes the step's actual finish reason; do not treat a failed step as successful simply because it has usage. A recoverable failed attempt followed by a successful terminal can still complete the generation.
Record a failed attempt once across stream and telemetry channels. No usage is invented when a provider reported none. These numeric fields are available with content capture disabled, and do not change the default privacy settings.
Enabling telemetry#
Telemetry is disabled by default. Turn it on with an environment variable:
PRISM_TELEMETRY_ENABLED=true
The full configuration block in config/prism.php:
'telemetry' => [ // Master switch. When false, telemetry is a complete no-op: no contexts // are minted and no events are dispatched. 'enabled' => env('PRISM_TELEMETRY_ENABLED', false), // Include prompts, completions, and tool arguments in payloads. Off by // default — this data can contain PII. Only enable where the sink is trusted. 'capture_content' => env('PRISM_TELEMETRY_CAPTURE_CONTENT', false), // Bounds so telemetry can never turn a streaming response into unbounded memory. 'content_max_length' => (int) env('PRISM_TELEMETRY_CONTENT_MAX_LENGTH', 65_536), 'content_max_items' => (int) env('PRISM_TELEMETRY_CONTENT_MAX_ITEMS', 256), ],
The events#
All telemetry events live in the Prism\Prism\Events\Telemetry namespace and
are dispatched through Laravel's event system, so you consume them with ordinary
listeners.
| Event | Dispatched when | Key payload (beyond $context) |
|---|---|---|
GenerationStarted |
a generation begins | $request, $tools |
StepCompleted |
each step finishes | $finishReason, $usage, $rateLimits, $step |
ToolInvoked |
a tool call resolves | $toolName, $toolCallId, $durationMs, $failed, $failure, $toolCall, $toolResult |
GenerationCompleted |
the generation finishes | $durationMs, $finishReason, $usage, $rateLimits, $response |
GenerationFailed |
the generation throws | $durationMs, $exception |
Every event carries a TelemetryContext (see below)
that ties the whole lifecycle together.
Listening#
Subscribe like any Laravel event:
use Illuminate\Support\Facades\Event; use Prism\Prism\Events\Telemetry\GenerationCompleted; Event::listen(function (GenerationCompleted $event): void { logger()->info('prism.generation', [ 'trace_id' => $event->context->traceId, 'provider' => $event->context->provider, 'model' => $event->context->model, 'duration_ms' => $event->durationMs, 'finish_reason' => $event->finishReason?->value, 'prompt_tokens' => $event->usage?->promptTokens, 'completion_tokens' => $event->usage?->completionTokens, 'rate_limits' => array_map(fn ($limit) => $limit->toArray(), $event->rateLimits), ]); });
For anything more involved, register a listener class in your application's event service provider.
Tool failures#
ToolInvoked.failed and ToolInvoked.failure are always available, including
when content capture is off. A successful call has false and null. A native
tool failure has true and a short kind: tool_error for a returned ToolError,
or exception:<ShortClass> for an exception. Exception messages stay out of the
kind; an invalid or oversized class name becomes exception:unknown.
For tools that return a failure inside their result, register a classifier at application boot:
use Prism\Prism\Facades\Prism; use Prism\Prism\ValueObjects\ToolCall; Prism::classifyToolResultsUsing(function (ToolCall $call, mixed $result): ?string { if ($call->name !== 'research' || ! is_string($result)) { return null; } $data = json_decode($result, true); return is_array($data) && ($data['success'] ?? null) === false ? 'research.failed' : null; });
The classifier receives the post-tool result value that the model receives,
with the same type on sequential and concurrent paths. It runs in the
registering process once per completed call; the host Closure is never sent to
concurrent workers. Native failures bypass it. The registration is process-wide;
set it at boot, and pass null to clear it.
Return null for success or a fixed failure kind of 1–64 characters from
A-Z, a-z, 0-9, _, ., : and -. Other returned values become
classified_failure. If the classifier throws, the kind is classifier_error.
Return coarse labels rather than customer data or result bodies.
A classified failure sets ToolInvoked.failed to true and the stream
ToolResultEvent.success flag to false. It preserves the model-facing result,
artifacts, conversation, provider request bytes and step count. Classifier
exceptions do not interrupt the tool call. With content capture off,
ToolInvoked.toolCall and ToolInvoked.toolResult remain null.
The telemetry context#
Prism\Prism\Telemetry\TelemetryContext is the correlation object shared by
every event of a single generation:
| Property | Description |
|---|---|
traceId |
stable id for the whole generation — join every event on this |
operation |
a TelemetryOperation describing the kind of call |
provider / model |
the provider key and model id |
stepIndex / toolIndex |
ordinals nesting steps and tool calls under the generation |
userId / sessionId |
your optional metadata (see below) |
startedAt |
monotonic start; elapsedMs() returns elapsed time |
Attaching user & session metadata#
Correlate telemetry with your own users and conversations using the
withTelemetryMetadata() builder method — the values flow onto every event's
context:
use Prism\Prism\Facades\Prism; use Prism\Prism\Enums\Provider; $response = Prism::text() ->using(Provider::Anthropic, 'claude-sonnet-5-5') ->withTelemetryMetadata(userId: (string) $user->id, sessionId: $conversation->id) ->withPrompt('Summarise this thread') ->asText();
Every telemetry event for that call now carries $context->userId and
$context->sessionId, so you can group traces per user or per conversation in
your backend.
Capturing prompt & completion content#
By default telemetry records structure and metrics only — timings, token usage, finish reasons, model, and the provider's rate-limit buckets — never the prompt or completion text, because that content can contain PII.
capture_content controls prompt and response content. Usage and rate-limit
metadata remain available when provided by the API.
When telemetry is enabled, GenerationStarted::$tools also carries each
advertised tool's name and a SHA-256 digest of its declaration (name, description
and parameters), even when capture_content is off. Full descriptions and
parameter schemas remain behind the content gate. These fingerprints help
diagnose cache misses caused by changes to the tool list in a provider's prompt
prefix.
Use stable, application-defined tool names. If you derive a tool name from user data, such as a user-owned document's title, that name is exposed to telemetry listeners on every generation that advertises the tool, even with content capture disabled. The digest is a fingerprint, not a copy of the declaration; it still allows comparison with known or guessed declarations.
Opt in with capture_content, and only where the telemetry sink is trusted:
PRISM_TELEMETRY_CAPTURE_CONTENT=true
Configure capture limits to bound the amount of retained content:
content_max_length(default65_536) caps per-item text length.content_max_items(default256) caps how many message items are captured.
Attachments#
Captured messages can hold images, documents, audio or video. Their bytes are not
captured by default. A media part keeps its kind, mime type, file id and filename,
and its base64 is replaced by omitted_bytes, the size of what was left out:
{"kind": "image", "url": null, "base64": null, "mime_type": "image/png", "file_id": null, "filename": null, "omitted_bytes": 48213}
To capture the bytes too, where your telemetry sink is trusted with your users' files:
PRISM_TELEMETRY_CAPTURE_MEDIA=true
Only media Prism serialises is recognised. Bytes a user pastes into a prompt as text
are text, and capture_content alone decides whether they are captured.
Exporting to OpenTelemetry / Arize Phoenix#
Because the events above are provider-neutral, any exporter can consume them. The
companion package
particle-academy/prism-opentelemetry
subscribes to them and emits standard OpenTelemetry spans — a root span per
generation, child spans per step and per tool call, with token, cost, model, and
finish-reason attributes, in both the GenAI and OpenInference conventions — over
OTLP to Arize Phoenix, Jaeger, Tempo, or any OTLP
backend.
composer require particle-academy/prism-opentelemetry
With telemetry enabled and the bridge installed, generations are exported as nested traces.