Capture and explore events

Events turns application activity into a source you can search, chart and investigate. A dataset defines retention, optional masking and the typed fields available for analysis. Its managed source appears alongside your other query sources.

Set up a datasetCopy Anchor Link

Open Events, choose or create a dataset, and select its event destination. Destinations can use a separately configured event service; managed cloud capacity has its own provisioning and billing flow. Dataset configuration is available before storage is ready, but ingestion and real searches need a working destination.

Choose retention when creating the dataset. Retention cannot be edited afterward. Add typed dimensions for values you intend to filter or aggregate: text, number, boolean or date/time. Field names and types are immutable; add a new field when meaning changes.

Use stable namespaces and groups such as production and orders. They organize events; they are not tenant isolation boundaries. The dataset credential determines ingestion authority.

Connect an applicationCopy Anchor Link

Choose Connect application to obtain the dataset's endpoint and create an ingestion key. Copy the key when it is shown and store it in the producer's secret configuration. These keys append events to their dataset; they do not grant dashboard or account access.

The batch envelope includes a stable batch ID and events with an immutable ID, namespace, group, type, timestamp and schema version. Typed dimensions are queryable. Optional data holds inspection details.

{
  "version": 1,
  "batchId": "ab84bb9c-93fa-4ce8-bb75-dcb787bc2a07",
  "events": [
    {
      "id": "order-123-created",
      "namespace": "production",
      "group": "orders",
      "type": "order.created",
      "timestamp": "2026-10-23T12:00:00.000Z",
      "schemaVersion": 1,
      "dimensions": { "orderId": "123" },
      "data": { "origin": "checkout" }
    }
  ]
}

Declare orderId as a text dimension before sending this example, and use a current timestamp within the dataset's retention window. Do not reuse an event identity for different contents. If a delivery times out, retry the same batch ID and payload. A 202 means durable queue acceptance; the event may not be queryable immediately.

Masking applies only to the field names and paths you configure. There is no automatic secret detection. Keep sensitive payloads out of event data unless their collection and access are intended.

Search and investigateCopy Anchor Link

Select a time range and add conditions on core fields or declared dimensions. Text search covers event IDs, types, namespaces, groups and declared text dimensions. Raw data is inspection-only and is not searched or scanned for chart calculations.

Submit the search, page through the bounded results, and open an event to fetch its details. Group matching events by up to four fields. Preserve the returned total, hasMore and truncated distinctions when using these operations through an agent or SDK; one page is not the complete dataset.

Inspect a traceCopy Anchor Link

In the dataset editor, choose Add trace fields. This adds missing fields without changing existing names or types. A conflicting field type must be resolved by choosing a compatible dataset; existing field types are immutable.

The event's timestamp is the span start. The first three dimensions enable trace inspection; the other fields add hierarchy and context. The SDK exports EVENT_TRACE_DIMENSIONS for programmatic dataset creation and spanEvent for completed spans:

import { createEventClient, spanEvent } from 'bytesmap/events'

const events = createEventClient({
  endpoint: process.env.BYTESMAP_EVENTS_URL!,
  dataset: process.env.BYTESMAP_EVENT_DATASET!,
  token: process.env.BYTESMAP_EVENT_TOKEN!,
  namespace: 'production',
  group: 'orders',
})

await events.emit(
  spanEvent({
    traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
    spanId: '00f067aa0ba902b7',
    name: 'GET /orders',
    service: 'api',
    start: requestStartedAt.toISOString(),
    durationMs: elapsedMs,
    status: 'ok',
    data: { route: '/orders' },
  }),
)

Configure the endpoint, dataset and ingestion key from Connect application, and supply your actual request timing and trace context. The helper validates nonzero 32-character hexadecimal trace IDs and 16-character span IDs, generates a stable event identity, and does not instrument your application or create parent context automatically. Fractional millisecond durations are supported; stored start timestamps have millisecond precision. Map completed spans from your instrumentation into these fields. BytesMap does not currently expose an OTLP collector endpoint.

Open an event and select View trace. Waterfall shows span start offsets and durations; Tree shows the same parent hierarchy. Expand or collapse branches, select a span, then open its original event. Elapsed time covers the earliest retained start through the latest retained end; overlapping durations are not added together. Colors identify services, and failures have an explicit error label.

The trace query reads only the selected dataset using its current read permission. An ingestion key cannot read traces. Results include at most 1,000 retained spans, or fewer when the source's row limit is lower. A limited result is marked incomplete. Missing parents, duplicate IDs, cyclic links and timing outside a parent are shown explicitly; a partial result is not a complete distributed trace. Refresh keeps existing spans visible while loading, but revoked access clears them.

Agents and SDK consumers can use events.trace({ id: datasetId, traceId }). It returns events and truncated; the query does not include inspection-only payloads. Fetch a selected original event with events.inspect using its ID, namespace and group. Trace reads retain the source's timeout and query limits; a row limit alone is not a bound on scanning work.

Use events in a dashboard or workflowCopy Anchor Link

Choose the dataset's managed source in a query. Its analytical view exposes typed nullable columns from the declared dimensions. Use the shared query and chart builder to count, filter, group or compare them over time.

Workflows can append events using an explicit event target and dataset ingestion permission. Saving a mapping does not send it. Use a test dataset when exercising effects.

Agents use the same Events operations and destination operations. Creating a reusable ingestion key remains an account action in the application.

For the complete wire limits, durable-delivery contract and service deployment settings, see the event service reference.