README

为 yii2 开发的跟踪库，与 jaeger 兼容。

使用方法

0. 安装 Yii2

$ composer create-project --prefer-dist yiisoft/yii2-app-basic basic

1. 安装 felix021/xtracer

$ composer require felix021/xtracer:dev-master

2. 配置

2.1 config/web.php

注意：您应该为每个应用程序设置一个可识别的名称。

$config = [
    'name' => '<APP NAME>', # will be saved to log
    ...
    'on beforeAction' => ['XTracer\Tracer','beforeAction'],
    'on afterAction' => ['XTracer\Tracer','afterAction'],
    ...
    components => [
        ...
        'tracer' => [
            'class' => 'XTracer\Tracer',
            'maskRules' => [
                ['mobile', 'prefixSuffix', [3, 4]],
                ['password', 'all', [8]],
                ['name', 'prefix', [-1]],
            ],
        ],
        ...
        'log' => [
            'traceLevel' => YII_DEBUG ? 3 : 0,
            'targets' => [
                [
                    'class' => 'XTracer\FileTarget',
                    'levels' => ['info', 'error', 'warning'],
                    'logVars' => [],
                ],
                [
                    'class' => 'XTracer\FileTarget',
                    'levels' => ['info'],
                    'categories' => ['jaeger'],
                    'logFile' => '@runtime/logs/jaeger.log',
                    'logVars' => [],
                ],
            ],
        ],
        ...
        # not necessary, but I'll leave it here as a guide
        'urlManager' => [
            'enablePrettyUrl' => true,
            'showScriptName' => false,
            'rules' => [
            ],
        ],
        ...
    ],
];

2.2 config/console.php

$config = [
    'id' => '<APP NAME>' # it should be the same as in `config/web.php`
    ...
    'on beforeAction' => ['XTracer\Tracer','beforeAction'],
    'on afterAction' => ['XTracer\Tracer','afterAction'],
    ...
    components => [
        ...
        'tracer' => [
            'class' => 'XTracer\Tracer',
            'maskRules' => [
                ['mobile', 'prefixSuffix', [3, 4]],
                ['password', 'all', [8]],
                ['name', 'prefix', [-1]],
            ],
        ],
        ...
        'log' => [
            'traceLevel' => YII_DEBUG ? 3 : 0,
            'targets' => [
                [
                    'class' => 'XTracer\FileTarget',
                    'levels' => ['info', 'error', 'warning'],
                    'logVars' => [],
                ],
                [
                    'class' => 'XTracer\FileTarget',
                    'levels' => ['info'],
                    'categories' => ['jaeger'],
                    'logFile' => '@runtime/logs/jaeger.log',
                    'logVars' => [],
                ],
            ],
        ],
        ...
    ],
];

3. 跟踪与日志

每次当 yii 收到 http 请求，或开始执行控制台命令时，都会创建一个跨度。执行后，跟踪信息将保存到 @app/runtime/logs/jaeger.log，每个跨度一行，格式为 json。应将 jaeger.log 发送到类似 ElasticSearch 的后端存储以进行后续分析。

使用 Yii::info($message) 记录额外的运行信息，这些信息将保存到 @app/runtime/logs/app.log，每条日志一行，格式为 json。

此外，当接收到 http 请求时，将保存包含 $_GET、$_POST 和 $_SERVER 的消息到 @app/runtime/logs/app.log 以供调试。

4. 外部请求

在发出外部请求之前初始化 \Xtracer\Outbound，这将创建一个子跨度，并调用其 finish 方法以记录请求。

示例

# Initialize
$outbound = new \XTracer\Outbound($this->span);

# Pass the trace information to downstream services if they support jaeger's tracing standard
# $trace = $outbound->getTraceKey() . ': ' . $outbound->getTraceValue();

# Issue the call
$result = ...;

# logging
$outbound->addTag('request.status', 'int64', strval($result['code']));
$outbound->finish();

如果是一个 http 请求，\XTracer\Http 将帮助您完成上述所有操作，包括将 traceid 通过 http 标头 uber-trace-id 传递给下游服务，如 jaeger 文档中定义的那样。

示例

use XTracer\Http;

$response = (new Http())->get("https://www.google.com");
if ($response['errno'] != 0) {
    throw new Exception("failed: " . $response['message']);
}
echo $response['body'], "\n";
Yii::info($response);

#more usage
$response = (new Http())->post("https://www.google.com", ['a'=>1]);
$response = (new Http())->call("POST", "https://www.google.com", '{"a": 1}', ['Content-Type: application/json']);
$response = (new Http())->call("POST", "https://www.google.com", '{"a": 1}', ['Content-Type: application/json'], [CURLOPT_SSL_VERIFYPEER => false]);

5. 隐藏

在 config['components'] 中为 \XTracer\Tracer 设置 maskRules 属性，以隐藏 $_GET/$_POST 中的敏感数据，这些数据将被保存到 app.log。

规则格式为 [$key, $method, $argArray]，其中 $method 可以是预定义操作之一

• ['password', 'unset', []]：在记录之前删除此键
• ['password', 'all', [8]]：将所有字符替换为 8 个星号 ('*')
• ['name', 'prefix', [1]]：只保留前缀字符，并将剩余的替换为 '*'
• ['name', 'prefix', [-1]]：只替换前缀字符为 '*'
• ['name', 'suffix', [1]]：只保留最后字符，并将剩余的替换为 '*'
• ['name', 'suffix', [-1]]：只替换最后字符为 '*'
• ['mobile', 'prefixSuffix', [3, 4]]：只保留前 3 和最后 4 个字符
• ['mobile', 'prefixSuffix', [-3, -4]]：只替换前 3 和最后 4 个字符

$method 还可以是一个自定义方法。请参阅 XTracer\Mask::maskPrefix。

如果以上都不够，您还可以为 \XTracer\Tracer 设置额外的 maskMethod 属性，它接收整个数组，并返回被隐藏的数组。