Telescope

// access
$nexus->telescope()

TelescopeCopy Anchor Link

class Inverge\Nexus\Telescope\Telescope

Nexus Telescope — records the journey of every unit of work (an HTTP request, a queued job, a console command, a scheduled task) and everything it did: queries, outgoing HTTP, cache, events, jobs dispatched, mail, exceptions, logs… Framework-agnostic; the Laravel and Symfony integrations drive it automatically.

$t = $nexus->telescope();
$t->start('request', ['method' => 'GET', 'uri' => '/orders/7'], ['traceparent' => $_SERVER['HTTP_TRACEPARENT'] ?? null]);
$t->query('select * from orders where id = ?', [7], 1.8, 'mysql');
$result = $t->span('price lookup', fn () => $pricing->quote($order));
$t->finish(['responseStatus' => 200]);

Nothing here ever throws into the host application: recording and delivery failures are swallowed. Batches are tail-sampled at finish, so failed and slow work is always kept whatever the sample rate.

Batches nest (a sync queue job runs inside the request that dispatched it), so the recorder keeps a STACK; entries always go to the innermost batch.

__constructCopy Anchor Link

function __construct(Inverge\Nexus\NexusClient $client, array $options = [])

enabled?: bool, service?: string|null, host?: string|null, release?: string|null, timeout?: float, max_entries?: int, ignore_types?: list<string>, ignore_paths?: list<string>, redact_keys?: list<string>, sample_rate?: float|null, capture_response_bodies?: bool, body_size_limit?: int, cache_dir?: string|null, transport?: Transport, } $options

Parameters

frames()Copy Anchor Link

static function frames(Throwable $e): array

Stack frames in the shape Nexus Errors renders.

Parameters

Returns list<array{function:string,filename:string,lineno:int}>

scalarize()Copy Anchor Link

static function scalarize(mixed $value, int $depth = 0)

Make values JSON-safe: objects become their class (or id for models), resources their type, long strings are clipped.

Parameters

Returns mixed

enabled()Copy Anchor Link

function enabled(): bool

Whether Telescope records at all (local switch, service switch, remote pause). */

Returns bool

active()Copy Anchor Link

function active(): bool

Whether a unit of work is being recorded right now. */

Returns bool

current()Copy Anchor Link

function current(): ?Inverge\Nexus\Telescope\Batch

Returns ?Inverge\Nexus\Telescope\Batch

ignores()Copy Anchor Link

function ignores(string $type): bool

Whether this entry type is switched off locally or from the console. */

Parameters

Returns bool

ignoresPath()Copy Anchor Link

function ignoresPath(string $path): bool

Whether a request path is ignored (/health, /horizon/*, …). */

Parameters

Returns bool

redactor()Copy Anchor Link

function redactor(): Inverge\Nexus\Telescope\Redactor

Returns Inverge\Nexus\Telescope\Redactor

option()Copy Anchor Link

function option(string $key)

Parameters

Returns mixed — */

start()Copy Anchor Link

function start(string $type, array $content = [], array $context = []): ?string

Open a unit of work. $context may carry an incoming traceparent header, or an explicit traceId / parentSpanId (from a job payload), plus tags, user, name, sessionKey, deviceKey.

Parameters

Returns ?string

finish()Copy Anchor Link

function finish(array $content = [], ?string $status = NULL, ?string $name = NULL): void

Close the innermost unit of work: merge final content, decide whether to keep it (tail sampling) and queue it for delivery. Sends when the outermost one closes.

Parameters

finishAll()Copy Anchor Link

function finishAll(array $content = []): void

Close every open unit of work (e.g. a fatal error ended the process). */

Parameters

record()Copy Anchor Link

function record(string $type, array $content = [], array $opts = []): ?string

Record an entry in the current unit of work.

Options: durationMs, startedAt (microtime float), status, name, tags, parentId, id.

Parameters

Returns ?string

span()Copy Anchor Link

function span(string $name, callable $fn, array $content = [], string $type = 'span')

Run $fn inside a named span; entries recorded meanwhile nest under it.

Parameters

Returns T

openSpan()Copy Anchor Link

function openSpan(string $type, string $name, array $content = []): ?string

Open a span manually (pair with closeSpan()); returns its id.

Parameters

Returns ?string

closeSpan()Copy Anchor Link

function closeSpan(?string $id, array $extra = []): void

Parameters

query()Copy Anchor Link

function query(string $sql, array $bindings, float $durationMs, ?string $connection = NULL, array $extra = []): ?string

Parameters

Returns ?string

exception()Copy Anchor Link

function exception(Throwable $e, bool $handled = false, array $context = []): ?string

Parameters

Returns ?string

log()Copy Anchor Link

function log(string $level, string $message, array $context = []): ?string

Parameters

Returns ?string

tag()Copy Anchor Link

function tag(string ...$tags): void

Parameters

user()Copy Anchor Link

function user(array $user): void

The authenticated user of the current unit of work. id becomes the Auth:<id> tag and correlates the journey into Nexus Sessions.

Parameters

traceparent()Copy Anchor Link

function traceparent(?string $spanId = NULL): ?string

A W3C traceparent for an outgoing call made from the current point. */

Parameters

Returns ?string

propagation()Copy Anchor Link

function propagation(?string $spanId = NULL): ?array

What a queued job carries so its execution joins this trace.

Parameters

Returns array{traceId:string,parentSpanId:string}|null

flush()Copy Anchor Link

function flush(): void

Send queued batches now. Never throws. */

TraceContextCopy Anchor Link

class Inverge\Nexus\Telescope\TraceContext

W3C Trace Context (traceparent: 00-<32 hex trace>-<16 hex span>-<flags>). Interoperates with OpenTelemetry, so a PHP service and an OTel-instrumented Go/Java/Node service show up in the same Nexus trace.

parse()Copy Anchor Link

static function parse(?string $header): ?array

Parameters

Returns array{traceId:string,spanId:string}|null — */

format()Copy Anchor Link

static function format(string $traceId, string $spanId): string

Parameters

Returns string

newTraceId()Copy Anchor Link

static function newTraceId(): string

Returns string

newSpanId()Copy Anchor Link

static function newSpanId(): string

Returns string

RedactorCopy Anchor Link

class Inverge\Nexus\Telescope\Redactor

Removes secrets before anything leaves the process. Keys are matched case-insensitively; any key containing "password" or "secret" is always redacted. The Nexus server redacts again with the environment's own list.

__constructCopy Anchor Link

function __construct(array $extra = [])

Parameters

globMatch()Copy Anchor Link

static function globMatch(string $glob, string $value): bool

Parameters

Returns bool

redact()Copy Anchor Link

function redact(array $data, int $depth = 0): array

Parameters

Returns array<mixed>