Skip to content

docs+release: publish to npm + ship Quickstart for Hono workers #5

@stackbilt-admin

Description

@stackbilt-admin

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:

  • 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`:

  1. Install — one command (after npm publishing resolves this)
  2. Get a token — reference stackbilder.com token issuance flow
  3. Wire middleware — copy-paste Hono snippet (5 lines after ergonomics: Span.startChild() + Hono-aware middleware helper #3 lands)
  4. Instrument a phase — copy-paste `rootSpan.startChild()` snippet (3 lines after ergonomics: Span.startChild() + Hono-aware middleware helper #3 lands)
  5. Emit a metric — `monitoring.metrics.histogram(name, ms, 'milliseconds', tags)`
  6. Verify — hit stackbilder.com/observe?service=, see traces within 30s
  7. 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.

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions