Trail Laravel Package

Getting Started

• Install the package and run its migrations, then publish its config if you need to tune payload capture or pricing. Make sure laravel/ai is at least 1.2.2 if you want failed image/audio/transcription calls recorded as Failed; older SDKs still record successful calls but leave failures to the caller or stale rules.
• Look first at the runs list and trace detail view. The runs list now has root-operation filters for the new image, audio and transcription operations, and the same filters apply to CSV export and the Boost trace listing.
• First use case: make a standalone image generation, text-to-speech, or transcription call through the Laravel AI SDK. It should appear as its own trace with span type image, audio or transcription. If the same call happens inside a tool, it appears as a child span under that tool’s trace instead.
• Before recording these new call types, deploy v0.4.0 to every process that reads Trail’s tables. Older versions cannot read the new span types.

Implementation Patterns

• Rely on the SDK events for instrumentation. You do not need to manually create spans for image, audio or transcription calls; the package records them from the SDK’s normal event flow.
• Use the “standalone call = trace, call inside a tool = span under the tool” model to organise multi-modal workflows. A top-level image or speech call is easy to find as its own trace; calls made inside agents/tools roll up under the parent tool trace.
• Filter by the new root operations when reviewing usage. Use the runs list for day-to-day debugging, CSV export for reporting, and the Boost trace listing when you want the same operation-based view in that context.
• Treat billing as token-based by default. Reported tokens count toward a run’s totals and are priced from the ordinary token rates of the model. Image, audio and transcription models ship with no default prices, so add a price for each model you use if you want costs rather than Unpriced.
• Capture text only when needed. Settings and counts are stored regardless — image size/quality/count, voice and characters spoken, language and seconds transcribed — but prompt/response texts are stored only when payload capture is enabled. Image and audio bytes are never stored.
• For failure monitoring, depend on SDK 1.2.2+ and the ImageFailed, AudioFailed and TranscriptionFailed events. They produce Failed spans with their own error and duration. On older SDK versions, a failed call is left as Incomplete or handled by the stale rule.
• If you have multiple consumers of Trail data, upgrade in the safe order: deploy v0.4.0 to all readers first, then start recording the new span types.

Gotchas and Tips

• The main upgrade hazard is mixed versions. An earlier Trail version cannot read the new image, audio or transcription span types, so deploy to every process that reads Trail’s tables before enabling recording of these calls.
• Expect Unpriced results for image/audio/transcription models until you add prices. There are no defaults for these models, and a call whose provider reports no tokens is Not captured rather than priced as zero.
• Failure visibility depends on SDK version. If you are below 1.2.2, failed calls may not appear as Failed; upgrade the AI SDK if failure spans and failure durations matter.
• Payload capture is privacy-sensitive by design. You can get texts when capture is enabled, but never image or audio bytes. Keep payload capture off unless you need the text content for debugging or evaluation.
• The new filters are root-operation filters. Nested calls inside tools are still spans under the tool, so use the parent trace to understand the full workflow rather than expecting every nested call to appear as a top-level run.
• When debugging missing data, check the SDK version, whether the relevant event fired, the package config for payload capture, model price configuration, and whether all Trail readers are on v0.4.0. CSV export is a quick way to audit operation coverage and pricing gaps.
• Extension point: add model-specific prices through the package’s pricing configuration. Keep those prices aligned with your provider contracts, especially if you route the same model through different providers or regions.