Download the PHP package mr-dlef/os-query-digest without Composer

os-query-digest

Human-readable, loggable digests and stable fingerprints for OpenSearch DSL queries.

A DSL query in a log line is a wall of nested braces: nobody greps it, nobody groups by it, and it costs a fortune in log volume. So the question you actually have during an incident — which kind of query is hurting us? — has no answer anywhere in your stack.

This gives it one!

📖 Documentation · ▶ Try it on your own query

Before. One search request, as it lands in your logs — and there are thousands of these a day:

After. The same request, three ways:

The third one is the point. Log the hash next to took, and your log index answers questions your dashboards cannot: which kind of query got slow this week, which one showed up with Friday's deploy, which one was hammering the cluster during the incident. Not which thousand queries were slow — which shape was. OpenSearch, analysing OpenSearch.

That query and that fingerprint are not illustrations: they are tests/fixtures/01-error-rate-filter, and the golden file pins the exact hash.

Install

Download the CLI

It digests a query you paste, a file of them a line at a time, or the slow log your cluster is already writing — every flag is in the guide:

That last one ranks the shapes in the file by what they cost you: no code to change, nothing to deploy, no index to create. Needs PHP 7.4 → 8.5 on the machine, and every release carries a .sha256 beside the file.

Or run it in Docker

It reads standard input, so nothing has to be mounted. Mounting a log instead is one flag. Both artefacts are built from the same source as the package and mint the same fingerprints — CI digests one query each way and compares the two.

Then put it in your application

Three ways in, and they mix:

• The Monolog processor replaces the request body with its digest wherever your application already logs one. One processor, no call sites.
• A PSR-18 decorator or a Guzzle middleware digests every search on its way out of the HTTP client, already joined to what it cost.
• The formatter, when you want the digest in your own hands:

ext-json, and no runtime dependencies: Monolog, PSR-18 and Guzzle are suggested, never required.

What you get

• Logs you can read, and fewer bytes of them. A 40-line body becomes one capped line — and it is DQL, so you select it, paste it into the Dashboards search bar, and you are looking at the same query.
• The dashboard is written already. An index template and four panels ship in the package — import them and you are looking at which shape costs you, which one regressed, and which one the last release added.
• It cannot break your logging. Nothing is required at runtime, the digest is lazy, and a request it cannot parse yields an error field rather than an exception. You lose the digest, never the log line.
• It says what kind of work each search is. Every digest carries a kind — suggest, aggregate, scan, lookup, browse — read off the parsed request, so a top-N grouped by it reads as a sentence instead of two hundred hashes.
• It tells you why. When two queries you thought were different share a hash, explain() names the rule that merged them.
• It is verified, not asserted. Certified against real OpenSearch 2.19.6 and 3.8.0 nodes, checked against the official API specification, PHPStan at level: max, mutation-tested, benchmarked, and run on PHP 7.4 → 8.5.

Documentation

mrdlef.github.io/php-os-query-digest — a guide for each way in, the reference, and the reasoning behind the normalisation rules.

• Getting started goes from nothing to a log line you can read.
• Hash stability comes before storing a fingerprint anywhere permanent: the prefix moves when the rules do, so a stored hash is never silently reinterpreted.
• Which normalisation level answers which question — the default fingerprints page 1 and page 3 of a search apart, which is right for ranking by latency and wrong for counting what your application searches for.

The site tracks the latest release, not main.

Contributing and security

CONTRIBUTING.md — the commands, and the rules that are not guessable from the code.

SECURITY.md — report a vulnerability privately, not in an issue.

License

LGPL-3.0-or-later — see LICENSE.

The LGPL builds on the GPL, so both texts ship: LICENSE holds the Lesser GPL and LICENSE.GPL the GPL it refers to.

In practice: you can use this library in a closed-source application without that application becoming subject to the licence. If you modify the library itself and distribute it, those changes stay under the LGPL.