入门指南

使用OpenTelemetry for PHP进行开发和运行。

OpenTelemetry for PHP可用于生成和导出traces、metrics和logs。

本页将向您展示如何在PHP中使用OpenTelemetry进行入门。我们将创建一个简单的“摇色子”应用程序，然后应用自动和手动的Instrumentation来生成traces并将其导出到控制台上。然后我们将发出一些logs，也会发送到控制台上。

前提条件

自动Instrumentation需要PHP 8.0+，但手动Instrumentation适用于PHP 7.4。

确保您已安装以下内容：

开始之前，请确保在shell中都可用：

php -v
composer -v

示例应用程序

以下示例使用基本的Slim Framework应用程序。如果您不使用Slim也没关系，您也可以将OpenTelemetry PHP与其他Web框架一起使用，例如WordPress、Symfony和Laravel。有关受支持的框架的完整列表，请参见registry。

依赖项

在一个空目录中初始化一个最小的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内置的Web服务器运行应用程序：

php -S localhost:8080

在Web浏览器中打开http://localhost:8080/rolldice来确保它正常工作。

添加自动Instrumentation

接下来，您将使用OpenTelemetry PHP扩展来自动Instrumentation应用程序。

由于扩展是从源代码构建的，您需要安装一些构建工具
```
sudo apt-get install gcc make autoconf
```
```
brew install gcc make autoconf
```
使用PECL构建扩展：
```
pecl install opentelemetry
```
注意
有关安装扩展的替代方法的详细信息，请参阅自动Instrumentation。

将扩展添加到您的php.ini文件中：

[opentelemetry]
extension=opentelemetry.so

验证扩展是否已安装并启用：
```
php --ri opentelemetry
```

添加其他依赖项到您的应用程序中，这些依赖项是自动Instrumentation所需的：

composer config allow-plugins.php-http/discovery false
composer require \
  open-telemetry/sdk \
  open-telemetry/opentelemetry-auto-slim

配置好OpenTelemetry PHP扩展并安装了一个自动Instrumentation包后，您现在可以运行您的应用程序并生成一些traces：

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

在Web浏览器中打开http://localhost:8080/rolldice并连续刷新页面几次。一段时间后，您应该在控制台上看到已打印的spans：

查看示例输出

[
  {
    "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": []
  }
]

添加手动Instrumentation

Traces

手动追踪需要一个TracerProvider。有多种方式来设置一个TracerProvider。在本示例中，我们将使用自动加载的TracerProvider，它是全局可用的。

使用以下代码替换index.php：

<?php

use OpenTelemetry\API\Common\Instrumentation\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();

再次启动内置的Web服务器，并浏览到http://localhost:8080/rolldice。您应该会看到类似的输出，但是多了一个名为manual-span的新span。

请注意，手动span的parent_span_id与"{closure}" span的context.span_id相同。手动Instrumentation和自动Instrumentation可以很好地协同工作，因为它们在底层使用相同的API。

Logging

现在让我们添加一些日志记录。我们将使用流行的monolog日志记录库，通过一个处理程序以OpenTelemetry格式发出日志。

首先，让我们安装一些其他依赖项：

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

使用以下代码替换index.php文件：

<?php

use Monolog\Logger;
use OpenTelemetry\API\Common\Instrumentation\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();

使用以下命令启动内置的Web服务器（注意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时，您应该会看到与以前相同的自动Instrumentation traces，以及由monolog处理程序生成的日志记录。

请注意，日志输出中添加了trace_id和span_id，这些值对应于生成日志消息时的活动span。