workers-telemetry-client

Lightweight, zero-dependency TypeScript client for the Cloudflare Workers Observability Telemetry API.

Install

npm install @bk.cc/workers-telemetry-client

Usage

Client

import { createClient, buildQuery } from "@bk.cc/workers-telemetry-client";

const client = createClient({
  accountId: "your-account-id",
  apiToken: "your-api-token",
});

// Destructuring works — no `this` binding issues
const { queryEvents, listKeys } = createClient({ accountId, apiToken });

Query events

const query = buildQuery()
  .service("my-worker")
  .last("1h")
  .search("error")
  .limit(50)
  .build();

const events = await client.queryEvents(query);

// Or get parsed & deduped log entries in one call
const logs = await client.queryLogs(query);

Time range helpers

buildQuery().last("5m");       // last 5 minutes
buildQuery().last("2h");       // last 2 hours
buildQuery().last("7d");       // last 7 days
buildQuery().lastHour();       // last hour
buildQuery().last24Hours();    // last 24 hours
buildQuery().last7Days();      // last 7 days
buildQuery().last30Days();     // last 30 days
buildQuery().today();          // since midnight
buildQuery().last(3_600_000);  // raw milliseconds still works

Aggregations

const query = buildQuery()
  .service("my-worker")
  .last("1h")
  .view("calculations")
  .count()
  .avg("$workers.wallTimeMs")
  .p95("$workers.wallTimeMs")
  .groupBy("$metadata.service")
  .build();

const response = await client.query(query);

Available calculation methods: count(), countDistinct(key), sum(key), avg(key), min(key), max(key), p50(key), p90(key), p95(key), p99(key).

Query with filters

const query = buildQuery()
  .service("my-worker")
  .timeframe(Date.now() - 3_600_000, Date.now())
  .filter("$metadata.level", "eq", "error")
  .search("timeout", { regex: false, caseSensitive: false })
  .limit(100)
  .build();

const response = await client.query(query);

Pagination

Iterate through large result sets automatically:

const query = buildQuery()
  .service("my-worker")
  .last("24h")
  .limit(100)
  .build();

for await (const batch of client.queryPaginated(query)) {
  console.log(`Got ${batch.length} events`);
  // process batch...
}

Error handling

All errors are thrown as ObservabilityError with a code to distinguish failure types:

import { ObservabilityError } from "@bk.cc/workers-telemetry-client";

try {
  await client.queryEvents(query);
} catch (error) {
  if (error instanceof ObservabilityError) {
    switch (error.code) {
      case "rate_limit":
        console.log(`Rate limited, retry after ${error.retryAfterMs}ms`);
        break;
      case "auth":
        console.log("Check your API token");
        break;
      case "validation":
        console.log("Invalid query:", error.body);
        break;
      case "server":
        console.log("Cloudflare server error");
        break;
    }
  }
}

List available keys

const keys = await client.listKeys();
// [{ key: "$metadata.service", lastSeenAt: 1710000000, type: "string" }, ...]

List values for a key

const values = await client.listValues({
  datasets: ["cloudflare-workers"],
  key: "$metadata.service",
  type: "string",
  timeframe: { from: Date.now() - 86_400_000, to: Date.now() },
});

Parse events into log entries

Raw telemetry events have a deeply nested structure. parseEvent flattens them into a human-friendly WorkerLogEntry:

import { parseEvents, dedup } from "@bk.cc/workers-telemetry-client";

const logs = dedup(parseEvents(events));

for (const log of logs) {
  console.log(`[${log.level}] ${log.service}: ${log.message}`);
}

API

createClient(options) → ObservabilityClient

| Method | Returns | Description | |---|---|---| | query(query) | TelemetryQueryResponse | Execute a telemetry query (full response) | | queryEvents(query) | TelemetryEvent[] | Execute a query and return only events | | queryLogs(query) | WorkerLogEntry[] | Execute a query and return parsed log entries | | queryPaginated(query) | AsyncGenerator<TelemetryEvent[]> | Paginate through all matching events | | listKeys() | TelemetryKey[] | List all available telemetry keys | | listValues(request) | TelemetryValue[] | List distinct values for a key |

ClientOptions

| Option | Type | Default | Description | |---|---|---|---| | accountId | string | required | Cloudflare account ID | | apiToken | string | required | API token | | baseUrl | string | https://api.cloudflare.com/client/v4 | Base URL override |

QueryBuilder (via buildQuery())

| Method | Description | |---|---| | .queryId(id) | Set query ID for tracking | | .view(view) | Set view type ("events", "calculations") | | .limit(n) | Max results to return | | .timeframe(from, to) | Set time range (Unix ms) | | .last(duration) | Relative time range ("5m", "1h", "7d", or ms) | | .lastHour() | Last hour preset | | .last24Hours() | Last 24 hours preset | | .last7Days() | Last 7 days preset | | .last30Days() | Last 30 days preset | | .today() | Since midnight today | | .datasets(ds) | Set datasets (default: ["cloudflare-workers"]) | | .service(name) | Filter by Worker service name | | .filter(key, op, value?, type?) | Add a filter | | .filterCombination(combo) | Set filter combination ("AND" / "OR") | | .search(value, opts?) | Search log content | | .count() | Count all events | | .countDistinct(key) | Count distinct values | | .sum(key) | Sum a numeric key | | .avg(key) | Average of a numeric key | | .min(key) / .max(key) | Min / max of a numeric key | | .p50(key) / .p90(key) / .p95(key) / .p99(key) | Percentiles | | .calculate(op, key?) | Add any calculation | | .calculations(calcs) | Set calculations directly | | .groupBy(key, opts?) | Add a group-by clause | | .groupBys(groups) | Set group-by clauses directly | | .build() | Build the TelemetryQuery object |

ObservabilityError

| Property | Type | Description | |---|---|---| | code | ErrorCode | "auth", "validation", "rate_limit", "server", "unknown" | | status | number | HTTP status code | | body | string | Response body | | retryAfterMs | number \| null | Parsed retry-after (rate limit only) |

Utilities

| Function | Description | |---|---| | parseEvent(event) | Parse a raw event into a WorkerLogEntry | | parseEvents(events) | Parse an array of events | | dedup(logs) | Deduplicate log entries by request ID | | parseDuration(str) | Parse "5m", "1h", "7d" into milliseconds |

License

MIT