README

OpenTelemetry是一个包含工具、API和SDK的集合。使用它来对软件进行检测、生成、收集和导出遥测数据（指标、日志和跟踪），以帮助您分析软件的性能和行为。

此包允许在Laravel应用程序中集成OpenTelemetry。

安装

您可以通过composer安装此包

composer require keepsuit/laravel-opentelemetry

您可以使用以下命令发布配置文件

php artisan vendor:publish --provider="Keepsuit\LaravelOpenTelemetry\LaravelOpenTelemetryServiceProvider" --tag="opentelemetry-config"

这是已发布配置文件的内容

<?php

use Keepsuit\LaravelOpenTelemetry\Instrumentation;

return [
    /**
     * Service name
     */
    'service_name' => env('OTEL_SERVICE_NAME', \Illuminate\Support\Str::slug(env('APP_NAME', 'laravel-app'))),

    /**
     * Comma separated list of propagators to use.
     * Supports any otel propagator, for example: "tracecontext", "baggage", "b3", "b3multi", "none"
     */
    'propagators' => env('OTEL_PROPAGATORS', 'tracecontext'),

    /**
     * OpenTelemetry Traces configuration
     */
    'traces' => [
        /**
         * Traces exporter
         * This should be the key of one of the exporters defined in the exporters section
         */
        'exporter' => env('OTEL_TRACES_EXPORTER', 'otlp'),

        /**
         * Traces sampler
         */
        'sampler' => [
            /**
             * Wraps the sampler in a parent based sampler
             */
            'parent' => env('OTEL_TRACES_SAMPLER_PARENT', true),

            /**
             * Sampler type
             * Supported values: "always_on", "always_off", "traceidratio"
             */
            'type' => env('OTEL_TRACES_SAMPLER_TYPE', 'always_on'),

            'args' => [
                /**
                 * Sampling ratio for traceidratio sampler
                 */
                'ratio' => env('OTEL_TRACES_SAMPLER_TRACEIDRATIO_RATIO', 0.05),
            ],
        ],
    ],

    /**
     * OpenTelemetry logs configuration
     */
    'logs' => [
        /**
         * Logs exporter
         * This should be the key of one of the exporters defined in the exporters section
         * Supported drivers: "otlp", "console", "null"
         */
        'exporter' => env('OTEL_LOGS_EXPORTER', 'otlp'),

        /**
         * Inject active trace id in log context
         *
         * When using the OpenTelemetry logger, the trace id is always injected in the exported log record.
         * This option allows to inject the trace id in the log context for other loggers.
         */
        'inject_trace_id' => true,

        /**
         * Context field name for trace id
         */
        'trace_id_field' => 'traceid',
    ],

    /**
     * OpenTelemetry exporters
     *
     * Here you can configure exports used by traces and logs.
     * If you want to use the same protocol with different endpoints,
     * you can copy the exporter with a different and change the endpoint
     *
     * Supported drivers: "otlp", "zipkin", "console", "null"
     */
    'exporters' => [
        'otlp' => [
            'driver' => 'otlp',
            'endpoint' => env('OTEL_EXPORTER_OTLP_ENDPOINT', 'https://:4318'),
            // Supported: "grpc", "http/protobuf", "http/json"
            'protocol' => env('OTEL_EXPORTER_OTLP_PROTOCOL', 'http/protobuf'),
        ],

        'zipkin' => [
            'driver' => 'zipkin',
            'endpoint' => env('OTEL_EXPORTER_ZIPKIN_ENDPOINT', 'https://:9411'),
        ],
    ],

    /**
     * List of instrumentation used for application tracing
     */
    'instrumentation' => [
        Instrumentation\HttpServerInstrumentation::class => [
            'enabled' => env('OTEL_INSTRUMENTATION_HTTP_SERVER', true),
            'excluded_paths' => [],
            'allowed_headers' => [],
            'sensitive_headers' => [],
        ],

        Instrumentation\HttpClientInstrumentation::class => [
            'enabled' => env('OTEL_INSTRUMENTATION_HTTP_CLIENT', true),
            'allowed_headers' => [],
            'sensitive_headers' => [],
        ],

        Instrumentation\QueryInstrumentation::class => env('OTEL_INSTRUMENTATION_QUERY', true),

        Instrumentation\RedisInstrumentation::class => env('OTEL_INSTRUMENTATION_REDIS', true),

        Instrumentation\QueueInstrumentation::class => env('OTEL_INSTRUMENTATION_QUEUE', true),

        Instrumentation\CacheInstrumentation::class => env('OTEL_INSTRUMENTATION_CACHE', true),

        Instrumentation\EventInstrumentation::class => [
            'enabled' => env('OTEL_INSTRUMENTATION_EVENT', true),
            'ignored' => [],
        ],
    ],
];

跟踪

此包提供了一套集成，可以自动跟踪Laravel应用程序中的常见操作。您可以在配置文件中的instrumentations部分禁用或自定义每个集成。

提供的跟踪集成

HTTP服务器请求
HTTP客户端
数据库
Redis
队列作业
日志上下文
手动跟踪

HTTP服务器请求

HTTP服务器请求通过向全局中间件注入\Keepsuit\LaravelOpenTelemetry\Support\HttpServer\TraceRequestMiddleware::class自动跟踪。您可以通过将OT_INSTRUMENTATION_HTTP_SERVER设置为false或从配置文件中删除HttpServerInstrumentation::class来禁用它。

配置选项

excluded_paths：要排除跟踪的路径列表
allowed_headers：要包含在跟踪中的头列表
sensitive_headers：包含敏感数据的头列表，要在跟踪中隐藏

HTTP客户端

要跟踪出站HTTP请求，请调用请求构建器的withTrace方法。

Http::withTrace()->get('https://example.com');

您可以通过将OT_INSTRUMENTATION_HTTP_CLIENT设置为false或从配置文件中删除HttpClientInstrumentation::class来禁用它。

配置选项

allowed_headers：要包含在跟踪中的头列表
sensitive_headers：包含敏感数据的头列表，要在跟踪中隐藏

数据库

数据库查询自动跟踪。您可以通过将OT_INSTRUMENTATION_QUERY设置为false或从配置文件中删除QueryInstrumentation::class来禁用它。

Redis

Redis命令自动跟踪。您可以通过将OT_INSTRUMENTATION_REDIS设置为false或从配置文件中删除RedisInstrumentation::class来禁用它。

队列作业

队列作业自动跟踪。当作业被调度时，将自动创建一个类型为PRODUCER的父跨度，当作业执行时，将创建一个类型为CONSUMER的子跨度。您可以通过将OT_INSTRUMENTATION_QUEUE设置为false或从配置文件中删除QueueInstrumentation::class来禁用它。

日志上下文

在启动带有提供的集成的跟踪时，跟踪ID会自动注入到日志上下文中。这允许将日志与跟踪相关联。

如果您正在手动启动根跟踪，应调用Tracer::updateLogContext()来在日志上下文中注入跟踪ID。

注意

当使用OpenTelemetry日志驱动程序（otlp）时，无需调用Tracer::updateLogContext()即可自动将跟踪ID注入到日志上下文中。

手动跟踪

可以使用Tracer外观上的newSpan方法手动创建跨度。此方法返回一个SpanBuilder实例，可以用于自定义和启动跨度。

使用measure方法创建自定义跟踪是最简单的方法

use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

Tracer::newSpan('my custom trace')->measure(function () {
    // do something
});

或者您可以手动管理跨度

use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

$span = Tracer::newSpan('my custom trace')->start();

// do something

$span->end();

使用measure，跨度会自动设置为活动状态（因此它将被用作新跨度的作用域）。使用start，您必须手动将跨度设置为活动状态

use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

$span = Tracer::newSpan('my custom trace')->start();
$scope = $span->activate()

// do something

$scope->detach();
$span->end();

Tracer外观上还有其他实用方法

use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

Tracer::traceId(); // get the active trace id
Tracer::activeSpan(); // get the active span
Tracer::activeScope(); // get the active scope
Tracer::currentContext(); // get the current trace context (useful for advanced use cases)
Tracer::propagationHeaders(); // get the propagation headers required to propagate the trace to other services
Tracer::extractContextFromPropagationHeaders(array $headers); // extract the trace context from propagation headers

日志

本包提供了一个自定义日志通道，允许使用 OpenTelemetry 仪表进行日志处理。此包注入了一个名为 otlp 的日志通道，可用于使用 Laravel 默认日志系统将日志发送到 OpenTelemetry。

// config/logging.php
'channels' => [
    // injected channel config, you can override it adding an `otlp` channel in your config
    'otlp' => [
        'driver' => 'monolog',
        'handler' => \Keepsuit\LaravelOpenTelemetry\Support\OpenTelemetryMonologHandler::class,
        'level' => 'debug',
    ]
]

作为替代，您可以使用 Logger 门面直接将日志发送到 OpenTelemetry

use Keepsuit\LaravelOpenTelemetry\Facades\Logger;

Logger::emergency('my log message');
Logger::alert('my log message');
Logger::critical('my log message');
Logger::error('my log message');
Logger::warning('my log message');
Logger::notice('my log message');
Logger::info('my log message');
Logger::debug('my log message');

测试

composer test

keepsuit/laravel-opentelemetry

维护者

详细信息