PHPackages                             open-telemetry/ext-opentelemetry - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. open-telemetry/ext-opentelemetry

ActivePhp-ext[Logging & Monitoring](/categories/logging)

open-telemetry/ext-opentelemetry
================================

Auto-instrumentation extension for OpenTelemetry

1.3.0(1mo ago)13518.7k↑36.1%33[13 PRs](https://github.com/open-telemetry/opentelemetry-php-instrumentation/pulls)Apache-2.0CPHP ^8.0CI passing

Since May 14Pushed 1mo ago22 watchersCompare

[ Source](https://github.com/open-telemetry/opentelemetry-php-instrumentation)[ Packagist](https://packagist.org/packages/open-telemetry/ext-opentelemetry)[ RSS](/packages/open-telemetry-ext-opentelemetry/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)DependenciesVersions (25)Used By (0)

OpenTelemetry auto-instrumentation extension
============================================

[](#opentelemetry-auto-instrumentation-extension)

[![Build and test](https://github.com/open-telemetry/opentelemetry-php-instrumentation/actions/workflows/build.yml/badge.svg)](https://github.com/open-telemetry/opentelemetry-php-instrumentation/actions/workflows/build.yml)

Current Project Status
----------------------

[](#current-project-status)

For more information, please consult the documentation of the main [OpenTelemetry PHP project](https://github.com/open-telemetry/opentelemetry-php).

Issues
------

[](#issues)

Issues have been disabled for this repo in order to help maintain consistency between this repo and the main [OpenTelemetry PHP project](https://github.com/open-telemetry/opentelemetry-php) repo. If you have an issue you'd like to raise about this issue, please use the [OpenTelemetry PHP Issue section](https://github.com/open-telemetry/opentelemetry-php/issues/new/choose). Please prefix the title of the issue with \[opentelemetry-php-instrumentation\].

Description
-----------

[](#description)

This is a PHP extension for OpenTelemetry, to enable auto-instrumentation. It is based on [zend\_observer](https://www.datadoghq.com/blog/engineering/php-8-observability-baked-right-in/) and requires php8+

The extension allows:

- creating `pre` and `post` hook functions to arbitrary PHP functions and methods, which allows those methods to be wrapped with telemetry
- adding attributes to functions and methods to enable observers at runtime

In PHP 8.2+, internal/built-in PHP functions can also be observed.

Requirements
------------

[](#requirements)

- PHP 8+
- [OpenTelemetry PHP library](https://github.com/open-telemetry/opentelemetry-php)

Installation
------------

[](#installation)

The extension can be installed in all of the usual ways:

### pecl

[](#pecl)

```
pecl install opentelemetry
```

### php-extension-installer

[](#php-extension-installer)

If you are using the [official PHP docker images](https://hub.docker.com/_/php) then you can use [php-extension-installer](https://github.com/mlocati/docker-php-extension-installer)

From github:

```
install-php-extensions opentelemetry-php/ext-opentelemetry@main
```

Via pecl/pickle:

```
install-php-extensions opentelemetry[-beta|-stable|-latest]
```

### Windows

[](#windows)

Pre-built windows binaries are available from the [releases page](https://github.com/open-telemetry/opentelemetry-php-instrumentation/releases)

See [https://wiki.php.net/internals/windows/stepbystepbuild\_sdk\_2#building\_pecl\_extensions\_with\_phpize](https://wiki.php.net/internals/windows/stepbystepbuild_sdk_2#building_pecl_extensions_with_phpize)for generic advice on building from source under Windows.

Verify that the extension is installed and enabled
--------------------------------------------------

[](#verify-that-the-extension-is-installed-and-enabled)

```
php --ri  opentelemetry
```

Known issues
------------

[](#known-issues)

### Conflicting extensions

[](#conflicting-extensions)

The extension can be configured to not run if a conflicting extension is installed. The following extensions are known to not work when installed alongside OpenTelemetry:

- SourceGuardian

If the conflicting extension is a regular PHP extension (i.e, not a [zend\_extension](https://www.phpinternalsbook.com/php7/extensions_design/zend_extensions.html)), you can control conflicts via the `opentelemetry.conflicts` ini setting.

If a conflicting extension is found, then the OpenTelemetry extension will disable itself:

```
php --ri opentelemetry

Notice: PHP Startup: Conflicting extension found (blackfire), disabling OpenTelemetry in Unknown on line 0

opentelemetry

opentelemetry hooks => disabled (conflict)
extension version => 1.0.0beta6

Directive => Local Value => Master Value
opentelemetry.conflicts => blackfire => blackfire
opentelemetry.validate_hook_functions => On => On
```

### Invalid pre/post hooks

[](#invalid-prepost-hooks)

Invalid argument types in `pre` and `post` callbacks can cause fatal errors. Runtime checking is performed on the hook functions to ensure they are compatible. If not, the hook will not be executed and an error will be generated.

This feature can be disabled by setting the `opentelemetry.validate_hook_functions` ini value to `Off`;

### Increasing function argument count

[](#increasing-function-argument-count)

By default, increasing the number of arguments provided to a function in the pre hook is allowed only if that does not require the stack frame of the function call to be extended in size. For internal functions, adding arguments not provided at the callsite always requires stack extension. For PHP functions, it is required only if the argument is not included in the function definition.

Extending stack frame automatically can be enabled by setting `opentelemetry.allow_stack_extension` ini value to `On`. This enables extending the stack frame by up to another 16 arguments.

Usage
-----

[](#usage)

The `pre` method starts and activates a span. The `post` method ends the span after the observed method has finished.

```