The Terminal Side of Instant Logs

Instant Logs, introduced during Speed Week 2021 for Enterprise customers, has expanded beyond its initial UI offering. The service now supports direct WebSocket access, letting you pull live HTTP request data into command-line tools for real-time examination. This setup relies on two open-source utilities: websocat for maintaining the WebSocket connection and Angle Grinder for processing the stream.

Building a Log Stream

Creating an Instant Logs session with a POST request to the jobs endpoint is the first step. You'll need your zone tag and either an authentication key or an API token carrying the Zone Logs Read permission.

The response body includes a destination_conf field containing a unique WebSocket URL. Connecting to that address with websocat starts an immediate stream of line-delimited JSON, providing direct access to the same data set that powers the Instant Logs UI.

Defining a Session: A Practical Walkthrough

To understand the session parameters, consider a scenario where a firewall rule blocks a path (/canadians-only) for non-Canadian visitors. The goal is verifying that rule behaves correctly across regions.

Fields, Sampling, and Filters

Any HTTP request dataset field can be requested in a session. For this use case, the relevant ones are ClientRequestCountry, FirewallMatchesActions, and FirewallMatchesRuleIDs.

The sample parameter controls the data volume. It represents the inverse probability of capturing a log: "sample": 1 retains all records, "sample": 10 keeps 10%, and so on. High-traffic zones may enforce server-side sampling regardless of your setting. When that occurs, the log payload includes a sampleInterval field to signal that this message represents one out of N logs received.

Filters restrict the stream to relevant events. Each filter specifies a key, operator, and value. Any field listed in the session's fields array is a valid key. To watch only requests for the asset in question, apply a filter on the request path.

Request and Validation

Combining these parameters produces a session request that targets the specific asset requests where firewall policies could apply. With the destination_conf from the response, pipe the WebSocket data into Angle Grinder. The tool accepts JSON input on stdin and supports filtering, transformation, and aggregation with SQL-like syntax.

A simple Angle Grinder query can tally visitors by country:

| count by ClientCountry

To validate the firewall rule specifically, aggregate counts of firewall actions per country:

| count by ClientCountry, FirewallMatchesActions

The resulting output shows whether traffic from restricted countries is being blocked as intended. If the numbers align with your rule's expectations, the deployment is confirmed.

The same pipeline—a POST request, a WebSocket connection, and a CLI aggregation tool—applies to any HTTP request field or filter combination the Instant Logs API supports, giving you scriptable, real-time visibility into your edge traffic.