Tenant activity logs

​

What lands in the activity log

• call lifecycle
• agent activity
• meetings
• streams
• VPN sessions
• webhook deliveries
• quota notices

​

Event schema

const d = new Date(ts.includes("T") ? ts : ts.replace(" ", "T") + "Z");

​

The fields blob

function parseFields(fields: string): unknown {
  try {
    const v = JSON.parse(fields);
    return v && typeof v === "object" && Object.keys(v as object).length > 0 ? v : null;
  } catch {
    return null;
  }
}

​

Sources and event types

​

Volume, levels and the one-minute rollup

const overview = await logs.overview.query({ orgId, windowMinutes: 60 });
// {
//   histogram: [{ bucket, info, warn, error }, ...],
//   bySource: [{ source, events, bytes }, ...],
//   totals:   { events, bytes },
//   budget:   { eventsPerMin, bytesPerMin, retentionDays },
//   stepSec
// }

• histogram is stacked by level: each point has separate info, warn and error counts for its bucket.
• stepSec is the bucket width the server chose. It caps the histogram at roughly 120 points regardless of window size, and is always a whole number of minutes with a floor of 60 seconds. A 15-minute window buckets at one minute; a 7-day window buckets much coarser.
• bucket is a ClickHouse timestamp string with the same no-timezone caveat as ts.
• totals is the sum of bySource, so it counts events and bytes across the whole window.

​

Admission budget

​

Retention

​

Query windows and filters

const page = await logs.query.query({
  orgId,
  windowMinutes: 60,
  levels: ["warn", "error"],
  sources: ["..."],
  search: "sid_",
  limit: 200,
});
// { rows, nextBeforeMs, gap }

• a case-insensitive substring match on message
• a case-insensitive substring match on event_type
• an exact match on call_sid

​

Cursor paging with nextBeforeMs

• If more rows exist beyond this page, nextBeforeMs is the ts_ms of the last (oldest) row on the page. Pass it as beforeMs to get the next, older page.
• If this page is the end of the window, nextBeforeMs is null.

let beforeMs: number | undefined;
for (;;) {
  const res = await logs.query.query({ orgId, windowMinutes: 1440, limit: 200, beforeMs });
  handle(res.rows);
  if (!res.nextBeforeMs) break;
  beforeMs = res.nextBeforeMs;
}

• Seeking by timestamp costs the same for the 2nd page as for the 200th, whereas OFFSET re-scans everything it skips.
• It stays correct while the log is being written. With OFFSET, rows arriving at the head shift every later page and the reader silently sees duplicates.

​

Tailing with afterMs and the gap flag

const res = await logs.query.query({ orgId, windowMinutes, limit: 500, afterMs: newestMs });
if (res.gap) {
  // hole in the stream — discard and re-seed from the head page
} else if (res.rows.length) {
  newestMs = Number(res.rows[0].ts_ms); // rows are newest-first
  prepend(res.rows);
}

• gap is only ever true when afterMs was supplied and the result hit the limit.
• On gap: true, do not stitch the rows onto your buffer. That leaves a silent hole. Discard and re-fetch the head page (the same request without afterMs or beforeMs), then resume tailing from its newest ts_ms.

• Only the head page streams. On an older page the reader is looking at a fixed window; new arrivals must not push it around.
• Cap your buffer. Nothing in logs.query limits how much you accumulate across polls. The console caps at 50,000 rows and trims from the old end; beyond that the answer is a narrower window or a filter, not more rows in the browser.

​

Empty results are not always empty

• logs.query returns { rows: [], nextBeforeMs: null, gap: false }.
• logs.overview returns empty histogram, bySource and totals, but still returns a populated budget and stepSec.

​

Related

• Telemetry — the gateway’s own metrics, traces, CDRs and SIP capture
• Authentication — the API key scopes that reach the control plane