# Інструментування PHP без коду

LLMS index: [llms.txt](/llms.txt)

---

## Вимоги {#requirements}

Автоматичне інструментування з PHP вимагає:

- PHP 8.0 або вище
- [Розширення OpenTelemetry PHP](https://github.com/open-telemetry/opentelemetry-php-instrumentation)
- [Автозавантаження Composer](https://getcomposer.org/doc/01-basic-usage.md#autoloading)
- [OpenTelemetry SDK](https://packagist.org/packages/open-telemetry/sdk)
- Одна або більше [бібліотек інструментування](/ecosystem/registry/?component=instrumentation&language=php)
- [Конфігурація](#configuration)

## Встановлення розширення OpenTelemetry {#install-the-opentelemetry-extension}

> [!IMPORTANT]
>
> Встановлення розширення OpenTelemetry само по собі не генерує трасування.

Розширення можна встановити через pecl, [pickle](https://github.com/FriendsOfPHP/pickle), [PIE](https://github.com/php/pie) або [php-extension-installer](https://github.com/mlocati/docker-php-extension-installer) (специфічно для docker). Також є пакетовані версії розширення, доступні для деяких менеджерів пакетів Linux.

### Пакунки Linux {#linux-packages}

Пакунки RPM та APK надаються наступними джерелами:

- [Репозиторій Remi](https://blog.remirepo.net/pages/PECL-extensions-RPM-status) - RPM
- [Alpine Linux](https://pkgs.alpinelinux.org/packages?name=*pecl-opentelemetry) - APK (наразі в [_testing_ гілці](https://wiki.alpinelinux.org/wiki/Repositories#Testing))

   <ul class="nav nav-tabs" id="tabs-0" role="tablist">
  <li class="nav-item">
      <button class="nav-link active"
          id="tabs-00-00-tab" data-bs-toggle="tab" data-bs-target="#tabs-00-00" role="tab"
          data-td-tp-persist="rpm" aria-controls="tabs-00-00" aria-selected="true">
        RPM
      </button>
    </li><li class="nav-item">
      <button class="nav-link"
          id="tabs-00-01-tab" data-bs-toggle="tab" data-bs-target="#tabs-00-01" role="tab"
          data-td-tp-persist="apk" aria-controls="tabs-00-01" aria-selected="false">
        APK
      </button>
    </li>
</ul>

<div class="tab-content" id="tabs-0-content">
    <div class="tab-body tab-pane fade show active"
        id="tabs-00-00" role="tabpanel" aria-labelled-by="tabs-00-00-tab" tabindex="0">
        <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl"><span class="c1">#цей приклад для CentOS 7. Версію PHP можна змінити</span>
</span></span><span class="line"><span class="cl"><span class="c1">#включивши remi-&lt;version&gt;, наприклад &#34;yum config-manager --enable remi-php83&#34;</span>
</span></span><span class="line"><span class="cl">yum update -y
</span></span><span class="line"><span class="cl">yum install -y epel-release yum-utils
</span></span><span class="line"><span class="cl">yum install -y http://rpms.remirepo.net/enterprise/remi-release-7.rpm
</span></span><span class="line"><span class="cl">yum-config-manager --enable remi-php81
</span></span><span class="line"><span class="cl">yum install -y php php-pecl-opentelemetry
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">php --ri opentelemetry
</span></span></code></pre></div>
    </div>
    <div class="tab-body tab-pane fade"
        id="tabs-00-01" role="tabpanel" aria-labelled-by="tabs-00-01-tab" tabindex="0">
        <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl"><span class="c1">#На момент написання, PHP 8.1 була стандартною версією PHP. Можливо, вам доведеться</span>
</span></span><span class="line"><span class="cl"><span class="c1">#змінити &#34;php81&#34;, якщо стандарт зміниться. Ви також можете вибрати версію PHP</span>
</span></span><span class="line"><span class="cl"><span class="c1">#з &#34;apk add php&lt;version&gt;&#34;, наприклад &#34;apk add php83&#34;.</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;@testing https://dl-cdn.alpinelinux.org/alpine/edge/testing&#34;</span> &gt;&gt; /etc/apk/repositories
</span></span><span class="line"><span class="cl">apk add php php81-pecl-opentelemetry@testing
</span></span><span class="line"><span class="cl">php --ri opentelemetry
</span></span></code></pre></div>
    </div>
</div>


### PECL

1. Налаштуйте середовище розробки. Встановлення з вихідного коду вимагає належного середовища розробки та деяких залежностей:

      <ul class="nav nav-tabs" id="tabs-1" role="tablist">
  <li class="nav-item">
      <button class="nav-link active"
          id="tabs-01-00-tab" data-bs-toggle="tab" data-bs-target="#tabs-01-00" role="tab"
          data-td-tp-persist="linux (apt)" aria-controls="tabs-01-00" aria-selected="true">
        Linux (apt)
      </button>
    </li><li class="nav-item">
      <button class="nav-link"
          id="tabs-01-01-tab" data-bs-toggle="tab" data-bs-target="#tabs-01-01" role="tab"
          data-td-tp-persist="macos (homebrew)" aria-controls="tabs-01-01" aria-selected="false">
        macOS (homebrew)
      </button>
    </li>
</ul>

<div class="tab-content" id="tabs-1-content">
    <div class="tab-body tab-pane fade show active"
        id="tabs-01-00" role="tabpanel" aria-labelled-by="tabs-01-00-tab" tabindex="1">
        <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">sudo apt-get install gcc make autoconf
</span></span></code></pre></div>
    </div>
    <div class="tab-body tab-pane fade"
        id="tabs-01-01" role="tabpanel" aria-labelled-by="tabs-01-01-tab" tabindex="1">
        <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">brew install gcc make autoconf
</span></span></code></pre></div>
    </div>
</div>


2. Збірка/встановлення розширення. Після налаштування середовища ви можете встановити розширення:

       <ul class="nav nav-tabs" id="tabs-2" role="tablist">
  <li class="nav-item">
      <button class="nav-link active"
          id="tabs-02-00-tab" data-bs-toggle="tab" data-bs-target="#tabs-02-00" role="tab"
          data-td-tp-persist="pecl" aria-controls="tabs-02-00" aria-selected="true">
        pecl
      </button>
    </li><li class="nav-item">
      <button class="nav-link"
          id="tabs-02-01-tab" data-bs-toggle="tab" data-bs-target="#tabs-02-01" role="tab"
          data-td-tp-persist="pickle" aria-controls="tabs-02-01" aria-selected="false">
        pickle
      </button>
    </li><li class="nav-item">
      <button class="nav-link"
          id="tabs-02-02-tab" data-bs-toggle="tab" data-bs-target="#tabs-02-02" role="tab"
          data-td-tp-persist="php-extension-installer (docker)" aria-controls="tabs-02-02" aria-selected="false">
        php-extension-installer (docker)
      </button>
    </li>
</ul>

<div class="tab-content" id="tabs-2-content">
    <div class="tab-body tab-pane fade show active"
        id="tabs-02-00" role="tabpanel" aria-labelled-by="tabs-02-00-tab" tabindex="2">
        <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">pecl install opentelemetry
</span></span></code></pre></div>
    </div>
    <div class="tab-body tab-pane fade"
        id="tabs-02-01" role="tabpanel" aria-labelled-by="tabs-02-01-tab" tabindex="2">
        <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">php pickle.phar install opentelemetry
</span></span></code></pre></div>
    </div>
    <div class="tab-body tab-pane fade"
        id="tabs-02-02" role="tabpanel" aria-labelled-by="tabs-02-02-tab" tabindex="2">
        <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">install-php-extensions opentelemetry
</span></span></code></pre></div>
    </div>
</div>


3. Додайте розширення до вашого файлу `php.ini`:

   ```ini
   [opentelemetry]
   extension=opentelemetry.so
   ```

4. Перевірте, що розширення встановлено та увімкнено:

   ```sh
   php -m | grep opentelemetry
   ```

## Встановлення SDK та бібліотек інструментування {#install-sdk-and-instrumentation-libraries}

Після встановлення розширення, встановіть OpenTelemetry SDK та одну або більше бібліотек інструментування.

Автоматичне інструментування доступне для багатьох популярних бібліотек PHP. Для повного списку дивіться [бібліотеки інструментування на packagist](https://packagist.org/search/?query=open-telemetry&tags=instrumentation).

Припустимо, що ваш застосунок використовує Slim Framework і HTTP-клієнт PSR-18, і що ми будемо експортувати трейси за допомогою протоколу OTLP.

Після цього вам потрібно буде встановити SDK, експортер та пакунки для автоматичного інструментування для Slim Framework і PSR-18:

```shell
composer require \
    open-telemetry/sdk \
    open-telemetry/exporter-otlp \
    open-telemetry/opentelemetry-auto-slim \
    open-telemetry/opentelemetry-auto-psr18
```

## Конфігурація {#configuration}

При використанні разом з OpenTelemetry SDK, ви можете використовувати змінні середовища або файл `php.ini` для налаштування автоінструментування.

### Конфігурація середовища {#environment-configuration}

```sh
OTEL_PHP_AUTOLOAD_ENABLED=true \
OTEL_SERVICE_NAME=your-service-name \
OTEL_TRACES_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318 \
OTEL_PROPAGATORS=baggage,tracecontext \
php myapp.php
```

### Конфігурація php.ini {#phpini-configuration}

Додайте наступне до `php.ini`, або іншого `ini` файлу, який буде оброблений PHP:

```ini
OTEL_PHP_AUTOLOAD_ENABLED="true"
OTEL_SERVICE_NAME=your-service-name
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
OTEL_PROPAGATORS=baggage,tracecontext
```

## Запуск вашого застосунку {#running-your-application}

Після того, як все вищезазначене встановлено та налаштовано, запустіть ваш застосунок як зазвичай.

Трасування, яке ви побачите, експортоване до OpenTelemetry Collector, залежить від бібліотек інструментування, які ви встановили, та шляху коду, який був виконаний всередині застосунку. У попередньому прикладі, використовуючи Slim Framework та PSR-18 бібліотеки інструментування, ви повинні очікувати побачити такі відрізки, як:

- Кореневий відрізок, що представляє HTTP транзакцію
- Відрізок для дії, яка була виконана
- Відрізок для кожної HTTP транзакції, яку відправив PSR-18 клієнт

Зверніть увагу, що інструментування PSR-18 клієнта додає [заголовки розподіленого трасування](/docs/concepts/context-propagation/#propagation) до вихідних HTTP запитів.

## Як це працює {#how-it-works}

> [!NOTE] Опціонально" %}}
>
> Ви можете пропустити цей розділ, якщо ви просто хочете швидко запустити, і є відповідні бібліотеки інструментування для вашого застосунку.

Розширення дозволяє реєструвати функції спостерігачів як PHP код для класів та методів, і виконувати ці функції до та після виконання спостережуваного методу.

Якщо немає бібліотеки інструментування для вашого фреймворку або застосунку, ви можете написати свою власну. Наступний приклад надає деякий код для інструментування, а потім ілюструє, як використовувати розширення OpenTelemetry для трасування виконання цього коду.

```php
<?php

use OpenTelemetry\API\Instrumentation\CachedInstrumentation;
use OpenTelemetry\API\Trace\Span;
use OpenTelemetry\API\Trace\StatusCode;
use OpenTelemetry\Context\Context;

require 'vendor/autoload.php';

/* Клас для інструментування */
class DemoClass
{
    public function run(): void
    {
        echo 'Hello, world';
    }
}

/* Код автоінструментування */
OpenTelemetry\Instrumentation\hook(
    class: DemoClass::class,
    function: 'run',
    pre: static function (DemoClass $demo, array $params, string $class, string $function, ?string $filename, ?int $lineno) {
        static $instrumentation;
        $instrumentation ??= new CachedInstrumentation('example');
        $span = $instrumentation->tracer()->spanBuilder('democlass-run')->startSpan();
        Context::storage()->attach($span->storeInContext(Context::getCurrent()));
    },
    post: static function (DemoClass $demo, array $params, $returnValue, ?Throwable $exception) {
        $scope = Context::storage()->scope();
        $scope->detach();
        $span = Span::fromContext($scope->context());
        if ($exception) {
            $span->recordException($exception);
            $span->setStatus(StatusCode::STATUS_ERROR);
        }
        $span->end();
    }
);

/* Запуск інструментованого коду, який буде генерувати трасування */
$demo = new DemoClass();
$demo->run();
```

Попередній приклад визначає `DemoClass`, а потім реєструє `pre` та `post` функції хуків на його методі `run`. Функції хуків виконуються до та після кожного виконання методу `DemoClass::run()`. Функція `pre` починає та активує відрізок, тоді як функція `post` завершує його.

Якщо `DemoClass::run()` викидає виключення, функція `post` записує його без впливу на поширення виключення.

## Наступні кроки {#next-steps}

Після того, як ви налаштували автоматичне інструментування для вашого застосунку або сервісу, ви можете додати [ручне інструментування](/docs/languages/php/instrumentation) для збору користувацьких телеметричних даних.

Для більшої кількості прикладів дивіться [opentelemetry-php-contrib/examples](https://github.com/open-telemetry/opentelemetry-php-contrib/tree/main/examples).