DEV Community

Immanuel Gabriel
Immanuel Gabriel

Posted on

Making Ops Pulse less project-specific and more useful for Cloudflare builders

#typescript #opensource #devtool #ops

I built Ops Pulse because I needed a calmer way to diagnose my Cloudflare setup.

When you are running Workers, D1, cron schedules, and logs across a few small services, the hard part is not always “getting metrics.”

The hard part is knowing what the metrics mean.

A Worker can look scary because an old error is still inside a long report window.

A cron job can look broken when it simply was not expected to run yet.

A service can be idle without being unhealthy.

A feed can be healthy but quiet.

And sometimes the thing you are about to edit is not the thing that is actually failing.

That is the loop Ops Pulse is meant to reduce.

Cloudflare metrics in.
Plain-English diagnosis out.
Enter fullscreen mode Exit fullscreen mode

What Ops Pulse does

Ops Pulse is a local-first CLI for diagnosing Cloudflare Workers, D1, cron schedules, and Workers Observability logs.

It runs on your machine, uses your own Cloudflare token, and produces readable reports about what looks healthy, degraded, idle, noisy, or unknown.

You can run it with npx:

npx freshcontext-ops-pulse --help
Enter fullscreen mode Exit fullscreen mode

Or install it globally:

npm install -g freshcontext-ops-pulse
freshops --help
Enter fullscreen mode Exit fullscreen mode

The tool is designed for people who want a quick operational read before they start changing code.

It can help inspect things like:

  • Worker request counts
  • error rates
  • invocation status
  • runtime exceptions
  • client disconnects
  • CPU and wall time
  • subrequests
  • D1 reads and writes
  • D1 latency
  • cron behavior
  • Workers Observability events
  • recent logs for a specific Worker
  • plain-English recommendations

Example commands:

freshcontext-ops-pulse report --hours 1
freshcontext-ops-pulse report --hours 6
freshcontext-ops-pulse logs --worker my-worker --hours 1
freshcontext-ops-pulse errors --worker my-worker --hours 24
freshcontext-ops-pulse assays
Enter fullscreen mode Exit fullscreen mode

The goal is not to replace Cloudflare Observability.

The goal is to sit one layer above the raw signals and help answer:

What is actually broken?
What is healthy?
What is idle?
What is old noise?
What should I inspect first?
What should I avoid touching?
Enter fullscreen mode Exit fullscreen mode

That last question matters a lot.

A surprising amount of debugging time is wasted changing healthy systems.

Local-first setup

Ops Pulse does not require a hosted dashboard.

It does not require an account with FreshContext.

It does not send your Cloudflare metrics to my server.

It reads from Cloudflare using the credentials you provide locally.

Required environment variables:

CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_API_TOKEN=
Enter fullscreen mode Exit fullscreen mode

The token should be read-only where possible.

The current docs explain recommended Cloudflare token permissions, but the basic principle is simple: only give Ops Pulse access to the Cloudflare resources you want it to inspect.

For example, if you only want it to inspect Worker analytics and logs, scope the token around that.

If you want it to inspect D1-related signals, include the relevant D1 read permissions.

Do not commit your .env.

Do not paste your token into issues, chats, or support threads.

That privacy boundary is now documented more clearly in PRIVACY.md.

Diagnostic assays

I also cleaned up the diagnostic assay documentation.

An assay is just a focused check that asks one operational question.

For example:

Do public/runtime versions agree?
Do MCP clients see the expected tools?
Is cache behavior visible enough to trust?
Was cron expected in this time window?
Is the Worker actually throwing runtime errors?
Enter fullscreen mode Exit fullscreen mode

Each assay should return a simple shape:

  • status
  • reason
  • evidence
  • recommendation

The statuses are intentionally boring:

  • healthy
  • warning
  • degraded
  • unknown

The unknown state is important.

A diagnosis tool should not fake certainty.

If Ops Pulse cannot see enough evidence, it should say that clearly instead of pretending everything is fine.

For example, a cache correctness check should not claim the cache is healthy if cache metadata is not visible in logs. It should explain what is missing and what visibility would be needed to make the call.

That is the kind of behavior I want from the tool generally.

Not dramatic.

Not magical.

Just honest.

What changed in this patch

This was a documentation and onboarding patch, not a feature rewrite.

The latest cleanup added or improved:

  • a clearer README
  • generic setup for non-FreshContext users
  • better quickstart examples
  • environment variable guidance
  • recommended token-permission notes
  • PRIVACY.md
  • docs/ASSAYS.md
  • safer .env.example comments
  • clearer CLI help text

The README now frames Ops Pulse as a local Cloudflare diagnosis CLI first.

My own systems are just the first place I used it seriously.

That matters because the tool should be useful to someone running their own Worker, API, cron job, D1-backed app, feed service, or MCP server.

Who this is for

Ops Pulse is probably useful if you are:

  • running Cloudflare Workers
  • using D1
  • relying on cron schedules
  • checking Workers Observability logs
  • maintaining a small API or feed
  • building an MCP server on Cloudflare
  • debugging alone without a full observability stack
  • trying to tell fresh failures from stale noise

It is especially useful when you want a quick answer before touching code.

Sometimes the right answer is:

Do not edit this Worker.
The errors are old.
Cron was not expected in this window.
This other service is the one to inspect.
Enter fullscreen mode Exit fullscreen mode

That kind of answer can save more time than another graph.

What it is not

Ops Pulse is not auto-remediation.

It does not patch your Workers.

It does not deploy anything.

It does not mutate Cloudflare resources.

It does not replace Cloudflare’s own dashboards.

It is also not trying to be a full observability platform.

The current version is intentionally small:

local CLI
read-only diagnosis
plain-English reports
Enter fullscreen mode Exit fullscreen mode

That is enough for now.

Current status

Ops Pulse is live on npm.

It has crossed a small first signal of interest, with a little over 100 npm downloads at the time I checked.

That is not product-market fit.

But it is enough of a signal to keep polishing the setup, docs, and diagnosis flow.

npm:

https://www.npmjs.com/package/freshcontext-ops-pulse

GitHub:

https://github.com/PrinceGabriel-lgtm/freshcontext-ops-pulse

Try it:

npx freshcontext-ops-pulse --help
Enter fullscreen mode Exit fullscreen mode

Or:

npm install -g freshcontext-ops-pulse
freshops --help
Enter fullscreen mode Exit fullscreen mode

Next

The next useful work is probably still small:

  • better markdown/json output
  • clearer resource selection
  • more diagnostic assays
  • more sample reports
  • a simple setup check
  • stronger examples for non-FreshContext projects

I am trying to keep the direction simple:

Cloudflare metrics in.
Plain-English diagnosis out.
Enter fullscreen mode Exit fullscreen mode

If Ops Pulse helps one other builder avoid chasing stale noise or editing the wrong service, that is already useful.

Top comments (0)