Traceloom

Why it exists

Logs show isolated messages. A trace shows a story.

Traditional application logs give you lines. Each one is true, and none of them tells you what the request actually did. Traceloom connects related events into a readable execution timeline for one logical process: a request, a job, a webhook, a script.

Language versions

Three implementations. All released.

PHP came first and is the most mature. JavaScript and Go have both reached v0.1.0 and write the same event format; they are published, installable and usable today.

composer require golovanov/traceloom

use Golovanov\Traceloom\Tracer;

$tracer = Tracer::fromDirectory(__DIR__ . '/logs');

$trace = $tracer->start();

$trace->event('request_start', [
    'method' => 'POST',
    'path' => '/orders',
]);

$trace->event('auth_success', [
    'user_id' => 42,
]);

$trace->event('request_end', [
    'status' => 201,
]);

npm install @rgolovanov/traceloom

import { Tracer } from '@rgolovanov/traceloom';

const tracer = Tracer.fromDirectory('./logs');
const trace = tracer.start();

await trace.event('request_start', {
  method: 'POST',
  path: '/orders',
});

await trace.event('auth_success', { user_id: 42 });
await trace.event('request_end', { status: 201 });

await tracer.close();

go get github.com/golovanov-dev/traceloom-go

package main

import (
    "log"

    traceloom "github.com/golovanov-dev/traceloom-go"
)

func main() {
    tracer, err := traceloom.New("./logs")
    if err != nil {
        log.Fatal(err)
    }
    defer tracer.Close()

    trace, err := tracer.Start("")
    if err != nil {
        log.Fatal(err)
    }

    if err := trace.Event("request_start", traceloom.Data{
        "method": "POST",
        "path":   "/orders",
    }); err != nil {
        log.Fatal(err)
    }

    _ = trace.Event("auth_success", traceloom.Data{"user_id": 42})
    _ = trace.Event("request_end", traceloom.Data{"status": 201})
}

Design principles

The rules the library is held to

Every one of these has said no to a feature at some point. That is what makes them principles rather than adjectives.

Roadmap

What shipped, and what I'm not promising

Released means published and installable. Everything below that line is an intention.

1. Shipped · PHP v0.1.0 → v0.2.0

   The PHP core

   Tracer and Trace, trace-ID generation and continuation, JSONL writer with date-based files and size-based shard rotation, flock coordination, sensitive-key masking, fail-safe error handling and the eventtrace show CLI.

2. Shipped · JavaScript v0.1.0 · Go v0.1.0

   Two more languages, one format

   The Node.js package (ESM + CJS + types, batched async writes, bounded queue with an overflow policy) and the Go module (kernel file locks on Unix and Windows, context-aware events, reflection-based payload normalization), both writing the PHP wire format.

3. Shipped · PHP v0.3.0 → v0.4.0

   The contract closes the gaps

   Building the JS and Go implementations exposed real holes in the PHP sanitizer. v0.3.0 aligned masking, marker escaping and defaults across all three; v0.4.0 added maxKeyBytes: an unbounded key was the last way a single hostile field could degrade an entire event.

4. In progress

   Toward a stable v1.0

   Stabilizing the API across the three implementations so the shared contract can be frozen at v1.0. No new features and no dates promised: the work is letting the interfaces settle and hold.

5. Considered · not committed

   Beyond the MVP core

   A richer CLI (tail, event search) and framework adapters for PSR-7, Laravel, Symfony or Express are deliberately outside the core today. If they land, they land as separate packages: the core stays small.