You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Third of three ergonomics issues from dogfooding on Stackbilt-dev/tarotscript#163. Siblings: #3 (Span.startChild + Hono middleware), #4 (AsyncLocalStorage active span).
Pain point 1 — Git dep install path is hostile to consumers
This works (the `prepare: tsc` script on the remote builds on install — nice touch, credit where due) but it has several downsides for any user who isn't hand-pinning commit SHAs:
No semver resolution — consumers can't say "give me latest 0.2.x"
No dependabot — breaking upgrades silently accumulate
SSH auth required — CI/CD pipelines without repo access fail to install
Opaque versioning — `v0.2.0` on `package.json` doesn't match any git tag; comparing installed vs latest requires commit inspection
No visible changelog — `npm view` would give consumers a glance at releases; git log is higher-friction
Proposed fix
Publish to npm under `@stackbilt/worker-observability` (scoped, private or public — your call based on whether this is an OSS play or pro-tier-only):
Option A (public): `npm publish --access public` — supports the "platform telemetry for customer workers" positioning. External customers install with standard tooling.
Option B (private): `npm publish` to a private registry or use GitHub Packages — keeps the library Stackbilt-only but still fixes the install UX for internal workers.
Either way, the install line becomes:
```json
"@stackbilt/worker-observability": "^0.2.0"
```
Pain point 2 — No Quickstart, had to read the source
When I started instrumenting tarotscript, the README (if present) didn't show:
The `createMonitoring({ stackbilt: { endpoint, token } })` pattern
The Tracer API (`startTrace` vs `startSpan`, when to call `getContext()`)
The MetricUnit literal type (`'milliseconds' | 'seconds' | 'bytes' | ...`)
How to wire it through Hono with `waitUntil`-based flushing
I had to read `dist/tracing.d.ts`, `dist/metrics.d.ts`, and `src/index.ts` + the `stackbilt-exporter.ts` source to piece together the integration pattern. That's ~45 minutes of friction that every new dogfood target will repeat.
Proposed Quickstart structure
`docs/quickstart-hono.md`:
Install — one command (after npm publishing resolves this)
Get a token — reference stackbilder.com token issuance flow
Emit a metric — `monitoring.metrics.histogram(name, ms, 'milliseconds', tags)`
Verify — hit stackbilder.com/observe?service=, see traces within 30s
Troubleshooting — common errors (403 tenant-cap, 429 budget, missing compat flag for ALS)
Total: 1 page, ~100 lines, copy-pasteable. Target: first trace visible 10 minutes after `npm install`.
Related acceptance
npm publish pipeline documented in CONTRIBUTING.md
`dist/` builds reliably (already does via `prepare: tsc`, keep it working)
Quickstart validated by pointing a new intern at it and having them instrument a toy worker in one sitting
README updated with a link to the quickstart in the first 10 lines
Impact
Together with #3 and #4, this turns worker-observability from "clone this, read the source, figure it out" into "`npm install`, read the quickstart, done." That's the UX bar for any platform the Stackbilt team wants third parties to adopt.
Context
Third of three ergonomics issues from dogfooding on Stackbilt-dev/tarotscript#163. Siblings: #3 (Span.startChild + Hono middleware), #4 (AsyncLocalStorage active span).
Pain point 1 — Git dep install path is hostile to consumers
Today the only install path is:
```json
"@stackbilt/worker-observability": "github:Stackbilt-dev/worker-observability#953a84a73498cb4db71eb889380b0ccf74d28245"
```
This works (the `prepare: tsc` script on the remote builds on install — nice touch, credit where due) but it has several downsides for any user who isn't hand-pinning commit SHAs:
Proposed fix
Publish to npm under `@stackbilt/worker-observability` (scoped, private or public — your call based on whether this is an OSS play or pro-tier-only):
Either way, the install line becomes:
```json
"@stackbilt/worker-observability": "^0.2.0"
```
Pain point 2 — No Quickstart, had to read the source
When I started instrumenting tarotscript, the README (if present) didn't show:
I had to read `dist/tracing.d.ts`, `dist/metrics.d.ts`, and `src/index.ts` + the `stackbilt-exporter.ts` source to piece together the integration pattern. That's ~45 minutes of friction that every new dogfood target will repeat.
Proposed Quickstart structure
`docs/quickstart-hono.md`:
Total: 1 page, ~100 lines, copy-pasteable. Target: first trace visible 10 minutes after `npm install`.
Related acceptance
Impact
Together with #3 and #4, this turns worker-observability from "clone this, read the source, figure it out" into "`npm install`, read the quickstart, done." That's the UX bar for any platform the Stackbilt team wants third parties to adopt.
Related