filecoin-project / filecoin-project/filecoin-pin
Instrument more of the library/CLI
- Dominant language
- TypeScript
- Stars
- 26
- Forks
- 21
- Avg merge
- 5d 18h
- Merged PRs (30d)
- 27
Description
## Done Criteria
1. Additional filecoin-pin surfaces beyond upload are instrumented so maintainers can see **which commands/features are used and how often they succeed or fail**.
2. New metrics are specified in English in [`documentation/events-and-metrics.md`](documentation/events-and-metrics.md) **before** implementation (events → metrics, same pattern as [#363](https://github.com/filecoin-project/filecoin-pin/issues/363) / [#501](https://github.com/filecoin-project/filecoin-pin/pull/501)).
3. Metrics carry the existing common tags (`affordance`, `network`) and reuse the telemetry plumbing from [#501](https://github.com/filecoin-project/filecoin-pin/pull/501) (`configureTelemetry`, BetterStack HTTP ingestion, opt-out paths).
## Why Important
Identify which portions of filecoin-pin are and aren't utilized — e.g. we currently lack visibility into CLI usage for listing data sets, payment setup, session keys, server mode, etc. Upload copy outcomes alone don't tell us how the product is used day-to-day.
## User/Customer
Maintainers
## Scope (initial brainstorm — refine in spec doc)
### CLI / affordance-level metrics
From [#363 discussion](https://github.com/filecoin-project/filecoin-pin/issues/363#issuecomment-4514202570):
| Metric | When emitted | Suggested tags |
|---|---|---|
| `cliAction` (counter) | Once per CLI invocation | `command` (`add`, `import`, `payments`, `data-set`, `server`, …), `status` (`success`, `failure.other`, …), `network`, `affordance: CLI` |
| `cliActionDurationMs` (gauge or histogram) | Start → end of CLI command | Same tags as `cliAction` |
Command-specific tags (only where relevant):
- `add` / `import`: input size (bytes or bucketed MB), maybe CAR vs UnixFS path
- `payments setup`: whether `--auto` was used
- `server`: distinguish start vs long-running (may need a separate event model)
### Surfaces to wire
| Surface | Affordance | Entry point |
|---|---|---|
| CLI | `CLI` | `src/cli.ts` (postAction hook or per-command wrapper) |
| GitHub Action | `GitHub Action` | Already partially covered by upload telemetry; extend if non-upload actions appear |
| Pinning server | `CLI` or new tag? | `src/server.ts` — API routes, pin lifecycle |
| Website | `Website` | Separate PR in filecoin-pin-website after library API stabilizes |
| Library consumers | `Library` | Document patterns; don't auto-instrument unknown hosts |
### Out of scope (for this issue)
- Upload **per-copy** metrics — tracked in [#363](https://github.com/filecoin-project/filecoin-pin/issues/363) / [#501](https://github.com/filecoin-project/filecoin-pin/pull/501)
- Upload **golden-path** (all copies complete) rate — tracked in [#516](https://github.com/filecoin-project/filecoin-pin/issues/516)
- Replacing Sentry error capture — keep errors/traces separate from anonymous metrics
## Notes
1. [#363](https://github.com/filecoin-project/filecoin-pin/issues/363) instrumented the upload flow only; this issue covers everything else.
2. Doc-first: expect discussion on metric names, tag cardinality, and whether duration should be gauge vs histogram before coding.
3. Respect opt-out: `FILECOIN_PIN_TELEMETRY_DISABLED`, `DO_NOT_TRACK`, Action `disableTelemetry`, and `configureTelemetry({ disabled: true })`.
4. README should stay high-level; [`documentation/events-and-metrics.md`](documentation/events-and-metrics.md) remains source of truth for schema and query recipes.
5. Related: [#350](https://github.com/filecoin-project/filecoin-pin/issues/350) (broader observability context, if still relevant).
Contributor guide
Assessment
This issue has not been assessed yet.