Events

The Events Explorer lets you search, visualize, and inspect operational events emitted in your WarpStream cluster. It is designed for troubleshooting and investigation. You can search recent activity, break it down over time, inspect full event payloads, and quickly pivot from one signal to another.

Depending on the page you are on, the explorer can be:

• A full Events page that searches across the event types enabled for a cluster

• An ACL-scoped explorer on the ACLs page

• A pipeline-scoped explorer on the pipeline details page

Enabling events

Events must be enabled on a virtual cluster before they are available in the console or via the API.

Through the web UI

1. Navigate to your cluster in the WarpStream Console.

2. Open the cluster's Events tab.

3. Toggle events on.

Once enabled, events will begin flowing within a few seconds.

Through Terraform

Use the events attribute of the warpstream_virtual_cluster resource. See the Terraform provider documentation for the full schema.

What are events?

WarpStream events are JSON documents wrapped in a CloudEvents-style envelope. The top-level fields identify the event itself, and the nested data object contains the event-specific payload that you usually filter, group, and inspect in the UI.

Common top-level fields include:

• specversion: the CloudEvents version, typically 1.0

• id: a unique event ID

• source: the component that emitted the event, such as an agent or control plane service

• type: the event category, such as agent_logs, acl_logs, pipeline_logs, or tableflow_logs

• time: the event timestamp

• datacontenttype: usually application/json

• data: the event payload

In practice, most searches focus on fields under data, such as data.log_level, data.message, data.operation, or data.pipeline_name.

Example ACL event

{
  "specversion": "1.0",
  "id": "7eb2c5d9-76b2-4559-8fff-73942a2c5895",
  "source": "ws:agent:vci_36aa3f5f_f5fd_4371_880d_0fb94ff60675:0243b517-676a-4b86-aaf9-278cbb91dfdf",
  "type": "acl_logs",
  "datacontenttype": "application/json",
  "time": "2026-03-02T14:06:36.562678971Z",
  "data": {
    "address": ":9092",
    "agent_id": "0243b517-676a-4b86-aaf9-278cbb91dfdf",
    "correlation_id": 2,
    "hostname_fqdn": "warp-agent-default-75bd977b45-4f8dm",
    "is_log": true,
    "kafka_api_key": 3,
    "kafka_api_key_name": "Metadata",
    "kafka_enabled": true,
    "log_level": "warn",
    "message": "ACL Denied Operation on resource",
    "module": "kafka_agent",
    "operation": "CREATE",
    "principal": "User:ccun_5d3cc38fb3b7da40db9681267923b1c9fe4f74e2b66cb6ae68079c4a12a9badc",
    "resource_name": "acl_validator_testf088792c-0ee1-4326-b40e-a21257efd380",
    "resource_type": "TOPIC",
    "virtual_cluster_id": "vci_36aa3f5f_f5fd_4371_880d_0fb94ff60675",
    "virtual_cluster_name": "vcn_test_cluster"
  }
}

Notice the two layers:

• The top-level envelope tells you when the event happened, where it came from, and what category it belongs to.

• The nested data payload carries the fields you typically search on, such as data.log_level, data.message, data.principal, data.operation, data.resource_type, and data.resource_name.

Event types

The exact event types depend on the kind of cluster you are working with:

• Kafka clusters typically expose agent_logs, acl_logs, and pipeline_logs

• Data lake clusters typically expose agent_logs and tableflow_logs

The main event types are:

• agent_logs: operational logs emitted by WarpStream agents

• acl_logs: ACL authorization and denial activity for Kafka operations

• pipeline_logs: Bento and Orbit pipeline activity and errors

• tableflow_logs: Tableflow and data lake activity, such as ingestion and table lifecycle events

Not every event has the same fields. For example:

• ACL events often include fields like data.principal, data.operation, data.resource_type, and data.resource_name

• Pipeline events often include fields like data.pipeline_name, data.stage, and data.message

• Tableflow events often include fields like data.type, data.table_name, and data.table_uuid

Searching events

The basic search flow is:

1. Pick one or more event types when the page allows it.

2. Choose a time range.

3. Add filters in Builder mode or Raw mode.

4. Optionally enable the timeline and configure grouping or aggregation.

5. Run the search and inspect the detailed results.

The full Events page exposes the most controls. The ACL and pipeline variants reuse the same explorer but start from a narrower scope.

Time range

The explorer supports:

• Quick relative ranges: Last 5m, Last 15m, Last 1h, Last 4h, and Last 1d

• Calendar shortcuts: Today and Yesterday

• A custom relative duration

• A single-day absolute time window

• A local time / UTC toggle in the time picker

For safety and performance, event queries are limited to a maximum 24-hour window.

Filter modes

The explorer has two filter modes:

• Builder mode: a structured UI for assembling filters from field, operator, and value

• Raw mode: a text expression for advanced filtering

Builder mode is the easiest way to create straightforward comparisons. Raw mode is the right choice when you want more expressive filters, such as or, like, or in.

Builder mode also suggests fields and sample values based on recent results. Raw mode is best when you already know the fields you want to target.

Switching between Builder and Raw mode clears the other mode's current filter state, so it is best to pick one mode for a search and stay in it.

Query language

In Raw mode, you write only the filter expression. The rest of the query is generated for you by the explorer.

The filter language supports:

• Comparisons: ==, !=, <, >, <=, >=

• Pattern matching: like, not like

• Set membership: in, not in

• Logical operators: and, or

• Nested field access with dot notation, such as data.resource_type

If you need to reference a top-level field name with special characters, wrap it in backticks, such as `field-name`.

Example filters:

data.operation == "CREATE" and data.resource_type == "TOPIC"

data.log_level == "warn" and data.principal like "%admin%"

data.kafka_api_key_name in ["Produce", "Fetch"] and data.log_level != "info"

Tips:

• Most user-relevant fields live under data, so filters often begin with data.

• String values should be quoted

• in and not in use square brackets

Preset queries

The explorer includes preset cards for common investigations. Depending on the page, these can prefill and immediately run a search with a combination of filter text, time range, grouping, and event type selection.

Examples include:

• Warnings and Errors by Type

• ACL by Operation

• ACL by Resource Type

• Pipeline Errors

• Pipeline Warnings

• Events by Stage

Shareable URLs

The explorer stores its search state in the URL. You can share links that preserve your selected event types, time range, sort order, filter state, and timeline configuration.

Timeline and aggregations

The Show timeline toggle adds a chart view above the detailed results. This is useful for spotting spikes, bursts, or changes in event volume over time.

The timeline view supports:

• Automatic time bucketing over the selected range

• Lines or Bars display modes

• Grouping by a field, such as type, data.operation, data.resource_type, or data.stage

• Numeric aggregations over a field using Avg, Max, Min, or Sum

When you group by a field, the chart can break the results into multiple series so you can compare categories over time. If there are too many distinct values, the chart keeps the most important series visible and groups the remainder into Other.

Detailed results

Below the timeline, the explorer shows a detailed event list.

Each result row shows a compact summary, including:

• Timestamp

• A one-line message

• Event type

• Log level when one is available

Clicking a row expands the full event details as JSON. From there, you can:

• Expand all nested fields

• Collapse the JSON view

• Copy the full event payload

The detailed results view is optimized for interactive investigation:

• Each search returns up to 100 detailed events

• Results are progressively revealed 20 at a time as you scroll

• A secondary in-results filter bar lets you narrow the current result set without re-running the backend query

The in-results filter bar is client-side only. It is useful when the main search has already returned the right time window and event family, and you just want to narrow the visible rows further.

Quick actions from JSON fields

The JSON details view is not just for inspection. Clicking a field name opens a context menu with quick actions such as:

• Copy field name

• Copy field value

• Add a filter like field == value

• Add a filter like field != value

• Group the timeline by that field

This makes it easy to pivot from a single interesting event into a broader search or chart without manually typing the field path.

Scoped explorer variants

The same explorer appears in a few different places, with different levels of scope:

• Global Events page: the full explorer, where you can search across the enabled event types for the cluster

• ACLs page: an ACL-focused explorer that is already scoped to ACL events

• Pipeline details page: a pipeline-focused explorer that is already scoped to the current pipeline

On the pipeline details page, the explorer applies the current pipeline name behind the scenes so searches stay focused on that pipeline. On the ACLs page, the explorer is limited to ACL events for the current cluster.

Limits and behavior

The explorer is intended for fast, interactive investigations, so it includes a few practical limits:

• Queries are limited to a maximum 24-hour time range

• The detailed results list returns up to 100 events per search

• The timeline uses aggregated buckets rather than plotting every individual event directly

Those limits keep searches responsive while still making it easy to move from a broad signal to a specific event payload.