belfry-debug
Use Belfry to set up local observability, export OpenTelemetry traces or logs, or debug a Service through bounded searches and exact trace/span/log correlations.
- License 许可
- MIT
- 所属仓库
- endalk200/belfry
- 最近更新
- 2026-10-23
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- belfry-debug
- description
- Use Belfry to set up local observability, export OpenTelemetry traces or logs, or debug a Service through bounded searches and exact trace/span/log correlations.
02 资源文件 3
- 参考文档references/query-api.md7.0 KB
- 参考文档references/setup-and-export.md8.8 KB
- 参考文档references/troubleshooting.md5.4 KB
03 SKILL.md 正文
Belfry
Establish a telemetry handshake, then follow the evidence trail.
Belfry is a local-development workbench. Use its verified Daemon endpoint and bounded Query API; treat the shared SQLite Telemetry Store as an implementation detail. Keep telemetry on loopback and redact sensitive values before export.
1. Establish the Daemon endpoint
Resolve the command before running it:
- In the Belfry source repository, use
bun run belfry --. - Elsewhere, use an installed
belfry.
Run daemon status --json. When it is stopped, run daemon start --json.
Capture the endpoint from the JSON instead of assuming the default port, then
request GET {endpoint}/api/health.
When Belfry is absent, configuration is invalid, the endpoint is unknown, or a target Service is not visible yet, read setup and export completely before changing instrumentation.
Complete this step when the verified endpoint is recorded, live is true,
and the health response establishes whether writerReady and readsAvailable
permit the next operation.
2. Prove the telemetry handshake
Before exercising the target, snapshot GET /api/ingestion/stats. Run one
recognizable operation, flush the enabled exporters, and request the statistics
again. Then list Services over the same time window.
Before the bounded Service request, read the Query API reference completely for time construction, required fields, and cursor rules.
For every enabled signal:
- its accepted-record counter increased;
- rejected/decode counters did not unexpectedly increase;
- the exact Service identity
(namespace, name, environment)appeared.
When a counter or Service does not move, read troubleshooting completely and locate the break before searching wider.
Complete this step when every expected signal is committed and discoverable, or when the first broken layer is identified with health, counter, diagnostic, or exporter evidence.
3. Bound the investigation
Record the symptom, expected behavior, target Service, and the narrowest useful nanosecond window. Preserve exact IDs and timestamps from the failure. Prefer a known trace ID, span ID, log ID, operation, error text, or domain attribute over an unbounded text search.
Use the Query API reference for request payloads,
search projections, and response semantics. Treat
{endpoint}/openapi.json as authoritative when the running version differs
from the reference.
Complete this step when the endpoint, Service Filter, time bounds, and sharpest known identifier are explicit.
4. Follow the evidence trail
Choose the entry point that matches the evidence:
- Trace-first: search traces, select an exact candidate, open its detail, inspect the failing span, then load trace- or span-correlated logs.
- Log-first: search logs, open each relevant log detail, then open its exact trace and span when correlation IDs are present.
- Identity-first: open a known trace, span, or log directly.
For a trace, record its root operation, participating Services, active state,
errors, structural warnings, and spansTruncated. Inspect error spans, events,
links, attributes, resource, scope, and logCount. Use the dedicated span
endpoint when trace detail is truncated or one span needs complete inspection.
For logs, distinguish exact correlation from temporal inference. A shared trace ID, and optionally span ID, is exact. Similar timestamps, text, or attributes without shared IDs are supporting evidence only.
Follow every page while truncated is true. Replay the identical endpoint,
filters, bounds, limit, and sort with only cursor added; signed cursors cannot
be reused with a changed query.
Complete this step when one exact causal path is supported across trace, span, and logs, or every bounded candidate and correlation page is exhausted and the remaining absence is explicit.
5. Report evidence
Report:
- Daemon endpoint and health gates;
- query bounds, filters, sort, and exhausted pages;
- Service identities;
- trace, span, and log IDs with exact nanosecond timestamps;
- ingestion diagnostics or counter deltas relevant to missing data;
- observations, separately labelled hypotheses, and unresolved gaps.
Complete the investigation only when every conclusion cites reported telemetry evidence or is explicitly marked as a hypothesis or unresolved.
04 同仓库更多 Skills
writing-great-skills
Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.
wayfinder
Plan a huge chunk of work — more than one agent session can hold — as a shared map of investigation tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
turborepo
Turborepo monorepo build system guidance. Triggers on: turbo.json, task pipelines, dependsOn, caching, remote cache, the "turbo" CLI, --filter, --affected, CI optimization, environment variables, internal packages, monorepo structure/best practices, and boundaries. Use when user: configures tasks/workflows/pipelines, creates packages, sets up monorepo, shares code between apps, runs changed/affected packages, debugs cache, or has apps/packages directories.
to-tickets
Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker — edges as text in a local file, or native blocking links on a real tracker.
to-spec
Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.
tdd
Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.