Search by

webpatser / fledge-apm

webpatser

Fiber-aware OpenTelemetry tracing for the Fledge framework, exported as OTLP to Elastic APM or any OTel backend.

Package info

github.com/webpatser/fledge-apm

pkg:composer/webpatser/fledge-apm

Statistics

Installs: 4

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.2.0 2026-11-18 14:38 UTC

This package is auto-updated.

Last update: 2026-11-18 19:38:17 UTC


README

Fiber-aware OpenTelemetry tracing for Fledge apps, exported as OTLP to Elastic APM or any OTel backend.

Fledge runs work in parallel fibers: Livewire lazy cards, FiberDB::concurrent, anything you start with async(). Stock OTel context storage cannot follow that, so parallel work either bleeds into the wrong span or starts a trace of its own. Fledge APM keeps one active span per fiber, and a fiber started with async() inherits the span of whoever started it. A request with five parallel cards shows up as one trace with five sibling spans, and the queries nest under the card that ran them.

It is independent of Laravel Pulse. Pulse stays your at-a-glance dashboard; this gives you the per-request span trees.

Requirements

  • PHP 8.5
  • webpatser/fledge-framework ^13.34
  • webpatser/fledge-fiber ^13.36.0.2 (required: provides Fledge\Async\FiberContext, which lets parallel fibers join the current trace). Without the hook the package logs a warning (at most once an hour).

Install

composer require webpatser/fledge-apm

The OTel SDK discovers its pieces through two Composer plugins, so your app has to allow them:

{
    "config": {
        "allow-plugins": {
            "php-http/discovery": true,
            "tbachert/spi": true
        }
    }
}

The service provider is auto-discovered. To publish the config:

php artisan vendor:publish --tag=apm-config

Configuration

Tracing is off until you turn it on. When disabled, no listeners are registered and the tracer is a no-op, so the cost is zero.

APM_ENABLED=true
APM_SAMPLE_RATE=1.0

OTEL_SERVICE_NAME=my-app
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20<secret-token>"
Variable Default What it does
APM_ENABLED false Master switch.
APM_SAMPLE_RATE 1.0 Share of new traces to keep (0.0 to 1.0).
APM_KEEP_ERRORS true Keep traces with a failed span even when the ratio dropped them.
APM_SLOW_THRESHOLD_MS 1000 Keep traces whose transaction took at least this long. 0 disables.
OTEL_SERVICE_NAME APP_NAME Service name in the APM UI.
OTEL_DEPLOYMENT_ENVIRONMENT APP_ENV Environment label.
OTEL_EXPORTER_OTLP_ENDPOINT http://localhost:4318 Base URL; /v1/traces is appended.
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT none Full traces URL, wins over the base endpoint.
OTEL_EXPORTER_OTLP_HEADERS none Comma separated key=value pairs, values URL encoded.
OTEL_EXPORTER_OTLP_PROTOCOL http/protobuf Or http/json. gRPC is not supported.
OTEL_EXPORTER_OTLP_COMPRESSION gzip Or none.
OTEL_EXPORTER_OTLP_TIMEOUT 2000 Per request, in milliseconds.

The http/protobuf encoder is pure PHP, so ext-protobuf is optional (it only makes encoding faster).

For Elastic, pass credentials in the headers. A secret token:

OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20<secret-token>"

An API key:

OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey%20<base64 id:key>"

The space in the header value is encoded as %20. See config/apm.php for batching, breaker and per-instrumentation options.

Production safety

A tracer must never take your app down with it. Spans are buffered in process and exported after the response was sent (terminating callback, off the response path). Queue workers flush on an interval and once more when they stop. Under Octane, spans are exported once APM_MAX_EXPORT_BATCH_SIZE spans are buffered or APM_WORKER_FLUSH_INTERVAL seconds (default 5) have passed, checked when a request ends, and when the worker stops. Where a Revolt event loop runs (the Fledge server, torque workers), a background timer also exports an idle worker's spans every APM_WORKER_FLUSH_INTERVAL seconds. Under Swoole, RoadRunner and FrankenPHP no loop runs between requests, so an idle worker keeps its spans until its next request or until it stops. A worker killed without a clean stop (kill -9, a reload past its kill timeout) loses what was buffered since its last export: up to APM_MAX_EXPORT_BATCH_SIZE minus one spans plus the last request's spans, capped by APM_MAX_QUEUE_SIZE. A request that produced no spans (not sampled, or APM disabled) does not start a background flush.

  • Flush budget: APM_FLUSH_BUDGET_MS (default 1500) bounds one whole flush, including timeouts and retries. A slow or dead intake holds a PHP-FPM or queue worker for at most that long, and a flush stops at its first failed chunk.
  • No retries on hot paths: retries only happen on the final flush (queue WorkerStopping, shutdown). After an HTTP response or between jobs it is one attempt per chunk.
  • Circuit breaker: after a failed export, every worker skips exporting for APM_BREAKER_SECONDS (default 30) and drops its spans. The state lives in APCu when enabled, else your default cache store, else per process. "Export failure" log lines are throttled to one per window. Running out of the flush budget partway through a flush, after the intake accepted an earlier chunk, does not open the breaker (the rest of the batch is dropped). A first chunk that exhausts the budget, a failure that returns before the deadline (a 5xx or connect error), a request that runs past the flush deadline, and 3 budget cut-offs in a row on one worker still open it; a flush that exports everything resets that count.
  • Bounded memory: the queue holds at most APM_MAX_QUEUE_SIZE spans (default 2048) and exports in chunks of APM_MAX_EXPORT_BATCH_SIZE (default 128).

The safest setup is a collector on localhost: the app posts to localhost:4318 in a millisecond, and the collector (or EDOT agent) handles auth, retries and the trip to Elastic.

What gets traced

Each source can be switched off under apm.instrumentation.

Source Recorded as
HTTP kernel Root transaction: route name, method, status code, user id. Back-dated to request start.
Queue jobs Consumer transaction per job. The traceparent travels in the job payload, so a job continues the trace that dispatched it.
Artisan commands Command transaction. Long-running or noisy commands (queue:work, horizon:*, pulse:*, schedule:work, octane:*, serve, tinker and friends) are skipped; see apm.console.ignore.
Database queries DB span, back-dated by the query time. Statements are truncated at 2048 characters and bindings are never inlined.
Cache Cache spans for get, put and forget. Keys are not recorded by default.
HTTP client Client span per outgoing request of Laravel's Http client, with a traceparent header sent along. URLs are redacted.
Livewire A livewire update span per update request, with mount, update, hydrate, properties, call and render spans per component below it. For FiberHandleRequests batches each lazy card is a sibling span.
Exceptions Reported exceptions are recorded on the active span and mark the transaction as failed, which also makes the trace sampler keep it.

Spans are only created inside a trace, so a query run by something that has no transaction (a boot-time call, say) is skipped instead of creating orphan traces.

Privacy defaults

Option Default Notes
apm.http.record_client_ip false client.address.
apm.http.record_user_agent true user_agent.original.
apm.http.record_user_id true enduser.id.
apm.options.cache.record_keys false Cache keys can hold PII.
apm.options.database.record_bindings false Bindings are stripped from recorded exception messages.
apm.options.http_client.record_full_path false Keeps the path in url.full verbatim; see below.
apm.options.http_client.error_on_4xx false Only 5xx and transport errors mark a client span as failed.

Query bindings are never sent, request bodies and headers are never recorded, and outgoing URLs are redacted.

Outgoing URL paths

url.full on client spans drops userinfo and the fragment, and redacts credential-looking query values. Secrets carried in the path are replaced by REDACTED too: Telegram bot tokens (/botREDACTED/sendMessage), Slack and Discord webhook secrets, and any segment with a random-looking run of 32 or more characters (JWTs, percent-encoded base64 and segments with matrix params included).

UUIDs, version strings and ordinary file names stay readable. 32+ character hex identifiers such as Git SHAs, MD5 object keys and Gravatar hashes are hidden. Set apm.options.http_client.record_full_path to true to get the old behaviour back and export the path verbatim; it applies to the whole app, and userinfo and query redaction still apply.

Limits, stated plainly:

  • A path secret shorter than 32 characters outside the known Telegram, Slack and Discord shapes is exported as is.
  • A wrapper exception that rewords the SQL message instead of including it verbatim still exports what it wrote.
  • The database driver's own message is kept, so a message such as Duplicate entry 'jane@example.test' for key ... still contains the value.

Sampling

Head sampling keeps APM_SAMPLE_RATE of new traces. Below 1.0, traces the ratio dropped are still recorded in memory, and are exported anyway when a span failed (keep.errors) or the transaction was slow (keep.slow_ms). For plain head sampling, set keep.errors to false and keep.slow_ms to 0; dropped traces then cost almost nothing.

An incoming traceparent is ignored by default, so a public client cannot choose your trace ids. Set apm.http.trust_traceparent to true to continue the caller's trace id when requests come from services you own (or a trusted proxy). Even then its sampled flag is not honored by default (apm.http.honor_sampled_flag), so an outside client cannot force or suppress sampling on your app. Turn it on if the caller is another service you own and you want one sampling decision across both.

Known limits

  • Under Swoole, RoadRunner and FrankenPHP an idle worker keeps its buffered spans until its next request or until it stops; see Production safety.
  • Only Laravel's Http client is traced. Other clients (raw Guzzle, curl, SDKs with their own transport) are not.
  • While the circuit breaker is open, spans are dropped, not queued.
  • Raw EventLoop::queue() callbacks and Fledge's low-level server/IO loops do not carry trace context. Fibers started with async() do.

Elastic APM notes

Kibana's APM UI only reads the traces-apm*, metrics-apm* and logs-apm.error* data streams, and those are fed by an APM intake. Writing OTLP at a bare Elasticsearch cluster does nothing. You need one of:

  • APM Server
  • the Elastic Agent with the APM integration (Fleet)
  • an EDOT collector (Elastic Distribution of OpenTelemetry)

Point OTEL_EXPORTER_OTLP_ENDPOINT at that intake. Because this is plain OTLP, the same setup works with any other OTel backend (Tempo, Jaeger, Honeycomb, and so on).

Development

composer test      # Pest
composer lint      # Pint
composer analyse   # PHPStan

License

MIT. See LICENSE.