chore: improve telemetry docs/collecting (#192)

* chore: improve telemetry docs/collecting

This is intended to finish off #153

* chore: fix disable code snippet

* chore: remove whitespace from README.md

* fix: set telemetry appName for cli & upload-action

* test: fix sentry init expectation

* Apply suggestion from @BigLep

* fix: initializeSynapse uses synapse telemetry config

* fix: filecoin-pinning-server sets sentry appName

* chore: lint fix

* deps: update synapse-sdk

* fix: use constant for cli telemetry appName

---------

Co-authored-by: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>

Author: BigLep

README.md

@@ -34,7 +34,7 @@ Filecoin Pin offers multiple affordances to integrate Filecoin storage into your
 Upload IPFS files directly to Filecoin via the command line. Perfect for developers who want to integrate Filecoin storage into scripts, workflows, or local development environments.
 
 - **Repository**: This repo ([filecoin-project/filecoin-pin](https://github.com/filecoin-project/filecoin-pin))
-- **Documentation**: 
+- **Documentation**:
   - Run `filecoin-pin --help` to see all available commands and options.
   - [CLI Walkthrough](https://docs.filecoin.io/builder-cookbook/filecoin-pin/filecoin-pin-cli)
 - **Installation**: `npm install -g filecoin-pin`
@@ -43,7 +43,7 @@ Upload IPFS files directly to Filecoin via the command line. Perfect for develop
 Automatically publish websites or build artifacts to IPFS and Filecoin as part of your CI/CD pipeline. Ideal for static websites, documentation sites, and automated deployment workflows.
 
 - **Repository**: This repo ([see upload-action/](./upload-action))
-- **Documentation**: 
+- **Documentation**:
    - [GitHub Action Walkthrough](https://docs.filecoin.io/builder-cookbook/filecoin-pin/github-action)
 - **Example in Production**: [filecoin-pin-website CI pipeline](https://github.com/filecoin-project/filecoin-pin-website/tree/main/.github/workflows)
 
@@ -59,13 +59,13 @@ Run a localhost IPFS Pinning Service API server that implements the [IPFS Pinnin
 
 - **Repository**: This repo (`filecoin-pin server` command in CLI)
 - **Usage**: `PRIVATE_KEY=0x... npx filecoin-pin server`
-- **Status**: Works and is tested, but hasn't received as many features as the CLI.  If it would benefit your usecase, please comment on [tracking issue](https://github.com/filecoin-project/filecoin-pin/issues/46) so we can be better informed when it comes to prioritizing.  
+- **Status**: Works and is tested, but hasn't received as many features as the CLI.  If it would benefit your usecase, please comment on [tracking issue](https://github.com/filecoin-project/filecoin-pin/issues/46) so we can be better informed when it comes to prioritizing.
 
 ### Management Console GUI
 Web-based management console for monitoring and managing your Filecoin Pin deployments.  This is effectively a Web UI equivalent to the [CLI](#cli).
 
 - **Status**: Planned
-- **Tracking**: See [issue #74](https://github.com/filecoin-project/filecoin-pin/issues/74) for updates.  Please leave a comment about your usecase if this would be particularly beneficial.  
+- **Tracking**: See [issue #74](https://github.com/filecoin-project/filecoin-pin/issues/74) for updates.  Please leave a comment about your usecase if this would be particularly beneficial.
 
 ## Examples
 
@@ -98,6 +98,24 @@ The [Synapse SDK](https://synapse.filecoin.services/) is the main library, as it
 
 The affordances were [discussed more above](#affordances).  All affordances use the same core library, ensuring consistent behavior and making it easy to add new interfaces in the future.
 
+## Telemetry
+
+Filecoin Pain collects telemetry.  A few things:
+* Telemetry always [has a way to be disabled](#how-to-disable-telemetry).
+* We don't collect Personal identifiable information (PII).
+* With our [end user affordance](#affordances) we expect to make telemetry on by default, requiring a consumer/user to opt out.  We are defaulting as "enabled" to help make sure we have a good pulse on the user experience and can address issues correctly.
+* In this [pre-v1 season](https://github.com/filecoin-project/filecoin-pin/issues/187), we are particularly focused on helping maintainers validate functionality and iron out problems throughout the whole Filecoin Onchain Cloud stack that `filecoin-pin` relies on.  We're piggy-backing on the underlying telemetry setup/system of Synapse, which uses sentry.io.  The telemetry we get from synapse-sdk is more invasive than we'd do if just setting it up for [Filecoin Pin affordances](#affordances), but this was the most resource efficient way to be able to get a pulse on what errors are happening where in the stack.
+* Learn more at the Synapse telemetry docs ([docs site](https://synapse.filecoin.services/guides/telemetry/), [github](https://github.com/FilOzone/synapse-sdk/blob/master/docs/src/content/docs/guides/telemetry.md)).
+
+### How to disable telemetry
+Telemetry can be disabled in JS with:
+
+```typescript
+const synapse = await initializeSynapse({ ...synapseConfig, telemetry: { sentryInitOptions: { enabled: false } } }, logger)
+```
+
+If using a different affordance like the CLI or example GitHub Action, then the following telemetry can be disabled by environment variable.  Because filecoin-pin telemetry is tied to synapse's telemetry currently, see the Synapse telemetry docs ([docs site](https://synapse.filecoin.services/guides/telemetry/#how-to-disable-telemetry), [github](https://github.com/FilOzone/synapse-sdk/blob/master/docs/src/content/docs/guides/telemetry.md#how-to-disable-telemetry)) for how to do this.
+
 ## Quick Start
 
 ### Prerequisites

package.json

@@ -97,7 +97,7 @@
   "homepage": "https://github.com/filecoin-project/filecoin-pin#readme",
   "dependencies": {
     "@clack/prompts": "^0.11.0",
-    "@filoz/synapse-sdk": "^0.35.1",
+    "@filoz/synapse-sdk": "^0.35.2",
     "@helia/unixfs": "^6.0.1",
     "@ipld/car": "^5.4.2",
     "commander": "^14.0.1",

src/add/add.ts

@@ -9,6 +9,7 @@ import { readFile, stat } from 'node:fs/promises'
 import pc from 'picocolors'
 import pino from 'pino'
 import { warnAboutCDNPricingLimitations } from '../common/cdn-warning.js'
+import { TELEMETRY_CLI_APP_NAME } from '../common/constants.js'
 import { displayUploadResults, performAutoFunding, performUpload, validatePaymentSetup } from '../common/upload-flow.js'
 import {
   cleanupSynapseService,
@@ -112,7 +113,10 @@ export async function runAdd(options: AddOptions): Promise<AddResult> {
     if (withCDN) config.withCDN = true
 
     // Initialize just the Synapse SDK
-    const synapse = await initializeSynapse(config, logger)
+    const synapse = await initializeSynapse(
+      { ...config, telemetry: { sentrySetTags: { appName: TELEMETRY_CLI_APP_NAME } } },
+      logger
+    )
     const network = synapse.getNetwork()
 
     spinner.stop(`${pc.green('✓')} Connected to ${pc.bold(network)}`)

src/common/constants.ts

@@ -2,3 +2,5 @@
  * Minimum runway in days to ensure WarmStorage can cover costs. Used when `--auto-fund` is passed to import or add commands
  */
 export const MIN_RUNWAY_DAYS = 30
+
+export const TELEMETRY_CLI_APP_NAME = 'filecoinPinCli'

src/core/synapse/index.ts

@@ -65,17 +65,17 @@ interface BaseSynapseConfig {
   warmStorageAddress?: string | undefined
   withCDN?: boolean | undefined
   /**
-   * Telemetry configuration, merges fields, but appends "appName" to the existing appName
+   * Telemetry configuration.
+   * Defaults to enabled unless explicitly disabled.
    * @example
    * {
    *   sentryInitOptions: {
-   *     enabled: true,
+   *     enabled: false, // if want to disable telemetry.
    *   },
    *   sentrySetTags: {
    *     appName: "${your-app-name}",
    *   },
    * }
-   * will result in your appName being "filecoin-pin@v1.0.0-${your-app-name}"
    */
   telemetry?: TelemetryConfig
 }
@@ -312,11 +312,7 @@ async function setupSessionKey(synapse: Synapse, sessionWallet: Wallet, logger:
  * @param logger - Logger instance for detailed operation tracking
  * @returns Initialized Synapse instance
  */
-export async function initializeSynapse(
-  config: Partial<SynapseSetupConfig>,
-  logger: Logger,
-  telemetryConfig?: TelemetryConfig
-): Promise<Synapse> {
+export async function initializeSynapse(config: Partial<SynapseSetupConfig>, logger: Logger): Promise<Synapse> {
   try {
     const authMode = validateAuthConfig(config)
 
@@ -340,9 +336,7 @@ export async function initializeSynapse(
     if (config.warmStorageAddress) {
       synapseOptions.warmStorageAddress = config.warmStorageAddress
     }
-    if (telemetryConfig) {
-      synapseOptions.telemetry = getTelemetryConfig(telemetryConfig)
-    }
+    synapseOptions.telemetry = getTelemetryConfig(config.telemetry)
 
     let synapse: Synapse
 

src/core/synapse/telemetry-config.ts

@@ -3,11 +3,6 @@ import type { TelemetryConfig } from '@filoz/synapse-sdk'
 import packageJson from '../../../package.json' with { type: 'json' }
 
 export const getTelemetryConfig = (config?: TelemetryConfig | undefined): TelemetryConfig => {
-  let appName = `${packageJson.name}@v${packageJson.version}`
-  if (config?.sentrySetTags?.appName != null) {
-    appName = `${appName}-${String(config.sentrySetTags.appName)}`
-  }
-
   return {
     ...config,
     sentryInitOptions: {
@@ -17,7 +12,7 @@ export const getTelemetryConfig = (config?: TelemetryConfig | undefined): Teleme
     },
     sentrySetTags: {
       ...config?.sentrySetTags,
-      appName, // use constructed appName, always.
+      filecoinPinVersion: `${packageJson.name}@v${packageJson.version}`,
     },
   }
 }

src/data-set/run.ts

@@ -1,6 +1,7 @@
 import type { EnhancedDataSetInfo, ProviderInfo, Synapse } from '@filoz/synapse-sdk'
 import { PDPServer, PDPVerifier, WarmStorageService } from '@filoz/synapse-sdk'
 import pc from 'picocolors'
+import { TELEMETRY_CLI_APP_NAME } from '../common/constants.js'
 import { cleanupSynapseService, initializeSynapse } from '../core/synapse/index.js'
 import { getCLILogger, parseCLIAuth } from '../utils/cli-auth.js'
 import { cancel, createSpinner, intro, outro } from '../utils/cli-helpers.js'
@@ -189,7 +190,10 @@ export async function runDataSetCommand(
     })
 
     const logger = getCLILogger()
-    synapse = await initializeSynapse(authConfig, logger)
+    synapse = await initializeSynapse(
+      { ...authConfig, telemetry: { sentrySetTags: { appName: TELEMETRY_CLI_APP_NAME } } },
+      logger
+    )
     const network = synapse.getNetwork()
     const client = synapse.getClient()
     const address = await client.getAddress()

src/filecoin-pinning-server.ts

@@ -38,6 +38,11 @@ export async function createFilecoinPinningServer(
     {
       ...config,
       privateKey: config.privateKey,
+      telemetry: {
+        sentrySetTags: {
+          appName: 'filecoinPinIPFSPinningServer',
+        },
+      },
     },
     logger,
     providerOptions

src/import/import.ts

@@ -12,6 +12,7 @@ import { CID } from 'multiformats/cid'
 import pc from 'picocolors'
 import pino from 'pino'
 import { warnAboutCDNPricingLimitations } from '../common/cdn-warning.js'
+import { TELEMETRY_CLI_APP_NAME } from '../common/constants.js'
 import { displayUploadResults, performAutoFunding, performUpload, validatePaymentSetup } from '../common/upload-flow.js'
 import {
   cleanupSynapseService,
@@ -182,7 +183,10 @@ export async function runCarImport(options: ImportOptions): Promise<ImportResult
     if (withCDN) config.withCDN = true
 
     // Initialize just the Synapse SDK
-    const synapse = await initializeSynapse(config, logger)
+    const synapse = await initializeSynapse(
+      { ...config, telemetry: { sentrySetTags: { appName: TELEMETRY_CLI_APP_NAME } } },
+      logger
+    )
     const network = synapse.getNetwork()
 
     spinner.stop(`${pc.green('✓')} Connected to ${pc.bold(network)}`)

src/payments/auto.ts

@@ -8,6 +8,7 @@
 
 import { ethers } from 'ethers'
 import pc from 'picocolors'
+import { TELEMETRY_CLI_APP_NAME } from '../common/constants.js'
 import {
   calculateDepositCapacity,
   checkAndSetAllowances,
@@ -56,7 +57,10 @@ export async function runAutoSetup(options: PaymentSetupOptions): Promise<void>
     })
 
     const logger = getCLILogger()
-    const synapse = await initializeSynapse(authConfig, logger)
+    const synapse = await initializeSynapse(
+      { ...authConfig, telemetry: { sentrySetTags: { appName: TELEMETRY_CLI_APP_NAME } } },
+      logger
+    )
     const network = synapse.getNetwork()
     const client = synapse.getClient()
     const address = await client.getAddress()