open-telemetry / opentelemetry-auto-phalcon

0.1.0 2026-10-01 00:19 UTC

Requires

• php: ^8.2
• composer-runtime-api: ^2.0
• ext-opentelemetry: *
• ext-phalcon: ^5.0
• open-telemetry/api: ^1.6
• open-telemetry/sem-conv: ^1.38

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3
• open-telemetry/sdk: ^1.8
• phan/phan: ^6.0
• php-http/mock-client: *
• phpstan/phpstan: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• phpunit/phpunit: ^9.5
• psalm/plugin-phpunit: ^0.19.2
• vimeo/psalm: ^6.4

Suggests

• open-telemetry/opentelemetry-propagation-server-timing: Automatically propagate the context to the client through server-timing headers.
• open-telemetry/opentelemetry-propagation-traceresponse: Automatically propagate the context to the client through trace-response headers.

Apache-2.0

• phalcon
• instrumentation
• tracing
• opentelemetry
• open-telemetry
• otel

Published on Packagist.org on 2026-10-01 00:24 UTC

README

This is a read-only subtree split of https://github.com/open-telemetry/opentelemetry-php-contrib.

OpenTelemetry Phalcon auto-instrumentation

This is an OpenTelemetry auto-instrumentation package for applications built on the Phalcon PHP framework.

Please read https://opentelemetry.io/docs/instrumentation/php/automatic/ for instructions on how to install and configure the extension and SDK.

Requirements

• PHP >= 8.2 — hook() observes internal/extension functions (what every method on compiled Phalcon classes is) via Zend Observer API support added in PHP 8.2; on 8.1 hooks register but never fire.
• OpenTelemetry extension
• OpenTelemetry SDK and exporters (required to actually export traces)
• Phalcon 5.x (ext-phalcon)

Overview

A request can reach Phalcon through several different entry points, and no single one of them covers every app — auto-instrumentation hooks all of them so exactly one root span is created regardless of which style the application uses:

• Phalcon\Mvc\Application::handle() — full MVC apps.
• Phalcon\Mvc\Micro::handle() — Micro apps, which route straight to a handler callable and never touch a dispatcher.
• Phalcon\Cli\Console::handle() — CLI tasks (INTERNAL span, no HTTP attributes).
• Phalcon\Dispatcher\AbstractDispatcher::dispatch() — fallback root, only when none of the above already started one (e.g. an app building and dispatching a Mvc\Dispatcher directly, without a surrounding Application).

The root span is named after the matched route when the application uses named routes, its raw pattern when it has one and isn't a raw-regex default route, and falls back to {controller}/{action} ({task}/{action} for CLI) otherwise.

AbstractDispatcher::callActionMethod() produces one child span (INTERNAL kind) per controller action actually invoked, including one for a forward()-ed action (Phalcon's forward() doesn't re-enter dispatch(); it makes dispatch()'s own internal loop run callActionMethod() again for the new action) and for an app manually re-dispatching to resolve a nested resource.

Installation via composer

$ composer require open-telemetry/opentelemetry-auto-phalcon

Installing dependencies and executing tests

From the repository root, using the Makefile (runs inside this repo's Docker image, so you don't need PHP or Phalcon installed locally):

$ PROJECT=Instrumentation/Phalcon PHP_VERSION=8.2 make install
$ PROJECT=Instrumentation/Phalcon PHP_VERSION=8.2 make test

make all runs style, static analysis, and tests together. See make help for the full list of targets.

Configuration

The extension can be disabled via runtime configuration:

OTEL_PHP_DISABLED_INSTRUMENTATIONS=phalcon