Instrument more of the library/CLI

[BigLep]

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 before implementation (events → metrics, same pattern as #363 / #501).
3. Metrics carry the existing common tags (affordance, network) and reuse the telemetry plumbing from #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:

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 / #501
• Upload golden-path (all copies complete) rate — tracked in #516
• Replacing Sentry error capture — keep errors/traces separate from anonymous metrics

Notes

1. #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 remains source of truth for schema and query recipes.
5. Related: #350 (broader observability context, if still relevant).

[andrianvaleanu]

Adding broad metrics helps, but privacy opt-outs usually mess with your data. This tool https://pulsetic.com/ worksfor uptime.

[BigLep]

Triage comment from 2026 FOC Board Triage (Post GA): we need to instrument filecoin-pin to get more insights into where our customers are getting stuck and how we can unblock them to drive ARR