Telemetry

To help maintainers validate functionality and iron out problems throughout the whole Filecoin Onchain Cloud stack, starting from the SDK, telemetry is temporarily enabled by default for the calibration network in Synapse. We are currently leveraging sentry.io as discussed in issue #328.

How to disable telemetry

There are multiple ways to disable Synapse telemetry:

1. Via Synapse Config:

const synapse = await Synapse.create({
  /* ...existing options... */
  telemetry : { sentryInitOptions : { enabled: false } },
})

2. Set the environment variable SYNAPSE_TELEMETRY_DISABLED=true before instantiating Synapse.

3. Set globalThis.SYNAPSE_TELEMETRY_DISABLED=true before instantiating Synapse.

What is being collected and why

All HTTP calls are being instrumented (except for static assets like JS, CSS, and images), even HTTP calls that originate from outside of Synapse. This was the quickest way to ensure we captured the information we are after.

The primary information we are attempting to collect is HTTP request paths, response status codes, and request/response latencies to RPC providers and Service Providers (SPs). Non 200 responses or “slow” responses may indicate issues in Synapse or the backend SP software, or general operational issues with RPC providers or SPs. These are issues we want to be aware of so we can potentially fix or improve.

We also capture general uncaught errors. This could be indicative of issues in Synapse, which we’d want to fix.

We are not capturing:

• Personal identifiable information (PII). We explicitly disable sending default PII to Sentry.
• Metrics on static asset (e.g., CSS, JS, image) retrieval.

(One can verify these claims in telemetry/service.ts.)

Why is telemetry collecting happening a library like Synapse

Collecting telemetry through Synapse with issue #328 is done as short a term dev-resource efficient decision. In this season of focusing on stability, the goal is to capture request failures and other client-side errors as broadly and quickly as possible so we have an enumeration of the problems and their impact. By setting up telemetry at the Synapse layer, we can broadly get telemetry from some of the first consumers by default without requiring extra on them (e.g., filecoin-pin,filecoin-pin-website, synapse demo websites). This is a short term measure.

How long will Synapse collect telemetry

This broad telemetry at the library/SDK layer will be removed by GA (by end of November 2025). At that point, we’ll do one or more of the following:

1. Reduce telemetry collecting to only be for calls originating from Synapse (not all HTTP calls),
2. Switch the default to opt-in vs. opt-out like it is currently. (Note that currently we only enable telemetry by default for the calibration network. We don’t enable it by default for mainnet.)
3. Remove telemetry entirely out of Synapse, and instead require applications (e.g., filecoin-pin, filecoin-pin-website) to do their telemetry collecting. The tracking issue for this cleanup is issue #363.

How to configure telemetry

Synapse consumers can pass in any Sentry options via Synapse.create({telemetry : { sentryInitOptions : {...} },}).

Synapse default Sentry options are applied in [src/telemetry/service.ts] whenever not explicitly set by the user.

Any explicit tags to add to all Sentry calls can be added with Synapse.create({telemetry : { sentrySetTags : {...} },}).

One also has direct access to the Sentry instance that Synapse is using via synapse.telemetry.sentry, at which point any of the Sentry APIs can be invoked.

Who has access to the telemetry data

Access is restricted to the Synapse maintainers and product/support personnel actively involved in the Filecoin Onchain Cloud who work with Synapse.