FreshContext Ops Pulse

Cloudflare metrics in. Plain-English diagnosis out.

What Is Ops Pulse?

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

It turns raw Cloudflare signals into plain-English status, evidence, and recommendations.

It was built while stabilizing FreshContext, but it can be used with any Cloudflare Workers project.

Ops Pulse helps answer:

• Is this Worker actually broken?
• Is it just idle?
• Was cron expected in this window?
• Are errors fresh or old?
• Are external calls noisy but not fatal?
• What should I inspect first?
• What should I avoid touching?

Who Is It For?

• solo builders running Cloudflare Workers
• people with D1-backed APIs
• MCP server maintainers
• feed/API builders
• small teams without a full observability stack
• developers who want local diagnosis before adding dashboards

Quickstart

From a local checkout:

npm install
npm run build
npm run dev -- --help
npm run dev -- report --hours 1
npm run dev -- logs --worker my-worker --hours 1
npm run dev -- assays

Package-style commands after installing the package or using the packed tarball:

npx freshcontext-ops-pulse --help
npx freshcontext-ops-pulse report --hours 1
npx freshcontext-ops-pulse logs --worker my-worker --hours 1
npx freshcontext-ops-pulse assays

Global install is supported by the CLI package shape:

npm install -g freshcontext-ops-pulse
freshops --help

The package is not published by this repository workflow. Use the local checkout until you intentionally publish or install from a local package artifact.

Environment Variables

Create a local .env from .env.example:

cp .env.example .env

Set:

CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_API_TOKEN=

Optional resource selection:

CLOUDFLARE_WORKERS=my-worker,my-cron-worker
CLOUDFLARE_D1_DATABASES=my-database

Your Cloudflare token stays local. Do not commit .env, do not paste tokens into issues/chats/logs, and use the narrowest permissions that let the commands you need read metrics.

Recommended Cloudflare Token Permissions

Based on the current implementation, useful permissions include:

• Account: Account Analytics:Read for GraphQL Analytics API.
• Account: D1:Read for D1 database lookup and D1 analytics support.
• Account: Workers Scripts:Read for Cron Trigger schedule lookup.
• Account: Workers Observability:Write for the current Workers Observability telemetry query endpoint.

Exact permissions may depend on which commands you run and how Cloudflare exposes analytics for your account. Start with the minimum read-only permissions needed for Workers analytics/logs and D1 read access. The Observability telemetry query API currently documents a write-scoped permission even though Ops Pulse only reads/query logs.

Using Ops Pulse With Your Own Cloudflare Project

Ops Pulse does not require FreshContext.

Point it at your own Workers and databases through environment variables, then inspect specific windows:

freshops report --hours 1
freshops logs --worker my-worker --hours 1
freshops errors --worker my-worker --hours 24
freshops workers --hours 6
freshops d1 --hours 24

Use your Cloudflare token permissions to control what Ops Pulse can read.

Current configuration is environment-variable based. A richer config file for named projects, expected assay targets, and default windows is planned.

FreshContext Preset / Example

FreshContext was the first real system Ops Pulse was used on.

Default Workers:

• freshcontext-mcp
• fresh-hn-feed
• fresh-jobs-feed

Default D1 databases:

• fresh-hn-feed-db
• fresh-jobs-feed-db

Override these defaults with CLOUDFLARE_WORKERS and CLOUDFLARE_D1_DATABASES.

Commands

npm run dev -- report --hours 24
npm run dev -- workers --hours 24
npm run dev -- d1 --hours 24
npm run dev -- errors --worker freshcontext-mcp --hours 24
npm run dev -- logs --hours 24
npm run dev -- assays
npm run dev -- daily --hours 24
npm run dev -- report --mock

Flags:

• --hours 24
• --worker freshcontext-mcp
• --json
• --mock

Diagnostic Assays

npm run dev -- assays
npm run dev -- assays --worker freshcontext-mcp --hours 1

Assays are small read-only checks that return status, reason, evidence, and recommendation. See docs/ASSAYS.md.

Currently implemented:

• Cache Correctness: limited by Workers Observability visibility; returns unknown when cache fields are not visible.
• Version Consistency: FreshContext-specific probe against the default health endpoint.
• Tool Discovery: FreshContext-specific MCP initialize and tools/list probe.

Planned/generic assays are documented in docs/ASSAYS.md rather than presented as fully implemented.

API Surfaces

Implemented:

• Cloudflare GraphQL Analytics API for Worker metrics via workersInvocationsAdaptive.
• Cloudflare GraphQL Analytics API for D1 metrics via d1AnalyticsAdaptiveGroups.
• Cloudflare D1 REST API to resolve configured database names to database IDs.
• Cloudflare Worker Cron schedules REST API via /workers/scripts/{script_name}/schedules.
• Best-effort Cloudflare GraphQL scheduled invocation query via workersInvocationsScheduled.
• Workers Observability telemetry API via /workers/observability/telemetry/query.

The CLI fails gracefully when a query shape, permission, or dataset is unavailable. It reports the limitation in Notes instead of inventing data. Mock output is only used when --mock is passed.

Privacy

Ops Pulse is local-first and uses your Cloudflare credentials from your local environment. See PRIVACY.md.

Known Limitations

• Worker CPU and wall-time quantile fields are discovered with GraphQL introspection. If Cloudflare rejects those fields, the CLI retries without them and notes that p90/p95 timing was unavailable.
• D1 analytics filters use database IDs. The CLI resolves configured names through the D1 REST API, so D1:Read is needed.
• Cron "last seen" uses best-effort GraphQL scheduled invocation data. If unavailable, the report still lists configured schedules when the REST schedule endpoint works.
• Workers Observability query field names can vary by account data shape. Logs/errors degrade to notes if Cloudflare rejects a filter.
• Assay probes are partly FreshContext-specific today; generic assay target configuration is planned.
• No hosted dashboard, browser login, deployment, Slack/email delivery, billing, or third-party AI/API calls are included.

References

• GraphQL Analytics API: https://developers.cloudflare.com/analytics/graphql-api/
• Worker metrics GraphQL tutorial: https://developers.cloudflare.com/analytics/graphql-api/tutorials/querying-workers-metrics/
• D1 metrics and analytics: https://developers.cloudflare.com/d1/observability/metrics-analytics/
• Workers Observability telemetry query API: https://developers.cloudflare.com/api/resources/workers/subresources/observability/subresources/telemetry/methods/query/
• Cron Trigger schedule API: https://developers.cloudflare.com/api/resources/workers/subresources/scripts/subresources/schedules/methods/get/