Laravel OpenTelemetry

https://github.com/keepsuit/laravel-opentelemetry
Admin
Laravel OpenTelemetry is a package that integrates OpenTelemetry instrumentation into Laravel...
Tokens:89,297
Snippets:646
Trust Score:8
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Example usage of all four facades

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Facades.md

Shows how to use the OpenTelemetry, Tracer, Meter, and Logger facades in a typical workflow: getting the tracer, starting a span, incrementing a counter, logging an info message, and flushing the OpenTelemetry instance.

```php
use Keepsuit\LaravelOpenTelemetry\Facades\OpenTelemetry;
use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;
use Keepsuit\LaravelOpenTelemetry\Facades\Meter;
use Keepsuit\LaravelOpenTelemetry\Facades\Logger;

$otel = OpenTelemetry::tracer();           // same as app(Tracer::class)
$span = Tracer::newSpan('job')->start();
Meter::counter('processed', 'times')->add(1);
Logger::info('done');

OpenTelemetry::flush();
```

--------------------------------

### commandStarting method signature

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/ApplicationInstrumentation.md

Starts a span for a command when it starts, if it should be recorded. The span is named after the command and includes attributes for the command name and its arguments/options.

```php
public function commandStarting(CommandStarting $event): void
{
    if (! $event->command) {
        return;
    }

    if (! $this->shouldRecord($event->command)) {
        return;
    }

    $span = Tracer::newSpan($event->command)
        ->setAttribute('console.command', $event->command)
        ->start();

    $this->recordCommandArguments($span, $event->input);

    $scope = $span->activate();

    $this->startedCommands[$event->input] = [$span, $scope];
}
```

--------------------------------

### Install package with Composer

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/README.md

Run this command to install the keepsuit/laravel-opentelemetry package via Composer.

```bash
composer require keepsuit/laravel-opentelemetry
```

--------------------------------

### Basic logging at all levels

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Logger.md

Example of using the Logger facade to log info, warning, and error messages with context attributes.

```php
use Keepsuit\LaravelOpenTelemetry\Facades\Logger;

Logger::info('order created', ['order_id' => 1234]);
Logger::warning('stock running low', ['sku' => 'A-100', 'remaining' => 3]);
Logger::error('payment failed', ['charge_id' => 'ch_abc', 'reason' => 'card_declined']);
```

--------------------------------

### start method signature

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/SpanBuilder.md

Starts the span. The span is not automatically activated; call $span->activate() to make it the active span.

```php
public function start(): SpanInterface
```

--------------------------------

### start(): SpanInterface

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/SpanBuilder.md

Starts the span. The span is not automatically activated; call `$span->activate()` to make it the active span.

```APIDOC
## start(): SpanInterface

### Description
Starts the span (`$this->spanBuilder->startSpan()`). The span is **not** automatically activated; call `$span->activate()` to make it the active span.

### Method
start

### Parameters
None

### Return Type
`OpenTelemetry\API\Trace\SpanInterface` - the started span.
```

--------------------------------

### TailSamplingProcessor::onStart

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/TailSampling.md

Called when a span starts. This method is a no-op.

```APIDOC
## TailSamplingProcessor::onStart

### Description
Called when a span starts. This method is a no-op.

### Method
onStart

### Signature
```php
public function onStart(ReadWriteSpanInterface $span, ContextInterface $parentContext): void
```

### Parameters
- **$span** (ReadWriteSpanInterface) - Required - The span that started.
- **$parentContext** (ContextInterface) - Required - The parent context.

### Return Value
void
```

--------------------------------

### Tracer::newSpan()->start() with activate() and detach()

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/README.md

Manually start a span, activate it to set it as the active span, and detach the scope when done.

```APIDOC
## Tracer::newSpan()->start() with activate() and detach()

### Description
Manually start a span, activate it to set it as the active span, and detach the scope when done.

### Method
- `start()`
- `activate()`
- `detach()`
- `end()`

### Parameters
None.

### Request Example
```php
use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

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

// do something

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

### Response
No return value specified.
```

--------------------------------

### Custom instrumentation example - OrderInstrumentation

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Instrumentation.md

Shows how to implement the Instrumentation interface to listen for an OrderPlaced event and add an event to the active span. Uses the Tracer facade.

```php
use Keepsuit\LaravelOpenTelemetry\Instrumentation\Instrumentation;
use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

class OrderInstrumentation implements Instrumentation
{
    public function register(array $options): void
    {
        app('events')->listen(OrderPlaced::class, function (OrderPlaced $event) {
            Tracer::activeSpan()->addEvent('order placed', [
                'order.id' => $event->orderId,
            ]);
        });
    }
}
```

--------------------------------

### commandStarting(CommandStarting $event): void

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/ApplicationInstrumentation.md

Starts a span for a whitelisted command when it begins execution. Records the command name and its input arguments and options as span attributes.

```APIDOC
## commandStarting(CommandStarting $event): void

### Description
Starts a span for a whitelisted command when it begins execution. Records the command name and its input arguments and options as span attributes.

### Method
commandStarting

### Signature
```php
public function commandStarting(CommandStarting $event): void
```

### Parameters
- **$event** (CommandStarting) - Required - The event object containing the command name and input.

### Return Type
void

### Behavior
If the command is not whitelisted, no span is created. Otherwise, a span is started with attribute `console.command` set to the command name, plus `console.argument.<key>` for each input argument (excluding the `command` argument) and `console.option.<key>` for each non-`false` input option.
```

--------------------------------

### Configure HttpServerInstrumentation in config/opentelemetry.php

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/HttpServerInstrumentation.md

Example configuration for the HTTP server instrumentation. Set `enabled` to true, and optionally exclude paths, methods, and configure allowed/sensitive headers and sensitive query parameters.

```php
// config/opentelemetry.php
'instrumentation' => [
    Instrumentation\HttpServerInstrumentation::class => [
        'enabled' => true,
        'excluded_paths' => ['health', 'metrics'],
        'excluded_methods' => ['OPTIONS'],
        'allowed_headers' => ['x-request-id', 'x-api-version'],
        'sensitive_headers' => ['authorization'],
        'sensitive_query_parameters' => ['token', 'password'],
    ],
],
```

--------------------------------

### Tracer facade

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Facades.md

Provides methods for tracing operations, including starting spans, getting trace IDs, and managing context.

```APIDOC
## Tracer facade

### Description
Provides methods for tracing operations, including starting spans, getting trace IDs, and managing context.

### Methods
- `traceStarted()`: bool
- `traceId()`: string|null
- `activeSpan()`: SpanInterface
- `activeScope()`: ScopeInterface|null
- `currentContext()`: ContextInterface
- `propagationHeaders(?ContextInterface $context = null)`: array
- `extractContextFromPropagationHeaders(array $headers)`: Context|null (actual implementation returns ContextInterface)
- `newSpan(string $name)`: SpanBuilder
- `updateLogContext()`: void
- `terminateActiveSpansUpToRoot(?SpanInterface $root = null)`: void
```

--------------------------------

### Before v1.x: batchObserve() with callback first

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/UPGRADE.md

In v1.x, batchObserve() accepted the callback as the first parameter and the instruments as subsequent parameters. This example shows the old signature.

```php
Meter::batchObserve(
    function(
        ObserverInterface $usageObserver,
        ObserverInterface $pressureObserver,
    ): void {
        [$usage, $pressure] = expensive_system_call();
        $usageObserver->observe($usage);
        $pressureObserver->observe($pressure);
    },
    Meter::createObservableCounter('usage', description: 'count of items used'),
    Meter::createObservableGauge('pressure', description: 'force per unit area'),
);
```

--------------------------------

### Create and use metric instruments with Meter facade

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/README.md

Example usage of the Meter facade to create or retrieve counter, histogram, and gauge instruments, record measurements with attributes, and use batchObserve with observable instruments. Instruments are cached by name to prevent duplicate creation.

```php
use Keepsuit\LaravelOpenTelemetry\Facades\Meter;

// create or retrieve a counter instrument
$counter = Meter::counter('my-meter', 'times', 'my custom meter');
$counter->add(1);

// create or retrieve a histogram instrument
$histogram = Meter::histogram('my-histogram', 'ms', 'my custom histogram');
$histogram->record(100, ['name' => 'value', 'app' => 'my-app']);

// create or retrieve a gauge instrument
$gauge = Meter::gauge('my-gauge', null, 'my custom gauge');
$gauge->record(100, ['name' => 'value', 'app' => 'my-app']);
$gauge->record(1.2, ['name' => 'percentage', 'app' => 'my-app']);

// Execute the callback with multiple observable instruments
Meter::batchObserve([
    Meter::observableCounter('usage', description: 'count of items used'),
    Meter::observableGauge('pressure', description: 'force per unit area'),
], function(ObserverInterface $usageObserver, ObserverInterface $pressureObserver): void {
    [$usage, $pressure] = expensive_system_call();
    $usageObserver->observe($usage);
    $pressureObserver->observe($pressure);
});
```

--------------------------------

### newSpan() method signature

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Tracer.md

Creates a new SpanBuilder wrapping $this->tracer->spanBuilder($name). The span is not started until you call start() or measure() on the builder.

```php
/**
 * @phpstan-param non-empty-string $name
 */
public function newSpan(string $name): SpanBuilder
```

--------------------------------

### LivewireInstrumentation::register(array $options): void

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/ApplicationInstrumentation.md

Registers the Livewire instrumentation by listening to mount, hydrate, and dehydrate events to trace component rendering. No-op if Livewire is not installed.

```APIDOC
## LivewireInstrumentation::register

### Description
Registers the Livewire instrumentation by listening to the Livewire 'mount' and 'hydrate' events to start a span per component, and 'dehydrate' to end it. No-op when Livewire\LivewireManager does not exist.

### Method
register

### Signature
```php
public function register(array $options): void
```

### Parameters
- **$options** (array) - Required - Accepted but unused.

### Return Type
void

```

--------------------------------

### Tracer::newSpan()->start() and $span->end()

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/README.md

Manually start and end a span. The span is not automatically activated; you must call activate() to set it as the active span.

```APIDOC
## Tracer::newSpan()->start() and $span->end()

### Description
Manually start and end a span. The span is not automatically activated; you must call activate() to set it as the active span.

### Method
- `start()`
- `end()`

### Parameters
None.

### Request Example
```php
use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

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

// do something

$span->end();
```

### Response
No return value specified.
```

--------------------------------

### Before v1.x: Creating an observable counter with callback

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/UPGRADE.md

In v1.x, observable counter methods accepted a callable parameter directly. This example shows the old syntax for creating an observable counter with a callback that observes a value.

```php
Meter::createObservableCounter('cache.hits', 'Cache hits', function(ObserverInterface $observer): void {
    $observer->observe(123);
});
```

--------------------------------

### Manually activate a span with scope

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/README.md

When using start, you must manually activate the span with activate() to set it as the active span. Detach the scope before ending the span.

```php
use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

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

// do something

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

--------------------------------

### Meter::gauge()

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Meter.md

Creates a gauge instrument for recording current values. The example shows creating a gauge and recording a value of 3.5.

```APIDOC
## Meter::gauge()

### Description
Creates a gauge instrument for recording a value that can go up and down. The gauge can be updated using the `record` method.

### Method
`Meter::gauge`

### Parameters
- **name** (string) - Required - The name of the gauge instrument.
- **unit** (string|null) - Optional - The unit of measurement (e.g., null).
- **description** (string|null) - Optional - A description of the gauge.

### Usage Example
```php
use Keepsuit\LaravelOpenTelemetry\Facades\Meter;

$gauge = Meter::gauge('my-gauge', null, 'my custom gauge');
$gauge->record(3.5);
```

### Return Value
Returns a gauge instrument object with a `record` method.
```

--------------------------------

### Meter::histogram()

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Meter.md

Creates a histogram instrument for recording measurements. The example shows creating a histogram with explicit bucket boundaries and recording a value with attributes.

```APIDOC
## Meter::histogram()

### Description
Creates a histogram instrument for recording statistical distributions of values. The histogram can be configured with explicit bucket boundaries.

### Method
`Meter::histogram`

### Parameters
- **name** (string) - Required - The name of the histogram instrument.
- **unit** (string|null) - Optional - The unit of measurement (e.g., 'ms').
- **description** (string|null) - Optional - A description of the histogram.
- **advisory** (array|null) - Optional - An array of advisory parameters, e.g., `['ExplicitBucketBoundaries' => [10, 50, 100, 500, 1000]]`.

### Usage Example
```php
use Keepsuit\LaravelOpenTelemetry\Facades\Meter;

$histogram = Meter::histogram('my-histogram', 'ms', 'my custom histogram', [
    'ExplicitBucketBoundaries' => [10, 50, 100, 500, 1000],
]);
$histogram->record(120, ['route' => '/products']);
```

### Return Value
Returns a histogram instrument object with a `record` method.
```

--------------------------------

### registerInstrumentation method

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/ServiceProviders.md

Registers the InstrumentationServiceProvider and installs a reportable hook that records exceptions on the active span with STATUS_ERROR. No-op when the SDK is disabled.

```php
protected function registerInstrumentation(): void
{
    if (Sdk::isDisabled()) {
        return;
    }

    $this->app->register(InstrumentationServiceProvider::class);

    $this->callAfterResolving(ExceptionHandlerContract::class, function (ExceptionHandlerContract $handler) {
        if (! method_exists($handler, 'reportable')) {
            return;
        }

        $handler->reportable(function (Throwable $e) {
            Facades\Tracer::activeSpan()
                ->recordException($e)
                ->setStatus(StatusCode::STATUS_ERROR);
        });
    });
}
```

--------------------------------

### Meter::counter()

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Meter.md

Creates a counter instrument that can be incremented by adding values. The example shows creating a counter and adding a value of 1.

```APIDOC
## Meter::counter()

### Description
Creates a counter instrument for recording additive values. The counter can be incremented using the `add` method.

### Method
`Meter::counter`

### Parameters
- **name** (string) - Required - The name of the counter instrument.
- **unit** (string|null) - Optional - The unit of measurement (e.g., 'times').
- **description** (string|null) - Optional - A description of the counter.

### Usage Example
```php
use Keepsuit\LaravelOpenTelemetry\Facades\Meter;

$counter = Meter::counter('my-meter', 'times', 'my custom meter');
$counter->add(1);
```

### Return Value
Returns a counter instrument object with an `add` method.
```

--------------------------------

### measure() method signature

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/SpanBuilder.md

The full implementation of measure(). It starts a span, activates a scope, runs the callback, records and rethrows exceptions, and always ends the span. If the callback returns a PendingDispatch, null is returned instead.

```php
/**
 * @template U
 *
 * @param  Closure(SpanInterface $span): U  $callback
 * @return (U is PendingDispatch ? null : U)
 *
 * @throws Throwable
 */
public function measure(Closure $callback): mixed
{
    $span = $this->start();
    $scope = $span->activate();

    try {
        $result = $callback($span);

        // Fix: Dispatch is effective only on destruct
        if ($result instanceof PendingDispatch) {
            $result = null;
        }

        return $result;
    } catch (Throwable $exception) {
        $span->recordException($exception);

        throw $exception;
    } finally {
        $scope->detach();
        $span->end();
    }
}
```

--------------------------------

### Measure a block of work with automatic exception recording

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Tracer.md

Use Tracer::newSpan() to create a span and measure a closure. Exceptions thrown inside the closure are automatically recorded on the span. The span is started and ended automatically by the measure() method.

```php
use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

$result = Tracer::newSpan('import users')
    ->setAttribute('source', 'csv')
    ->measure(function () {
        // runs inside an active span; exceptions are recorded on the span
        return importUsersFromCsv();
    });
```

--------------------------------

### packageBooted method

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/ServiceProviders.md

Initializes the OTel SDK, boots singletons, and registers instrumentation. Called after package registration.

```php
public function packageBooted(): void
{
    $this->initOtelSdk();
    $this->bootSingletons();
    $this->registerInstrumentation();
}
```

--------------------------------

### boot() method implementation

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/ServiceProviders.md

Iterates over the opentelemetry.instrumentation config, skipping entries set to false or disabled arrays, resolves each instrumentation class, and calls register() with the array options or an empty array for plain true entries.

```php
public function boot(): void
{
    foreach (config('opentelemetry.instrumentation') as $key => $options) {
        if ($options === false) {
            continue;
        }

        if (is_array($options) && ! ($options['enabled'] ?? true)) {
            continue;
        }

        $instrumentation = $this->app->make($key);

        if ($instrumentation instanceof Instrumentation) {
            $instrumentation->register(is_array($options) ? $options : []);
        }
    }
}
```

--------------------------------

### Tracer facade class with @method annotations

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Facades.md

Defines the Tracer facade that proxies to the Tracer service. It declares static methods for tracing operations, including starting spans, getting trace IDs, and extracting context from propagation headers. Note: the actual implementation of extractContextFromPropagationHeaders() returns OpenTelemetry\Context\ContextInterface, not Context|null as the annotation suggests.

```php
/**
 * @method static bool traceStarted()
 * @method static string|null traceId()
 * @method static SpanInterface activeSpan()
 * @method static ScopeInterface|null activeScope()
 * @method static ContextInterface currentContext()
 * @method static array propagationHeaders(?ContextInterface $context = null)
 * @method static Context|null extractContextFromPropagationHeaders(array $headers)
 * @method static SpanBuilder newSpan(string $name)
 * @method static void updateLogContext()
 * @method static void terminateActiveSpansUpToRoot(?SpanInterface $root = null)
 */
class Tracer extends Facade
```

--------------------------------

### initOtelSdk method

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/ServiceProviders.md

Sets up the OpenTelemetry SDK: clock, resource, propagator, providers, global registration, and instrumentation bindings.

```php
protected function initOtelSdk(): void
{
    Clock::setDefault(new CarbonClock);

    $resource = ResourceBuilder::build();

    $propagator = match (Sdk::isDisabled()) {
        true => new NoopTextMapPropagator,
        false => PropagatorBuilder::new()->build(config('opentelemetry.propagators'))
    };

    $meterProvider = $this->buildMeterProvider($resource);
    $tracerProvider = $this->buildTracerProvider($resource, meterProvider: $meterProvider);
    $loggerProvider = $this->buildLoggerProvider($resource, meterProvider: $meterProvider);

    Sdk::builder()
        ->setTracerProvider($tracerProvider)
        ->setLoggerProvider($loggerProvider)
        ->setMeterProvider($meterProvider)
        ->setPropagator($propagator)
        ->setAutoShutdown(true)
        ->buildAndRegisterGlobal();

    $instrumentation = new CachedInstrumentation(
        name: 'laravel-opentelemetry',
        version: class_exists(InstalledVersions::class) ? InstalledVersions::getPrettyVersion('keepsuit/laravel-opentelemetry') : null,
        schemaUrl: Version::VERSION_1_38_0->url(),
    );

    $this->app->singleton(TextMapPropagatorInterface::class, fn () => $propagator);
    $this->app->singleton(MeterInterface::class, fn () => $instrumentation->meter());
    $this->app->singleton(TracerInterface::class, fn () => $instrumentation->tracer());
    $this->app->singleton(LoggerInterface::class, fn () => $instrumentation->logger());
}
```

--------------------------------

### register() method implementation

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/HttpServerInstrumentation.md

Registers the instrumentation: reads options, sets boot timestamp on app boot, and injects middleware. Paths are normalized (leading slash stripped except for '/'), methods uppercased, headers/query params lowercased.

```php
public function register(array $options): void
{
    static::$excludedPaths = array_map(
        fn (string $path) => $path === '/' ? '/' : ltrim($path, '/'),
        Arr::get($options, 'excluded_paths', []),
    );

    static::$excludedMethods = array_map(
        fn (string $method) => strtoupper($method),
        Arr::get($options, 'excluded_methods', []),
    );

    static::$allowedHeaders = $this->normalizeHeaders(Arr::get($options, 'allowed_headers', []));

    static::$sensitiveQueryParameters = array_merge(
        $this->normalizeQueryParameters(Arr::get($options, 'sensitive_query_parameters', [])),
        $this->defaultSensitiveQueryParams
    );

    static::$sensitiveHeaders = array_merge(
        $this->normalizeHeaders(Arr::get($options, 'sensitive_headers', [])),
        $this->defaultSensitiveHeaders,
    );

    static::$bootedTimestamp = null;
    app()->booted(function () {
        static::$bootedTimestamp = Clock::getDefault()->now();
    });

    $this->injectMiddleware(app(HttpKernelContract::class));
}
```

--------------------------------

### Manual lifecycle with custom start time and error handling

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/SpanBuilder.md

Shows manual span lifecycle: start with a custom start time, activate scope, run work, set status, record exceptions, and always detach and end in a finally block.

```php
use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;
use OpenTelemetry\API\Trace\SpanKind;

$span = Tracer::newSpan('sync products')
    ->setSpanKind(SpanKind::KIND_CLIENT)
    ->setStartTimestamp(now()->subSecond())
    ->start();

$scope = $span->activate();

try {
    syncProducts();
    $span->setStatus(\OpenTelemetry\API\Trace\StatusCode::STATUS_OK);
} catch (Throwable $e) {
    $span->recordException($e)
        ->setStatus(\OpenTelemetry\API\Trace\StatusCode::STATUS_ERROR);
} finally {
    $scope->detach();
    $span->end();
}
```

--------------------------------

### Create and use synchronous instruments (counter, histogram, gauge)

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Meter.md

Shows how to create a counter, histogram with explicit bucket boundaries, and gauge, and record values. The histogram records a value with attributes.

```php
use Keepsuit\LaravelOpenTelemetry\Facades\Meter;

$counter = Meter::counter('my-meter', 'times', 'my custom meter');
$counter->add(1);

$histogram = Meter::histogram('my-histogram', 'ms', 'my custom histogram', [
    'ExplicitBucketBoundaries' => [10, 50, 100, 500, 1000],
]);
$histogram->record(120, ['route' => '/products']);

$gauge = Meter::gauge('my-gauge', null, 'my custom gauge');
$gauge->record(3.5);
```

--------------------------------

### newSpan(string $name): SpanBuilder

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Tracer.md

Creates a new SpanBuilder wrapping the tracer's spanBuilder. The span is not started until you call start() or measure() on the builder.

```APIDOC
## newSpan(string $name): SpanBuilder

### Description
Creates a new `SpanBuilder` wrapping `$this->tracer->spanBuilder($name)`. The span is **not** started until you call `start()` or `measure()` on the builder.

### Method
`newSpan`

### Signature
```php
public function newSpan(string $name): SpanBuilder
```

### Parameters
- **$name** (`non-empty-string`) - Required - Span name

### Return Type
`Keepsuit\LaravelOpenTelemetry\Support\SpanBuilder`
```

--------------------------------

### packageRegistered method

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/ServiceProviders.md

Registers core services as singletons and calls helper methods to configure environment variables, inject config, and initialize worker mode manager.

```php
public function packageRegistered(): void
{
    $this->app->singleton(Meter::class);
    $this->app->singleton(Tracer::class);
    $this->app->singleton(Logger::class);
    $this->app->singleton(OpenTelemetry::class);
    $this->app->singleton(UserContextResolver::class);

    $this->configureEnvironmentVariables();
    $this->injectConfig();
    $this->initWorkerModeManager();
}
```

--------------------------------

### Manually start and end a span

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/README.md

Create a span manually with start and end. The span is not automatically activated, so it will not be used as parent for new spans unless activated.

```php
use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

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

// do something

$span->end();
```

--------------------------------

### SamplerBuilder class with build method

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Support.md

Builds a sampler from the 'traces.sampler' config. The build method lowercases and trims the sampler name, then maps 'always_on' to AlwaysOnSampler, 'traceidratio' to TraceIdRatioBasedSampler with a ratio from args (default 0.05), and anything else to AlwaysOffSampler. If parentBased is true, the result is wrapped in ParentBased.

```php
final class SamplerBuilder
{
    public static function new(): SamplerBuilder

    public function build(string $sampler, bool $parentBased = false, array $args = []): SamplerInterface
    {
        $instance = $this->buildSampler(strtolower(trim($sampler)), $args);

        if ($parentBased) {
            return new ParentBased($instance);
        }

        return $instance;
    }
}
```

--------------------------------

### Custom worker mode detector example

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/WorkerMode.md

Example implementation of WorkerModeDetectorInterface for RoadRunner. Detects RoadRunner environment via $_SERVER variables and registers a callback on MyWorkerLoopIteration event. Register this class in opentelemetry.worker_mode.detectors.

```php
use Closure;
use Keepsuit\LaravelOpenTelemetry\WorkerMode\WorkerModeDetectorInterface;

class RoadRunnerWorkerModeDetector implements WorkerModeDetectorInterface
{
    public function detect(): bool
    {
        return isset($_SERVER['RR_HTTP']) || isset($_SERVER['RR_WORKER']);
    }

    public function onIterationEnded(Closure $callback): void
    {
        app('events')->listen(MyWorkerLoopIteration::class, $callback);
    }
}
```

--------------------------------

### Tracer::activeScope()

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/README.md

Gets the active scope.

```APIDOC
## Tracer::activeScope()

### Description
Gets the active scope.

### Method
- `activeScope()`

### Parameters
None.

### Request Example
```php
use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

$scope = Tracer::activeScope();
```

### Response
Returns the active scope.
```

--------------------------------

### Static accessors for excluded paths, methods, and boot timestamp

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/HttpServerInstrumentation.md

Provides static methods to retrieve the currently excluded paths, excluded methods, and the boot timestamp. The boot timestamp is in nanoseconds and is null before the app boots.

```php
public static function getExcludedPaths(): array   // line 17
public static function getExcludedMethods(): array // line 23
public static function getBootedTimestamp(): ?int  // line 29
```

--------------------------------

### Tracer::activeSpan()

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/README.md

Gets the active span.

```APIDOC
## Tracer::activeSpan()

### Description
Gets the active span.

### Method
- `activeSpan()`

### Parameters
None.

### Request Example
```php
use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

$span = Tracer::activeSpan();
```

### Response
Returns the active span.
```

--------------------------------

### Tracer::traceId()

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/README.md

Gets the active trace ID.

```APIDOC
## Tracer::traceId()

### Description
Gets the active trace ID.

### Method
- `traceId()`

### Parameters
None.

### Request Example
```php
use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

$traceId = Tracer::traceId();
```

### Response
Returns the active trace ID.
```

--------------------------------

### Configure Console Instrumentation by Command Class Name

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/README.md

Adds a console command to the 'commands' option of ConsoleInstrumentation using its class name ExampleCommand::class. The 'enabled' option is controlled by the OTEL_INSTRUMENTATION_CONSOLE environment variable, defaulting to true.

```php
use Keepsuit\LaravelOpenTelemetry\Instrumentation;
use App\Console\Commands\ExampleCommand;

return [
    // ...
    
    /**
     * List of instrumentation used for application tracing
     */
    'instrumentation' => [
        // ...
        
        Instrumentation\ConsoleInstrumentation::class => [
            'enabled' => env('OTEL_INSTRUMENTATION_CONSOLE', true),
            'commands' => [
                ExampleCommand::class,
             ],
        ],
        
        // ...
    ],
    
    // ...
];
```

--------------------------------

### Constructor

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Meter.md

Creates a new Meter instance with the underlying SDK meter and metric reader.

```APIDOC
## Constructor

### Description
Creates a new Meter instance with the underlying SDK meter and metric reader.

### Signature
```php
public function __construct(
    protected MeterInterface $meter,
    protected MetricReaderInterface $reader
) {}
```

### Parameters
- `$meter` (OpenTelemetry\API\Metrics\MeterInterface) - Required - Underlying SDK meter
- `$reader` (OpenTelemetry\SDK\Metrics\MetricReaderInterface) - Required - Metric reader (an ExportingReader built by the service provider)
```

--------------------------------

### measure(Closure $callback): mixed

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/SpanBuilder.md

Starts a span, activates it for the duration of the callback, records any thrown exception on the span, rethrows it, and always ends the span and detaches the scope. The callback receives the started SpanInterface. If the callback returns a PendingDispatch, null is returned instead.

```APIDOC
## measure(Closure $callback): mixed

### Description
Starts a span, activates it for the duration of the callback, records any thrown exception on the span, rethrows it, and always ends the span and detaches the scope. The callback receives the started SpanInterface. If the callback returns a PendingDispatch, null is returned instead.

### Method
measure

### Signature
```php
public function measure(Closure $callback): mixed
```

### Parameters
- **$callback** (Closure(SpanInterface $span): U) - Required - Work to measure inside an active span

### Return Type
mixed - The callback result (or null for PendingDispatch).

### Throws
Rethrows Throwable after recording it on the span.

### Example
```php
use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

$result = Tracer::newSpan('render report')
    ->setAttribute('report.id', 42)
    ->measure(function ($span) {
        // $span is the active span
        return generateReport();
    });
```
```

--------------------------------

### Tracer::propagationHeaders()

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/README.md

Gets the propagation headers required to propagate the trace to other services.

```APIDOC
## Tracer::propagationHeaders()

### Description
Gets the propagation headers required to propagate the trace to other services.

### Method
- `propagationHeaders()`

### Parameters
None.

### Request Example
```php
use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

$headers = Tracer::propagationHeaders();
```

### Response
Returns an array of propagation headers.
```

--------------------------------

### register(array $options): void

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/HttpServerInstrumentation.md

Registers the HTTP server instrumentation by reading configuration options, recording boot timestamp, and injecting tracing middleware into the HTTP kernel.

```APIDOC
## register(array $options): void

### Description
Registers the HTTP server instrumentation. Reads options for excluded paths, excluded methods, allowed headers, sensitive headers, and sensitive query parameters. Records the application boot timestamp and prepends the tracing middleware to the HTTP kernel global middleware.

### Method
register

### Signature
```php
public function register(array $options): void
```

### Parameters
- **$options** (array) - Required - Options: `excluded_paths` (string[]), `excluded_methods` (string[]), `allowed_headers` (string[]), `sensitive_headers` (string[]), `sensitive_query_parameters` (string[])

### Return Type
void

### Behavior
- Paths are normalized by stripping a leading `/` (except `'/'`).
- Methods are uppercased.
- Headers and query parameters are lowercased.
- Records boot timestamp once the app is booted.
- Prepends `TraceRequestMiddleware::class` to the HTTP kernel global middleware (only when the kernel is an `Illuminate\Foundation\Http\Kernel`).
```

--------------------------------

### Tracer::currentContext()

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/README.md

Gets the current trace context, useful for advanced use cases.

```APIDOC
## Tracer::currentContext()

### Description
Gets the current trace context, useful for advanced use cases.

### Method
- `currentContext()`

### Parameters
None.

### Request Example
```php
use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

$context = Tracer::currentContext();
```

### Response
Returns the current trace context.
```

--------------------------------

### Configure Console Instrumentation by Command Signature

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/README.md

Adds a console command to the 'commands' option of ConsoleInstrumentation using its signature 'app:example-command'. The 'enabled' option is controlled by the OTEL_INSTRUMENTATION_CONSOLE environment variable, defaulting to true.

```php
use Keepsuit\LaravelOpenTelemetry\Instrumentation;

return [
    // ...
    
    /**
     * List of instrumentation used for application tracing
     */
    'instrumentation' => [
        // ...
        
        Instrumentation\ConsoleInstrumentation::class => [
            'enabled' => env('OTEL_INSTRUMENTATION_CONSOLE', true),
            'commands' => [
                'app:example-command',
             ],
        ],
        
        // ...
    ],
    
    // ...
];
```

--------------------------------

### Using context attributes and the generic log() method

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Logger.md

Shows the generic log() method with a CRITICAL level and demonstrates that context values become attributes on the exported log record.

```php
use Keepsuit\LaravelOpenTelemetry\Facades\Logger;
use Psr\Log\LogLevel;

Logger::log(LogLevel::CRITICAL, 'out of disk space', ['device' => '/dev/sda1']);

// context values become attributes on the exported log record:
Logger::info('job processed', ['job' => 'ReportsJob', 'duration_ms' => 412]);
```

--------------------------------

### Constructor with TracerInterface and TextMapPropagatorInterface

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Tracer.md

The constructor accepts the underlying OpenTelemetry tracer and the configured propagator. It is built by the service provider from SDK-initialized singletons; do not construct manually.

```php
public function __construct(
    protected TracerInterface $tracer,
    protected TextMapPropagatorInterface $propagator
) {}
```

--------------------------------

### Unified OpenTelemetry Facade Usage

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/UPGRADE.md

Shows how to access the tracer, meter, and logger through the unified OpenTelemetry facade. The old facades (Tracer, Meter, Logger) still work.

```php
use Keepsuit\LaravelOpenTelemetry\Facades\OpenTelemetry;

// Access the tracer
OpenTelemetry::tracer();

// Access the meter
OpenTelemetry::meter();

// Access the logger
OpenTelemetry::logger();
```

--------------------------------

### setStartTimestamp(CarbonInterface|int $timestamp): SpanBuilder

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/SpanBuilder.md

Sets the span start timestamp. Accepts a Carbon instance (converted to nanoseconds) or an integer nanosecond timestamp.

```APIDOC
## setStartTimestamp(CarbonInterface|int $timestamp): SpanBuilder

### Description
Sets the span start timestamp. Accepts a Carbon instance (converted to nanoseconds via `CarbonClock::carbonToNanos()`) or an integer nanosecond timestamp.

### Method
setStartTimestamp

### Parameters
- **$timestamp** (`CarbonInterface|int`) - Required - Carbon instance, or nanoseconds since epoch

### Return Type
`SpanBuilder` (fluent)
```

--------------------------------

### SpanProcessorInterface methods signatures

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/TailSampling.md

Shows the method signatures for onStart, onEnd, forceFlush, and shutdown. onStart is a no-op, while onEnd buffers spans and evaluates the trace when the root span ends or the buffer age reaches decisionWait. forceFlush and shutdown evaluate and flush pending buffers then delegate to the downstream processor.

```php
public function onStart(ReadWriteSpanInterface $span, ContextInterface $parentContext): void {}
public function onEnd(ReadableSpanInterface $span): void
public function forceFlush(?CancellationInterface $cancellation = null): bool
public function shutdown(?CancellationInterface $cancellation = null): bool
```

--------------------------------

### getEventStartTimestampNs in SpanTimeAdapter

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Support.md

Converts a duration in milliseconds to a nanosecond start timestamp by subtracting the duration from the current time. Used for Laravel query and Redis events.

```php
trait SpanTimeAdapter
{
    protected function getEventStartTimestampNs(float $timeMs): int
    {
        $nowNs = Clock::getDefault()->now();
        $durationNs = (int) ($timeMs * ClockInterface::NANOS_PER_MILLISECOND);

        return $nowNs - $durationNs;
    }
}
```

--------------------------------

### Tracer::newSpan()->measure()

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/README.md

Creates a new span and automatically starts and ends it around the given closure. The span is set as active during the closure execution.

```APIDOC
## Tracer::newSpan()->measure()

### Description
Creates a new span and automatically starts and ends it around the given closure. The span is set as active during the closure execution.

### Method
- `measure(callable $callback)`

### Parameters
- **callback** (callable) - Required - The closure to execute within the span.

### Request Example
```php
use Keepsuit\LaravelOpenTelemetry\Facades\Tracer;

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

### Response
No return value specified.
```

--------------------------------

### register(array $options): void

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/ApplicationInstrumentation.md

Registers the instrumentation by listening to console command events. Accepts an array of command signatures, class names, or wildcards to whitelist commands for tracing.

```APIDOC
## register(array $options): void

### Description
Registers the instrumentation by listening to console command events. Accepts an array of command signatures, class names, or wildcards to whitelist commands for tracing.

### Method
register

### Signature
```php
public function register(array $options): void
```

### Parameters
- **$options** (array) - Required - Options: `commands` (string[], command signatures, class names, or `*`-suffixed wildcards)

### Return Type
void

### Behavior
Class names are resolved to their command name via `app($command)->getName()`. Entries ending in `*` are treated as wildcards (prefix match).
```

--------------------------------

### SamplerBuilder::new()

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/Support.md

Static factory method that returns a new SamplerBuilder instance.

```APIDOC
## SamplerBuilder::new()

### Description
Static factory method that returns a new SamplerBuilder instance.

### Method
new()

### Parameters
None

### Return
- **SamplerBuilder** - A new SamplerBuilder instance.

### Example
```php
$builder = SamplerBuilder::new();
```
```

--------------------------------

### Implement TailSamplingRuleInterface for custom tail sampling rule

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/README.md

Create a custom tail sampling rule by implementing TailSamplingRuleInterface. The initialize method receives options from config, and evaluate returns SamplingResult::Keep, Drop, or Forward to control trace sampling.

```php
use Keepsuit\LaravelOpenTelemetry\TailSampling\TailSamplingRuleInterface;
use Keepsuit\LaravelOpenTelemetry\TailSampling\SamplingResult;
use Keepsuit\LaravelOpenTelemetry\TailSampling\TraceBuffer;

class MyCustomRule implements TailSamplingRuleInterface
{
    public function initialize(array $options): void
    {
        // Configure the rule using options from config
    }

    public function evaluate(TraceBuffer $trace): SamplingResult
    {
        // Evaluate the trace and return a SamplingResult
        // Return SamplingResult::Keep to keep the trace
        // Return SamplingResult::Drop to drop the trace
        // Return SamplingResult::Forward to let the next rule decide
    }
}
```

--------------------------------

### After v2.0: batchObserve() with instruments array first

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/UPGRADE.md

In v2.0, batchObserve() now takes the instruments array as the first parameter and the callback as the second. This example shows the new signature.

```php
Meter::batchObserve(
    [
        Meter::observableCounter('usage', description: 'count of items used'),
        Meter::observableGauge('pressure', description: 'force per unit area'),
    ],
    function(
        ObserverInterface $usageObserver,
        ObserverInterface $pressureObserver,
    ): void {
        [$usage, $pressure] = expensive_system_call();
        $usageObserver->observe($usage);
        $pressureObserver->observe($pressure);
    }
);
```

--------------------------------

### Configure Console and Scout Instrumentation

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/README.md

Configuration array for enabling console and Scout instrumentation. The console instrumentation can be enabled/disabled via the OTEL_INSTRUMENTATION_CONSOLE environment variable and allows specifying commands. Scout instrumentation is controlled by OTEL_INSTRUMENTATION_SCOUT.

```php
Instrumentation\ConsoleInstrumentation::class => [
    'enabled' => env('OTEL_INSTRUMENTATION_CONSOLE', true),
    'commands' => [],
],

Instrumentation\ScoutInstrumentation::class => env('OTEL_INSTRUMENTATION_SCOUT', true),
],
```

--------------------------------

### setStartTimestamp method implementation

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/SpanBuilder.md

Sets the span start timestamp. Accepts a Carbon instance (converted to nanoseconds via CarbonClock::carbonToNanos()) or an integer nanosecond timestamp. Returns $this for chaining.

```php
/**
 * @param  CarbonInterface|int  $timestamp  A carbon instance or a timestamp in nanoseconds
 */
public function setStartTimestamp(CarbonInterface|int $timestamp): SpanBuilder
{
    if ($timestamp instanceof CarbonInterface) {
        $timestamp = CarbonClock::carbonToNanos($timestamp);
    }

    $this->spanBuilder->setStartTimestamp($timestamp);

    return $this;
}
```

--------------------------------

### configurePackage method

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/ServiceProviders.md

Configures the package with name 'laravel-opentelemetry' and publishes the config file. This method is part of the LaravelOpenTelemetryServiceProvider.

```php
public function configurePackage(Package $package): void
{
    $package
        ->name('laravel-opentelemetry')
        ->hasConfigFile();
}
```

--------------------------------

### QueryInstrumentation::recordQuery() method

Source: https://github.com/keepsuit/laravel-opentelemetry/blob/main/_autodocs/api-reference/DatabaseInstrumentation.md

Records a database query as a client span and a duration metric. Only queries starting with SELECT, INSERT, UPDATE, or DELETE are recorded. No-op when no trace is active.

```php
public function recordQuery(QueryExecuted $event): void
{
    if (! Tracer::traceStarted()) {
        return;
    }

    $operationName = (string) Str::of($event->sql)
        ->before(' ')
        ->upper()
        ->when(
            value: fn (Stringable $operationName) => in_array($operationName, ['SELECT', 'INSERT', 'UPDATE', 'DELETE']),
            callback: fn (Stringable $operationName) => $operationName->toString(),
            default: fn () => ''
        );

    if ($operationName === '') {
        return;
    }

    $sharedAttributes = $this->sharedTraceMetricAttributes($event, $operationName);

    $this->recordTraceSpan($event, $operationName, $sharedAttributes);
    $this->recordOperationDurationMetric($event, $sharedAttributes);
}
```
Tokens:
Raw