Початок роботи

Почніть працювати з OpenTelemetry для PHP.

OpenTelemetry для PHP можна використовувати для генерації та експорту трасувань, метрик та логів.

Ця сторінка покаже вам, як почати роботу з OpenTelemetry у PHP. Ми створимо простий застосунок “кидання кубика”, потім застосуємо як інструментування без коду, так і інструментування з кодом для генерації трасувань та експорту їх до консолі. Потім ми згенеруємо деякі логи, які також будуть відправлені до консолі.

Передумови

OpenTelemetry вимагає PHP 8.0+ для інструментування без коду, однак ручне інструментування працюватиме з PHP 7.4

Переконайтеся, що у вас встановлено наступне:

Перед тим, як почати, переконайтеся, що у вашій оболонці доступні обидва:

php -v
composer -v

Приклад застосунку

Наступний приклад використовує базовий застосунок Slim Framework. Якщо ви не використовуєте Slim, це не проблема, ви можете використовувати OpenTelemetry PHP з іншими веб-фреймворками, такими як WordPress, Symfony та Laravel. Для повного списку бібліотек для підтримуваних фреймворків дивіться реєстр.

Залежності

У порожній теці ініціалізуйте мінімальний файл composer.json:

composer init \
  --no-interaction \
  --require slim/slim:"^4" \
  --require slim/psr7:"^1"
composer update

Створення та запуск HTTP сервера

У тій же теці створіть файл з назвою index.php з наступним вмістом:

<?php
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Slim\Factory\AppFactory;

require __DIR__ . '/vendor/autoload.php';

$app = AppFactory::create();

$app->get('/rolldice', function (Request $request, Response $response) {
    $result = random_int(1,6);
    $response->getBody()->write(strval($result));
    return $response;
});

$app->run();

Запустіть застосунок за допомогою вбудованого вебсервера PHP:

php -S localhost:8080

Відкрийте http://localhost:8080/rolldice у вашому вебоглядачі, щоб переконатися, що він працює.

Додати інструментування без коду

Далі ви будете використовувати розширення OpenTelemetry PHP для автоматичного інструментування застосунку.

Оскільки розширення збирається з вихідного коду, вам потрібно встановити деякі інструменти для збірки
```
sudo apt-get install gcc make autoconf
```
```
brew install gcc make autoconf
```
Зберіть розширення за допомогою PECL:
```
pecl install opentelemetry
```
Примітка
Альтернативні методи встановлення розширення детально описані в розділі інструментування без коду.
Додайте розширення до вашого файлу php.ini:
```
[opentelemetry]
extension=opentelemetry.so
```
Перевірте, що розширення встановлено та увімкнено:
```
php --ri opentelemetry
```
Додайте додаткові залежності до вашого застосунку, які потрібні для автоматичного інструментування вашого коду:
```
composer config allow-plugins.php-http/discovery false
composer require \
  open-telemetry/sdk \
  open-telemetry/opentelemetry-auto-slim
```

З налаштованим розширенням OpenTelemetry PHP та встановленою бібліотекою інструментування, ви можете запустити ваш застосунок та згенерувати деякі трасування:

env OTEL_PHP_AUTOLOAD_ENABLED=true \
    OTEL_TRACES_EXPORTER=console \
    OTEL_METRICS_EXPORTER=none \
    OTEL_LOGS_EXPORTER=none \
    php -S localhost:8080

Відкрийте http://localhost:8080/rolldice у вашому вебоглядачі та перезавантажте сторінку кілька разів. Через деякий час ви повинні побачити відрізки, надруковані у вашій консолі:

Переглянути приклад виводу

[
  {
    "name": "GET /rolldice",
    "context": {
      "trace_id": "16d7c6da7c021c574205736527816eb7",
      "span_id": "268e52331de62e33",
      "trace_state": ""
    },
    "resource": {
      "service.name": "__root__",
      "service.version": "1.0.0+no-version-set",
      "telemetry.sdk.name": "opentelemetry",
      "telemetry.sdk.language": "php",
      "telemetry.sdk.version": "1.0.0beta10",
      "telemetry.auto.version": "1.0.0beta5",
      "process.runtime.name": "cli-server",
      "process.runtime.version": "8.2.6",
      "process.pid": 24435,
      "process.executable.path": "/bin/php",
      "process.owner": "php",
      "os.type": "darwin",
      "os.description": "22.4.0",
      "os.name": "Darwin",
      "os.version": "Darwin Kernel Version 22.4.0: Mon Mar  6 20:59:28 PST 2023; root:xnu-8796.101.5~3/RELEASE_ARM64_T6000",
      "host.name": "OPENTELEMETRY-PHP",
      "host.arch": "arm64"
    },
    "parent_span_id": "",
    "kind": "KIND_SERVER",
    "start": 1684749478068582482,
    "end": 1684749478072715774,
    "attributes": {
      "code.function": "handle",
      "code.namespace": "Slim\\App",
      "code.filepath": "/vendor/slim/slim/Slim/App.php",
      "code.lineno": 197,
      "http.url": "http://localhost:8080/rolldice",
      "http.method": "GET",
      "http.request_content_length": "",
      "http.scheme": "http",
      "http.status_code": 200,
      "http.flavor": "1.1",
      "http.response_content_length": ""
    },
    "status": {
      "code": "Unset",
      "description": ""
    },
    "events": [],
    "links": []
  }
]

Додати ручне інструментування

Трасування

Ручне трасування вимагає TracerProvider. Існує кілька способів його налаштування. У цьому прикладі ми будемо використовувати автозавантажений TracerProvider, який доступний глобально.

Замініть index.php наступним кодом:

<?php

use OpenTelemetry\API\Globals;
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Slim\Factory\AppFactory;

require __DIR__ . '/vendor/autoload.php';

$tracer = Globals::tracerProvider()->getTracer('demo');

$app = AppFactory::create();

$app->get('/rolldice', function (Request $request, Response $response) use ($tracer) {
    $span = $tracer
        ->spanBuilder('manual-span')
        ->startSpan();
    $result = random_int(1,6);
    $response->getBody()->write(strval($result));
    $span
        ->addEvent('rolled dice', ['result' => $result])
        ->end();
    return $response;
});

$app->run();

Знову запустіть вбудований вебсервер і перейдіть до http://localhost:8080/rolldice. Ви повинні побачити подібний вивід, але з додаванням нового відрізка з назвою manual-span.

Зверніть увагу, що parent_span_id ручного відрізка містить те саме значення, що і context.span_id відрізка “{closure}”. Ручне та автоматичне інструментування добре працюють разом, оскільки під капотом вони використовують ті самі API.

Логування

Тепер додамо деяке логування. Ми будемо використовувати популярну бібліотеку логування monolog для цього, через обробник, який буде генерувати логи у форматі OpenTelemetry.

Спочатку встановимо деякі додаткові залежності:

composer require \
  monolog/monolog \
  open-telemetry/opentelemetry-logger-monolog

Замініть файл index.php наступним кодом:

<?php

use Monolog\Logger;
use OpenTelemetry\API\Globals;
use OpenTelemetry\Contrib\Logs\Monolog\Handler;
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Psr\Log\LogLevel;
use Slim\Factory\AppFactory;

require __DIR__ . '/vendor/autoload.php';

$loggerProvider = Globals::loggerProvider();
$handler = new Handler(
    $loggerProvider,
    LogLevel::INFO
);
$monolog = new Logger('otel-php-monolog', [$handler]);

$app = AppFactory::create();

$app->get('/rolldice', function (Request $request, Response $response) use ($monolog) {
    $result = random_int(1,6);
    $response->getBody()->write(strval($result));
    $monolog->info('dice rolled', ['result' => $result]);
    return $response;
});

$app->run();

Запустіть вбудований вебсервер з наступною командою (зверніть увагу на зміну OTEL_LOGS_EXPORTER):

env OTEL_PHP_AUTOLOAD_ENABLED=true \
    OTEL_TRACES_EXPORTER=console \
    OTEL_METRICS_EXPORTER=none \
    OTEL_LOGS_EXPORTER=console \
    php -S localhost:8080

Цього разу при переході до http://localhost:8080/rolldice ви повинні побачити автоматичні трасування, як і раніше, а також запис логу, який був згенерований обробником monolog.

Зверніть увагу, що trace_id та span_id були додані до виводу журналу, і що значення відповідають активному відрізку на момент генерації повідомлення журналу.

Переглянути приклад виводу

[
    {
        "name": "{closure}",
        "context": {
            "trace_id": "8b046fc5d43864058b6a5a18e0dfce3f",
            "span_id": "9cf24c78c6868bfe",
            "trace_state": ""
        },
        "resource": {
            "service.name": "__root__",
            "service.version": "1.0.0+no-version-set",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.language": "php",
            "telemetry.sdk.version": "1.0.0beta11",
            "telemetry.auto.version": "1.0.0beta6",
            "process.runtime.name": "cli-server",
            "process.runtime.version": "8.0.27",
            "process.pid": 2672,
            "process.executable.path": "\/usr\/local\/bin\/php",
            "process.owner": "root",
            "os.type": "linux",
            "os.description": "5.15.0-75-generic",
            "os.name": "Linux",
            "os.version": "#82-Ubuntu SMP Tue Jun 6 23:10:23 UTC 2023",
            "host.name": "f2c0afe83ea9",
            "host.arch": "x86_64"
        },
        "parent_span_id": "df2199a615085705",
        "kind": "KIND_INTERNAL",
        "start": 1687323704059486500,
        "end": 1687323704060820769,
        "attributes": {
            "code.function": "__invoke",
            "code.namespace": "Slim\\Handlers\\Strategies\\RequestResponse",
            "code.filepath": "\/usr\/src\/myapp\/vendor\/slim\/slim\/Slim\/Handlers\/Strategies\/RequestResponse.php",
            "code.lineno": 28
        },
        "status": {
            "code": "Unset",
            "description": ""
        },
        "events": [],
        "links": []
    }
]
[
    {
        "name": "GET \/rolldice",
        "context": {
            "trace_id": "8b046fc5d43864058b6a5a18e0dfce3f",
            "span_id": "df2199a615085705",
            "trace_state": ""
        },
        "resource": {
            "service.name": "__root__",
            "service.version": "1.0.0+no-version-set",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.language": "php",
            "telemetry.sdk.version": "1.0.0beta11",
            "telemetry.auto.version": "1.0.0beta6",
            "process.runtime.name": "cli-server",
            "process.runtime.version": "8.0.27",
            "process.pid": 2672,
            "process.executable.path": "\/usr\/local\/bin\/php",
            "process.owner": "root",
            "os.type": "linux",
            "os.description": "5.15.0-75-generic",
            "os.name": "Linux",
            "os.version": "#82-Ubuntu SMP Tue Jun 6 23:10:23 UTC 2023",
            "host.name": "f2c0afe83ea9",
            "host.arch": "x86_64"
        },
        "parent_span_id": "",
        "kind": "KIND_SERVER",
        "start": 1687323704058191192,
        "end": 1687323704060981779,
        "attributes": {
            "code.function": "handle",
            "code.namespace": "Slim\\App",
            "code.filepath": "\/usr\/src\/myapp\/vendor\/slim\/slim\/Slim\/App.php",
            "code.lineno": 197,
            "http.url": "http:\/\/localhost:8080\/rolldice",
            "http.method": "GET",
            "http.request_content_length": "",
            "http.scheme": "http",
            "http.status_code": 200,
            "http.flavor": "1.1",
            "http.response_content_length": ""
        },
        "status": {
            "code": "Unset",
            "description": ""
        },
        "events": [],
        "links": []
    }
]
{
    "resource": {
        "attributes": {
            "service.name": "__root__",
            "service.version": "1.0.0+no-version-set",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.language": "php",
            "telemetry.sdk.version": "1.0.0beta11",
            "telemetry.auto.version": "1.0.0beta6",
            "process.runtime.name": "cli-server",
            "process.runtime.version": "8.0.27",
            "process.pid": 2672,
            "process.executable.path": "\/usr\/local\/bin\/php",
            "process.owner": "root",
            "os.type": "linux",
            "os.description": "5.15.0-75-generic",
            "os.name": "Linux",
            "os.version": "#82-Ubuntu SMP Tue Jun 6 23:10:23 UTC 2023",
            "host.name": "f2c0afe83ea9",
            "host.arch": "x86_64"
        },
        "dropped_attributes_count": 0
    },
    "scope": {
        "name": "monolog",
        "version": null,
        "attributes": [],
        "dropped_attributes_count": 0,
        "schema_url": null,
        "logs": [
            {
                "timestamp": 1687323704059648000,
                "observed_timestamp": 1687323704060784128,
                "severity_number": 9,
                "severity_text": "INFO",
                "body": "dice rolled",
                "trace_id": "8b046fc5d43864058b6a5a18e0dfce3f",
                "span_id": "9cf24c78c6868bfe",
                "trace_flags": 1,
                "attributes": {
                    "channel": "otel-php-monolog",
                    "context": {
                        "result": 4
                    }
                },
                "dropped_attributes_count": 0
            }
        ]
    }
}

Що далі?

Для більшого:

Запустіть цей приклад з іншим експортером для даних телеметрії.
Спробуйте інструментування без коду на одному з ваших власних застосунків.
Дізнайтеся більше про ручне інструментування та спробуйте деякі приклади.
Погляньте на OpenTelemetry Demo, який включає оснований на PHP Quote Service.

Відгук

Чи це було корисним?

Дякуємо. Ми цінуємо ваші відгуки!

Будь ласка, дайте нам знати як ми можемо покращити цю сторінку. Ми цінуємо ваші відгуки!

Востаннє змінено December 26, 2024: [uk] Ukrainian documentation for OpenTelemetry (2a3c5648)