secondsky/claude-skills / plugins/cloudflare-workflows/skills/cloudflare-workflows
cloudflare-workflows
VerifiedCloudflare Workflows for durable long-running execution. Use for multi-step workflows, retries, state persistence, or encountering NonRetryableError, execution failed errors.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.5 KB |
| references/2025-features.md | markdown | 7.9 KB |
| references/common-issues.md | markdown | 9.9 KB |
| references/limits-quotas.md | markdown | 8.7 KB |
| references/metrics-analytics.md | markdown | 11.7 KB |
| references/production-checklist.md | markdown | 11.8 KB |
| references/troubleshooting.md | markdown | 15.1 KB |
| references/workflow-patterns.md | markdown | 15.2 KB |
| references/wrangler-commands.md | markdown | 6.6 KB |
| templates/basic-workflow.ts | script | 3.4 KB |
| templates/circuit-breaker-workflow.ts | script | 12.6 KB |
| templates/parallel-execution-workflow.ts | script | 8.6 KB |
| templates/scheduled-workflow.ts | script | 7.2 KB |
| templates/worker-trigger.ts | script | 6.6 KB |
| templates/workflow-with-events.ts | script | 9.2 KB |
| templates/workflow-with-retries.ts | script | 6.2 KB |
| templates/wrangler-workflows-config.jsonc | other | 3.8 KB |
references/metrics-analytics.md
View on GitHub# Cloudflare Workflows Metrics & Analytics
Comprehensive guide to monitoring, observability, and analytics for Cloudflare Workflows.
## Built-in Monitoring
### Wrangler CLI Monitoring
**List Running Instances**:
```bash
# List all instances
wrangler workflows instances list my-workflow
# Filter by status
wrangler workflows instances list my-workflow --status running
wrangler workflows instances list my-workflow --status errored
wrangler workflows instances list my-workflow --status complete
# Limit results
wrangler workflows instances list my-workflow --limit 50
```
**Instance Details**:
```bash
# Get detailed instance information
wrangler workflows instances describe my-workflow <instance-id>
# Output includes:
# - Instance ID
# - Status (queued, running, paused, complete, errored, terminated)
# - Created timestamp
# - Completed timestamp (if finished)
# - Steps executed
# - Current step (if running)
# - Error details (if errored)
# - Output (if complete)
```
**Real-time Logs**:
```bash
# Stream workflow logs
wrangler tail my-worker --format pretty
# Filter for workflow events
wrangler tail my-worker | grep -E "(Workflow|step|instance)"
```
---
## Custom Metrics Implementation
### Step-Level Metrics
```typescript
import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';
type Env = {
MY_WORKFLOW: Workflow;
ANALYTICS: AnalyticsEngineDataset;
};
type Metrics = {
stepDurations: Record<string, number>;
totalDuration: number;
retryCount: number;
};
export class InstrumentedWorkflow extends WorkflowEntrypoint<Env, any> {
async run(event: WorkflowEvent<any>, step: WorkflowStep) {
const startTime = Date.now();
const metrics: Metrics = {
stepDurations: {},
totalDuration: 0,
retryCount: 0
};
// Instrumented step wrapper
const timedStep = async <T>(
name: string,
fn: () => Promise<T>,
options?: { retries?: { limit: number } }
): Promise<T> => {
const stepStart = Date.now();
const result = await step.do(name, options || {}, fn);
metrics.stepDurations[name] = Date.now() - stepStart;
// Log step completion
console.log(JSON.stringify({
type: 'step_complete',
workflow: 'my-workflow',
instanceId: event.instanceId,
step: name,
duration: metrics.stepDurations[name]
}));
return result;
};
try {
// Use instrumented steps
await timedStep('validate', async () => {
return await validate(event.payload);
});
await timedStep('process', async () => {
return await process(event.payload);
});
await timedStep('complete', async () => {
return await finalize(event.payload);
});
metrics.totalDuration = Date.now() - startTime;
// Write final metrics
this.env.ANALYTICS.writeDataPoint({
blobs: [event.instanceId, 'complete'],
doubles: [metrics.totalDuration],
indexes: ['my-workflow']
});
return { status: 'complete', metrics };
} catch (error) {
metrics.totalDuration = Date.now() - startTime;
this.env.ANALYTICS.writeDataPoint({
blobs: [event.instanceId, 'error', error.message],
doubles: [metrics.totalDuration],
indexes: ['my-workflow']
});
throw error;
}
}
}
```
### Analytics Engine Integration
**Setup Analytics Engine**:
1. Enable in Cloudflare Dashboard > Analytics > Analytics Engine
2. Add binding to wrangler.jsonc:
```jsonc
{
"analytics_engine_datasets": [
{
"binding": "ANALYTICS",
"dataset": "workflow_metrics"
}
]
}
```
**Write Metrics**:
```typescript
// Write workflow completion metric
env.ANALYTICS.writeDataPoint({
blobs: [
instanceId, // blob1: instance identifier
workflowName, // blob2: workflow name
status // blob3: completion status
],
doubles: [
duration, // double1: total duration (ms)
stepCount, // double2: steps executed
retryCount // double3: total retries
],
indexes: [workflowName] // For efficient querying
});
```
**Query Metrics** (via GraphQL API):
```graphql
query WorkflowMetrics($date: Date!) {
viewer {
accounts(filter: { accountTag: "your-account-id" }) {
workflowMetrics: analyticsEngineDatasets(
dataset: "workflow_metrics"
filter: { date: $date }
limit: 1000
) {
dimensions {
blob1 # instanceId
blob2 # workflowName
blob3 # status
}
avg {
double1 # avg duration
}
sum {
double2 # total steps
double3 # total retries
}
count
}
}
}
}
```
---
## Structured Logging
### Log Format Standard
```typescript
interface WorkflowLogEntry {
timestamp: string;
level: 'debug' | 'info' | 'warn' | 'error';
type: 'workflow_start' | 'step_start' | 'step_complete' | 'step_error' | 'workflow_complete' | 'workflow_error';
workflow: string;
instanceId: string;
step?: string;
duration?: number;
error?: {
message: string;
code?: string;
retryable: boolean;
};
metadata?: Record<string, unknown>;
}
function log(entry: WorkflowLogEntry) {
console.log(JSON.stringify({
...entry,
timestamp: entry.timestamp || new Date().toISOString()
}));
}
```
### Example Logging Implementation
```typescript
export class LoggingWorkflow extends WorkflowEntrypoint<Env, Params> {
async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
const workflowName = 'order-processing';
// Log workflow start
log({
level: 'info',
type: 'workflow_start',
workflow: workflowName,
instanceId: event.instanceId,
metadata: { params: event.payload }
});
try {
// Log step start
log({
level: 'debug',
type: 'step_start',
workflow: workflowName,
instanceId: event.instanceId,
step: 'validate'
});
const startTime = Date.now();
const result = await step.do('validate', async () => {
return await validate(event.payload);
});
// Log step complete
log({
level: 'info',
type: 'step_complete',
workflow: workflowName,
instanceId: event.instanceId,
step: 'validate',
duration: Date.now() - startTime
});
// ... more steps
// Log workflow complete
log({
level: 'info',
type: 'workflow_complete',
workflow: workflowName,
instanceId: event.instanceId,
duration: Date.now() - workflowStartTime
});
return result;
} catch (error) {
// Log workflow error
log({
level: 'error',
type: 'workflow_error',
workflow: workflowName,
instanceId: event.instanceId,
error: {
message: error.message,
retryable: !(error instanceof NonRetryableError)
}
});
throw error;
}
}
}
```
---
## External Monitoring Integration
### Logpush to External Services
Configure Cloudflare Logpush for workflow logs:
1. Go to Cloudflare Dashboard > Logs > Logpush
2. Create job for Workers logs
3. Select destination (S3, Datadog, Splunk, etc.)
**Example Datadog Integration**:
```typescript
// Log in Datadog-compatible format
console.log(JSON.stringify({
ddsource: 'cloudflare-workflows',
ddtags: `workflow:${workflowName},env:production`,
hostname: 'cloudflare-workers',
service: workflowName,
status: 'info',
message: `Step ${stepName} completed`,
duration: stepDuration,
workflow: {
instanceId,
step: stepName,
params: event.payload
}
}));
```
### Custom Webhook Notifications
```typescript
async function notifyExternal(event: {
type: string;
workflow: string;
instanceId: string;
data: Record<string, unknown>;
}) {
await fetch('https://your-webhook.com/workflow-events', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
...event,
timestamp: new Date().toISOString(),
source: 'cloudflare-workflows'
})
});
}
// Use in workflow
await step.do('notify start', async () => {
await notifyExternal({
type: 'workflow.started',
workflow: 'order-processing',
instanceId: event.instanceId,
data: { orderId: event.payload.orderId }
});
});
```
---
## Dashboard Queries
### Instance Status Overview
```sql
-- Analytics Engine SQL API (if enabled)
SELECT
blob2 AS workflow_name,
blob3 AS status,
COUNT(*) AS instance_count,
AVG(double1) AS avg_duration_ms,
SUM(double3) AS total_retries
FROM workflow_metrics
WHERE timestamp >= NOW() - INTERVAL '24 hours'
GROUP BY blob2, blob3
ORDER BY instance_count DESC
```
### Error Rate Tracking
```sql
SELECT
blob2 AS workflow_name,
COUNT(*) FILTER (WHERE blob3 = 'error') AS errors,
COUNT(*) FILTER (WHERE blob3 = 'complete') AS successes,
ROUND(
COUNT(*) FILTER (WHERE blob3 = 'error') * 100.0 / COUNT(*),
2
) AS error_rate_pct
FROM workflow_metrics
WHERE timestamp >= NOW() - INTERVAL '1 hour'
GROUP BY blob2
```
### Performance Percentiles
```sql
SELECT
blob2 AS workflow_name,
PERCENTILE_CONT(0.50) WITHIN GROUP (ORDER BY double1) AS p50_ms,
PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY double1) AS p95_ms,
PERCENTILE_CONT(0.99) WITHIN GROUP (ORDER BY double1) AS p99_ms
FROM workflow_metrics
WHERE blob3 = 'complete'
AND timestamp >= NOW() - INTERVAL '24 hours'
GROUP BY blob2
```
---
## Alerting Patterns
### Error Rate Alert
```typescript
// Check error rate periodically
async function checkErrorRate(env: Env, threshold = 5) {
const stats = await getWorkflowStats(env, '1 hour');
const errorRate = (stats.errors / stats.total) * 100;
if (errorRate > threshold) {
await sendAlert({
severity: 'critical',
message: `Workflow error rate ${errorRate.toFixed(1)}% exceeds ${threshold}%`,
workflow: 'order-processing',
metrics: stats
});
}
}
```
### Latency Alert
```typescript
async function checkLatency(env: Env, thresholdMs = 30000) {
const p95 = await getP95Latency(env, '1 hour');
if (p95 > thresholdMs) {
await sendAlert({
severity: 'warning',
message: `Workflow P95 latency ${p95}ms exceeds ${thresholdMs}ms`,
workflow: 'order-processing'
});
}
}
```
### Stuck Instance Detection
```typescript
async function detectStuckInstances(env: Env) {
const instances = await env.MY_WORKFLOW.list();
const stuckThreshold = 60 * 60 * 1000; // 1 hour
const now = Date.now();
for (const instance of instances) {
if (instance.status === 'running') {
const age = now - new Date(instance.created).getTime();
if (age > stuckThreshold) {
await sendAlert({
severity: 'warning',
message: `Instance ${instance.id} running for ${Math.round(age / 60000)} minutes`,
workflow: 'order-processing'
});
}
}
}
}
```
---
## Monitoring Script
Use the included monitoring script:
```bash
# Basic status check
./scripts/benchmark-workflow.sh my-workflow 1
# Performance benchmark
./scripts/benchmark-workflow.sh my-workflow 10
# Output:
# Workflow Benchmark: my-workflow
# ===============================
# Iterations: 10
#
# Results:
# - Min Duration: 1.2s
# - Max Duration: 2.1s
# - Avg Duration: 1.5s
# - Success Rate: 100%
#
# Cost Estimate:
# - Requests: 60 × $0.15/M = $0.000009
# - Duration: 0.015 GB-s × $0.02/M = ~$0
# - Total: ~$0.00001 per run
```
---
## When to Load This Reference
Load this file when:
- Setting up workflow monitoring
- Implementing custom metrics
- Integrating with external monitoring tools
- Creating dashboards for workflow visibility
- Debugging performance issues
- Setting up alerts for workflow health
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |