particle-academy / prism-opentelemetry

v0.3.0 2026-09-14 08:10 UTC

Requires

• php: ^8.2
• ext-json: *
• ext-mbstring: *
• illuminate/contracts: ^12.0|^13.0
• illuminate/support: ^12.0|^13.0
• open-telemetry/api: ^1.0
• open-telemetry/context: ^1.0
• particle-academy/prism: >=0.116 <1.0

Requires (Dev)

• laravel/pint: ^1.14
• open-telemetry/sdk: ^1.0
• orchestra/testbench: ^10|^11
• pestphp/pest: ^3.0|^4.0
• phpstan/phpstan: ^2.1

MIT

• Particle Academy

• laravel
• prism
• Phoenix
• tracing
• observability
• opentelemetry
• otel
• otlp
• llm
• gen-ai

Published on Packagist.org on 2026-09-14 08:15 UTC

README

OpenTelemetry bridge for Prism. It subscribes to Prism's neutral telemetry events and turns them into GenAI-convention spans — a root span per generation, child spans per step and per tool call, with token, cost, model, finish-reason and provider rate-limit attributes — exported over OTLP to Arize Phoenix or any OTLP backend.

Status: under active development, and this release needs an unreleased Prism. The bridge reads the provider rate limits off GenerationCompleted::$rateLimits, which core gained after v0.115.1, so the constraint is >=0.116 <1.0 and composer install stays red until Prism v0.116.0 is tagged. The field exists because quota headroom is not content: before it, a successful generation exported no rate limits at all unless the application had turned prompt capture on.

Working on this package? Read AGENTS.md first — the boundary this package has to hold, the gates that must be green, and the traps that have already caught someone. @link AGENTS.md

How it fits together

Prism core (events)                 →  this bridge                →  OTLP backend
Events\Telemetry\GenerationStarted     builds root span              Arize Phoenix,
                 \StepCompleted        + child step spans            Jaeger, Tempo,
                 \ToolInvoked          + child tool spans            Grafana, …
                 \GenerationCompleted  ends the root span
                 \GenerationFailed     ends w/ error status

Prism core never depends on OpenTelemetry. This package owns the open-telemetry/* dependency and the GenAI attribute mapping, so semantic convention churn is a release of this package, not a change to Prism.

Installation

composer require particle-academy/prism-opentelemetry

# Provide an OpenTelemetry SDK + an OTLP exporter (transport of your choice):
composer require open-telemetry/sdk open-telemetry/exporter-otlp

Enable Prism telemetry (in the Prism config or environment):

PRISM_TELEMETRY_ENABLED=true

Point the OpenTelemetry SDK at your collector / Phoenix instance:

OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_SERVICE_NAME=my-app
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:6006   # Phoenix OTLP endpoint

Configuration

php artisan vendor:publish --tag=prism-opentelemetry-config

Key	Env	Default	Description
enabled	PRISM_OTEL_ENABLED	true	Subscribe the span-building listener.
tracer_name	PRISM_OTEL_TRACER_NAME	prism	Instrumentation scope name.
record_exceptions	PRISM_OTEL_RECORD_EXCEPTIONS	true	Record the exception on failed spans.

Privacy

By default, spans carry metadata only: tokens, timing, model, finish reason and provider rate limits. Prompts, completions, tool arguments and tool results are added as input.value / output.value only when Prism's prism.telemetry.capture_content is on, and it is off by default. Each captured attribute is cut to content_max_length.

Attachment bytes are withheld even with content capture on. A captured message's images, documents, audio and video keep their kind, mime type, file id and filename, and their base64 is replaced by omitted_bytes, the size of what was left out. To export the bytes as well, set Prism's prism.telemetry.capture_media (PRISM_TELEMETRY_CAPTURE_MEDIA=true). Bytes a user pastes into a prompt as text are text, and are exported with the prompt.

License

MIT © Particle Academy