Punk-Observe - an OpenTelemetry observability and logging backend

This is a BACKEND, not a client. It receives OTLP, stores it, queries it and
draws it. To emit telemetry from a Perl application, see Punk::OpenTelemetry.

WHAT IS HERE

    Ingest      OTLP over http/protobuf and http/json, gzip and deflate
                bodies, partial success, and a tenant resolver. Served as a
                PSGI application, so it mounts into Punk, plackup or anything
                else that speaks PSGI.
    Storage     a write-ahead log, immutable segments with content-derived
                series ids, compressed metric chunks, deflated log blocks with
                a trigram filter, and spans assembled at read time.
    Queries     one language over all three signals, with a planner that
                refuses an over-budget query and a resumable executor that
                yields to the event loop.
    Retention   compaction, five-minute and hourly rollups, and deletion by
                whole block.
    Drawing     server-rendered chart primitives, service graph layout and
                flamegraph folding.

    Screens     status, logs, metrics, traces, the service map, explore,
                dashboards and alerts, mounted into a Punk application by
                Punk::Plugin::Observe behind a guard the host supplies.
    Alerting    per-series rule state, grouping, silences and an SSRF-checked
                webhook target.

There is no packaged server binary: what ships is the engine, the PSGI
receiver and the plugin, assembled by the host application. Dashboards, alert
rules and saved views are configuration and live in a database - SQLite beside
the store by default, PostgreSQL when told.

gRPC ingest is deliberately not offered. It reports failure in HTTP/2
trailers, PSGI has no trailer channel, and an endpoint answering 200 with no
grpc-status is an exporter that looks successful while losing every batch.

INSTALLATION

    perl Makefile.PL
    make
    make test
    make install

DOCUMENTATION

    perldoc Punk::Observe            the system, and why it is shaped this way
    perldoc Punk::Observe::Ingest    the receiver
    perldoc Punk::Observe::Query     the query language

The language also has a reference inside the application itself, at
<prefix>/help - generated from the parser's own tables, so it says what this
build actually accepts rather than what a document once claimed.

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION.
This is free software, licensed under the Artistic License 2.0.
