filecoin-project / filecoin-project/filecoin-pin

Instrument more of the library/CLI

Open
#515 2 comments 0 reactions 0 assignees View on GitHub
enhancement ready-for-work team/filecoin-pin team/fs-wg
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.