shell: fish functions -> ~/.local/bin executables + bash/zsh ports; manage ~/.agents

- 16 cross-shell utilities converted to sh/bash chezmoi executables:
  ai c2p cp-appid extract_agents fab gdc gh-sonr-org-migrate ghg-clone
  ghn gho git-summary launch_omp_livediff_overlay lc-elir mdcp mdp pj
  (ghg-clone not named ghg: unrelated cargo binary owns that name)
- cwd/history helpers stay per-shell: yy c cd clip-last + ghg/ghn/gho
  cd-wrappers in bash/functions/ and zsh/functions/, loaded by rc files
- fish keeps only shell-state functions; converted ones now hit PATH
- cp-appid ignore gating moved to .local/bin path
- dot_agents/skills: 82 skills materialized from dotstate storage so
  dot_claude skill symlinks resolve on fresh bootstrap; dotstate
  profile/symlinks.json released .agents/skills .bashrc .zshrc
This commit is contained in:
Prad Nukala committed 2026-08-10 15:15:06 -04:00
1 parent 6776366ce6
commit 6406208b35
637 files changed
+100297 -497

No files matched your search

@@ -0,0 +1,89 @@
# Cloudflare Tail Workers
Specialized Workers that consume execution events from producer Workers for logging, debugging, analytics, and observability.
## When to Use This Reference
- Implementing observability/logging for Cloudflare Workers
- Processing Worker execution events, logs, exceptions
- Building custom analytics or error tracking
- Configuring real-time event streaming
- Working with tail handlers or tail consumers
## Core Concepts
### What Are Tail Workers?
Tail Workers automatically process events from producer Workers (the Workers being monitored). They receive:
- HTTP request/response info
- Console logs (`console.log/error/warn/debug`)
- Uncaught exceptions
- Execution outcomes (`ok`, `exception`, `exceededCpu`, etc.)
- Diagnostic channel events
**Key characteristics:**
- Invoked AFTER producer finishes executing
- Capture entire request lifecycle including Service Bindings and Dynamic Dispatch sub-requests
- Billed by CPU time, not request count
- Available on Workers Paid and Enterprise tiers
### Alternative: OpenTelemetry Export
**Before using Tail Workers, consider OpenTelemetry:**
For batch exports to observability tools (Sentry, Grafana, Honeycomb):
- OTEL export sends logs/traces in batches (more efficient)
- Built-in integrations with popular platforms
- Lower overhead than Tail Workers
- **Use Tail Workers only for custom real-time processing**
## Decision Tree
```
Need observability for Workers?
├─ Batch export to known tools (Sentry/Grafana/Honeycomb)?
│ └─ Use OpenTelemetry export (not Tail Workers)
├─ Custom real-time processing needed?
│ ├─ Aggregated metrics?
│ │ └─ Use Tail Worker + Analytics Engine
│ ├─ Error tracking?
│ │ └─ Use Tail Worker + external service
│ ├─ Custom logging/debugging?
│ │ └─ Use Tail Worker + KV/HTTP endpoint
│ └─ Complex event processing?
│ └─ Use Tail Worker + Durable Objects
└─ Quick debugging?
└─ Use `wrangler tail` (different from Tail Workers)
```
## Reading Order
1. **[configuration.md](configuration.md)** - Set up Tail Workers
2. **[api.md](api.md)** - Handler signature, types, redaction
3. **[patterns.md](patterns.md)** - Common use cases and integrations
4. **[gotchas.md](gotchas.md)** - Pitfalls and debugging tips
## Quick Example
```typescript
export default {
async tail(events, env, ctx) {
// Process events from producer Worker
ctx.waitUntil(
fetch(env.LOG_ENDPOINT, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(events),
})
);
}
};
```
## Related Skills
- **observability** - General Workers observability patterns, OTEL export
- **analytics-engine** - Aggregated metrics storage for tail event data
- **durable-objects** - Stateful event processing, batching tail events
- **logpush** - Alternative for batch log export (non-real-time)
- **workers-for-platforms** - Dynamic dispatch with tail consumers