refactor: bring our own telemtry

see FilOzone/synapse-sdk#363

Author: juliangruber

README.md

@@ -105,23 +105,17 @@ 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
+## CLI Telemetry
 
-Filecoin Pain collects telemetry.  A few things:
+Filecoin Pin's CLI 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)).
+* 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. 
 
-### How to disable telemetry
-Telemetry can be disabled in JS with:
+### How to disable CLI telemetry
 
-```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.
+Set the environment variable `FILECOIN_PIN_TELEMETRY_DISABLED=true`.
 
 ## Quick Start
 

package.json

@@ -117,6 +117,7 @@
     "@filoz/synapse-sdk": "^0.36.1",
     "@helia/unixfs": "^7.0.0",
     "@ipld/car": "^5.4.2",
+    "@sentry/node": "^10.35.0",
     "commander": "^14.0.1",
     "ethers": "^6.15.0",
     "fastify": "^5.6.0",

src/add/add.ts

@@ -9,7 +9,6 @@ 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 { normalizeMetadataConfig } from '../core/metadata/index.js'
 import {
@@ -45,7 +44,10 @@ async function validatePath(
     if (stats.isDirectory()) {
       // Check if bare flag is used with directory
       if (options.bare) {
-        return { exists: false, error: `--bare flag is not supported for directories` }
+        return {
+          exists: false,
+          error: `--bare flag is not supported for directories`,
+        }
       }
       return { exists: true, stats, isDirectory: true }
     }
@@ -57,7 +59,10 @@ async function validatePath(
       return { exists: false, error: `Path not found: ${path}` }
     }
     // Other errors like permission denied, etc.
-    return { exists: false, error: `Cannot access path: ${path} (${error?.message || 'unknown error'})` }
+    return {
+      exists: false,
+      error: `Cannot access path: ${path} (${error?.message || 'unknown error'})`,
+    }
   }
 }
 
@@ -122,18 +127,17 @@ export async function runAdd(options: AddOptions): Promise<AddResult> {
     if (withCDN) config.withCDN = true
 
     // Initialize just the Synapse SDK
-    const synapse = await initializeSynapse(
-      { ...config, telemetry: { sentrySetTags: { appName: TELEMETRY_CLI_APP_NAME } } },
-      logger
-    )
+    const synapse = await initializeSynapse(config, logger)
     const network = synapse.getNetwork()
 
     spinner.stop(`${pc.green('✓')} Connected to ${pc.bold(network)}`)
 
     // Check payment setup (may configure permissions if needed)
     // Actual CAR size will be checked later
     spinner.start('Checking payment setup...')
-    await validatePaymentSetup(synapse, 0, spinner, { suppressSuggestions: true })
+    await validatePaymentSetup(synapse, 0, spinner, {
+      suppressSuggestions: true,
+    })
 
     // Create CAR from file or directory
     const packingMsg = isDirectory

src/cli.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import './instrument.js'
 import { Command } from 'commander'
 import pc from 'picocolors'
 

src/common/constants.ts

@@ -2,5 +2,3 @@
  * 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

@@ -8,13 +8,11 @@ import {
   type StorageServiceOptions,
   Synapse,
   type SynapseOptions,
-  type TelemetryConfig,
 } from '@filoz/synapse-sdk'
 import { type Provider as EthersProvider, JsonRpcProvider, type Signer, Wallet, WebSocketProvider } from 'ethers'
 import type { Logger } from 'pino'
 import { ADDRESS_ONLY_SIGNER_SYMBOL, AddressOnlySigner } from './address-only-signer.js'
 import { DEFAULT_DATA_SET_METADATA, DEFAULT_STORAGE_CONTEXT_CONFIG } from './constants.js'
-import { getTelemetryConfig } from './telemetry-config.js'
 
 export * from './constants.js'
 
@@ -46,7 +44,7 @@ export interface Config {
 /**
  * Common options for all Synapse configurations
  */
-interface BaseSynapseConfig extends Omit<SynapseOptions, 'withCDN' | 'warmStorageAddress' | 'telemetry'> {
+interface BaseSynapseConfig extends Omit<SynapseOptions, 'withCDN' | 'warmStorageAddress'> {
   /** RPC endpoint for the target Filecoin network. Defaults to calibration. */
   rpcUrl?: string | undefined
   /** Optional override for WarmStorage contract address */
@@ -56,20 +54,6 @@ interface BaseSynapseConfig extends Omit<SynapseOptions, 'withCDN' | 'warmStorag
   withCDN?: boolean | undefined
   /** Default metadata to apply when creating or reusing datasets */
   dataSetMetadata?: Record<string, string>
-  /**
-   * Telemetry configuration.
-   * Defaults to enabled unless explicitly disabled.
-   * @example
-   * {
-   *   sentryInitOptions: {
-   *     enabled: false, // if want to disable telemetry.
-   *   },
-   *   sentrySetTags: {
-   *     appName: "${your-app-name}",
-   *   },
-   * }
-   */
-  telemetry?: TelemetryConfig
 }
 
 /**
@@ -353,7 +337,11 @@ async function setupSessionKey(synapse: Synapse, sessionWallet: Wallet, logger:
   }
 
   logger.info(
-    { event: 'synapse.session_key.verified', createExpiry: createDataSetExpiry, addExpiry: addPiecesExpiry },
+    {
+      event: 'synapse.session_key.verified',
+      createExpiry: createDataSetExpiry,
+      addExpiry: addPiecesExpiry,
+    },
     'Session key verified'
   )
 
@@ -374,7 +362,7 @@ async function setupSessionKey(synapse: Synapse, sessionWallet: Wallet, logger:
  * @returns Initialized Synapse instance
  */
 export async function initializeSynapse(config: Partial<SynapseSetupConfig>, logger: Logger): Promise<Synapse> {
-  const { withCDN, warmStorageAddress, telemetry, ...restConfig } = config
+  const { withCDN, warmStorageAddress, ...restConfig } = config
   try {
     const authMode = validateAuthConfig(config)
 
@@ -399,7 +387,6 @@ export async function initializeSynapse(config: Partial<SynapseSetupConfig>, log
     if (warmStorageAddress) {
       synapseOptions.warmStorageAddress = warmStorageAddress
     }
-    synapseOptions.telemetry = getTelemetryConfig(telemetry)
 
     let synapse: Synapse
 
@@ -445,7 +432,10 @@ export async function initializeSynapse(config: Partial<SynapseSetupConfig>, log
         throw new Error('Internal error: signer mode but config type mismatch')
       }
 
-      synapse = await Synapse.create({ ...synapseOptions, signer: config.signer })
+      synapse = await Synapse.create({
+        ...synapseOptions,
+        signer: config.signer,
+      })
       activeProvider = synapse.getProvider()
       setAuthMode(synapse, 'signer')
     } else {
@@ -454,7 +444,10 @@ export async function initializeSynapse(config: Partial<SynapseSetupConfig>, log
         throw new Error('Internal error: private key mode but config type mismatch')
       }
 
-      synapse = await Synapse.create({ ...synapseOptions, privateKey: config.privateKey })
+      synapse = await Synapse.create({
+        ...synapseOptions,
+        privateKey: config.privateKey,
+      })
       activeProvider = synapse.getProvider()
       setAuthMode(synapse, 'standard')
     }
@@ -522,7 +515,10 @@ export async function createStorageContext(
     if (options?.dataset?.useExisting != null) {
       sdkOptions.dataSetId = options.dataset.useExisting
       logger?.info?.(
-        { event: 'synapse.storage.dataset.existing', dataSetId: options.dataset.useExisting },
+        {
+          event: 'synapse.storage.dataset.existing',
+          dataSetId: options.dataset.useExisting,
+        },
         'Connecting to existing dataset'
       )
     } else if (options?.dataset?.createNew === true) {
@@ -595,13 +591,19 @@ export async function createStorageContext(
     if (options?.providerAddress) {
       sdkOptions.providerAddress = options.providerAddress
       logger?.info?.(
-        { event: 'synapse.storage.provider_override', providerAddress: options.providerAddress },
+        {
+          event: 'synapse.storage.provider_override',
+          providerAddress: options.providerAddress,
+        },
         'Overriding provider by address'
       )
     } else if (options?.providerId != null && Number.isFinite(options.providerId)) {
       sdkOptions.providerId = options.providerId
       logger?.info?.(
-        { event: 'synapse.storage.provider_override', providerId: options.providerId },
+        {
+          event: 'synapse.storage.provider_override',
+          providerId: options.providerId,
+        },
         'Overriding provider by ID'
       )
     }
@@ -761,11 +763,6 @@ export async function cleanupProvider(provider: any): Promise<void> {
  * and allow the process to terminate
  */
 export async function cleanupSynapseService(): Promise<void> {
-  // Close telemetry to flush pending events and shutdown cleanly
-  if (synapseInstance) {
-    await synapseInstance.telemetry?.sentry?.close()
-  }
-
   if (activeProvider) {
     await cleanupProvider(activeProvider)
   }

src/core/synapse/telemetry-config.ts

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

src/filecoin-pinning-server.ts

@@ -12,7 +12,6 @@ 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 { normalizeMetadataConfig } from '../core/metadata/index.js'
 import {
@@ -57,7 +56,11 @@ async function validateCarFile(filePath: string): Promise<CID[]> {
  * Resolve the root CID from CAR file roots
  * Handles multiple cases: no roots, single root, multiple roots
  */
-function resolveRootCID(roots: CID[]): { cid: CID; cidString: string; message?: string } {
+function resolveRootCID(roots: CID[]): {
+  cid: CID
+  cidString: string
+  message?: string
+} {
   if (roots.length === 0) {
     // No roots - use zero CID
     return {
@@ -115,7 +118,10 @@ async function validateFilePath(filePath: string): Promise<{ exists: boolean; st
       return { exists: false, error: `File not found: ${filePath}` }
     }
     // Other errors like permission denied, etc.
-    return { exists: false, error: `Cannot access file: ${filePath} (${error?.message || 'unknown error'})` }
+    return {
+      exists: false,
+      error: `Cannot access file: ${filePath} (${error?.message || 'unknown error'})`,
+    }
   }
 }
 
@@ -192,10 +198,7 @@ export async function runCarImport(options: ImportOptions): Promise<ImportResult
     if (withCDN) config.withCDN = true
 
     // Initialize just the Synapse SDK
-    const synapse = await initializeSynapse(
-      { ...config, telemetry: { sentrySetTags: { appName: TELEMETRY_CLI_APP_NAME } } },
-      logger
-    )
+    const synapse = await initializeSynapse(config, logger)
     const network = synapse.getNetwork()
 
     spinner.stop(`${pc.green('✓')} Connected to ${pc.bold(network)}`)

src/import/import.ts

@@ -0,0 +1,17 @@
+import Sentry from '@sentry/node'
+import { name as packageName, version as packageVersion } from './core/utils/version.js'
+
+// Ensure to call this before requiring any other modules!
+Sentry.init({
+  dsn: 'https://9TMHhmfsi93WgHaMSXoQ2qhQ@s1685337.us-east-9.betterstackdata.com/1685337',
+  // Setting this option to false will prevent the SDK from sending default PII data to Sentry.
+  // For example, automatic IP address collection on events
+  sendDefaultPii: false,
+  // Enable tracing/performance monitoring
+  tracesSampleRate: 1.0, // Capture 100% of transactions for development (adjust in production)
+  enabled: process.env.FILECOIN_PIN_TELEMETRY_DISABLED !== 'true',
+})
+
+Sentry.setTags({
+  filecoinPinVersion: `${packageName}@v${packageVersion}`,
+})