mirror of
https://github.com/sourcegraph/sourcegraph.git
synced 2026-02-06 18:51:59 +00:00
doc: add notes that new telemetry docs only apply to some events (#58316)
In 5.2.1, we've rolled out a new telemetry export framework and associated docs, but not all events use it yet - this change adds disclaimers that the new content does not apply to a lot of existing events. Migrations are being tracked by the analytics team. In most cases, there isn't an equivalent reference for the existing events, particularly Cody extension events, so I haven't added any links. There's a discussion about this in [this thread](https://sourcegraph.slack.com/archives/C04MSD3DP5L/p1699627360154729). I also made a few misc updates to other sections to hopefully improve the wording and clarity a bit.
This commit is contained in:
Robert Lin
GitHub
parent
47d275e616
commit
704449488f
@ -12,6 +12,9 @@ If you have any questions about telemetry collection, please reach out to your S
|
||||
|
||||
<span class="badge badge-note">Sourcegraph 5.2.1+</span>
|
||||
|
||||
> WARNING: This section refers to a new system for collecting telemetry introduced in Sourcegraph 5.2.1, and only applies to telemetry that has been migrated to use this new system.
|
||||
> Certain Sourcegraph components - namely [Cody editor extensions](../../cody/index.md) - will continue to use a legacy mechanism for reporting telemetry directly to Sourcegraph.com until the migration is complete.
|
||||
|
||||
Sourcegraph instances 5.2.1 and later collect telemetry events to understand usage patterns and help improve the product. Telemetry events can be generated when certain user actions occur, like opening files or performing searches. This data helps us provide the highest level of support to Sourcegraph's customers.
|
||||
|
||||
Sensitive data/PII exfiltration, intentional or not, is a significant concern to Sourcegraph that we take very seriously.
|
||||
|
||||
@ -10,6 +10,8 @@ In the [lifecycle of an event](./index.md#event-lifecycle), events are first [st
|
||||
|
||||
See [testing events](./index.md#testing-events) for a summary of how to observe your events during development.
|
||||
|
||||
> WARNING: This page primarily pertains to the new telemetry system introduced in Sourcegraph 5.2.1 - refer to [DEPRECATED: Telemetry](deprecated.md) for the legacy system which may still be in use if a callsite has not been migrated yet.
|
||||
|
||||
## Storing events
|
||||
|
||||
Once [recorded](./index.md#recording-events), telemetry events are stored in two places:
|
||||
|
||||
@ -12,6 +12,8 @@ There are currently two ways to log product telemetry:
|
||||
|
||||
All usages of old telemetry mechanisms should be migrated to the new framework.
|
||||
|
||||
> WARNING: This page primarily pertains to the new system introduced in Sourcegraph 5.2.1 - refer to [DEPRECATED: Telemetry](deprecated.md) for the legacy system which may still be in use if a callsite has not been migrated yet.
|
||||
|
||||
- [Why a new framework and APIs?](#why-a-new-framework-and-apis)
|
||||
- [Event lifecycle](#event-lifecycle)
|
||||
- [Recording events](#recording-events)
|
||||
@ -28,7 +30,7 @@ All usages of old telemetry mechanisms should be migrated to the new framework.
|
||||
|
||||
The new telemetry framework and API aims to address the following issues:
|
||||
|
||||
- The existing `event_logs` parameters are arbitrarily shaped - to provide stronger guarantees against accidentally exporting sensitive data, the new APIs enforce stricter requirements - see [recording events](#recording-events) for more details.
|
||||
- The existing `event_logs` parameters are arbitrarily shaped - to provide stronger guarantees against accidentally exporting sensitive data, the new APIs enforce stricter requirements, such as numeric metadata - see [recording events](#recording-events) for more details.
|
||||
- The shape of existing `event_logs` have grown organically over time without a clear structured schema.
|
||||
Callsites must construct full events on their own, and we cannot easily prune event objects of potentially [sensitive attributes](#sensitive-attributes) before export.
|
||||
|
||||
@ -49,22 +51,42 @@ See [telemetry export architecture](./architecture.md) for more details.
|
||||
|
||||
## Recording events
|
||||
|
||||
Note that recording APIs are intentionally stricter and have a smaller surface area than [the full events we end up exporting](#exported-event-schema).
|
||||
This is to help prevent accidental export of sensitive data, and to make it clear what properties should be injected in a uniform manner instead of being constructed ad-hoc by callers - see [event lifecycle](#event-lifecycle) for details.
|
||||
Recording events can be done via recording APIs available on each of the platforms documented below:
|
||||
|
||||
- [Clients](#clients): web app, extensions, etc.
|
||||
- [Backend services](#backend-services)
|
||||
|
||||
Note that:
|
||||
|
||||
- Recording APIs are intentionally stricter and have a smaller surface area than [the full events we end up exporting](#exported-event-schema). This make it clear what properties should be injected in a uniform manner serverside instead of being constructed ad-hoc by callers - see [event lifecycle](#event-lifecycle) for details.
|
||||
- Metadata that gets exported by default only accepts numeric values. This offers a guard against accidentally exporting sensitive data. Arbitrarily shaped metadata can be collected, but not exported, via the `additionalMetadata` parameter - see [sensitive attributes](#sensitive-attributes).
|
||||
- An escape hatch to export arbitrarily shaped metadata is available via an instance-side allowlist - see [sensitive attributes](#sensitive-attributes).
|
||||
|
||||
### Clients
|
||||
|
||||
Clients (web apps, extensions, etc) should use [`@sourcegraph/telemetry`](https://github.com/sourcegraph/telemetry), providing client-specific metadata and implementation for exporting to a Sourcegraph instance's `mutation { telemetry { recordEvent(...) }}` GraphQL mutation.
|
||||
[sourcegraph/cody#1192](https://github.com/sourcegraph/cody/pull/1192) is a pull request demonstrating how to integrate `@sourcegraph/telemetry` into a client by extending specific classes and providing backing implementations for various interfaces.
|
||||
|
||||
#### VS Code
|
||||
#### Cody extensions
|
||||
|
||||
##### VS Code
|
||||
|
||||
Event-recording development documentation for the VS Code extension is available in [`sourcegraph/cody/vscode/CONTRIBUTING.md`'s "Telemetry events" section](https://github.com/sourcegraph/cody/blob/main/vscode/CONTRIBUTING.md#telemetry-events).
|
||||
|
||||
#### Sourcegraph web app
|
||||
##### Cody Agent
|
||||
|
||||
> WARNING: Not yet available, coming soon!
|
||||
|
||||
#### Sourcegraph web app
|
||||
|
||||
A shared event recorder for web app components is available in the platform context type, under `(PlatformContext).telemetryRecorder`:
|
||||
|
||||
```ts
|
||||
import type { PlatformContext } from '@sourcegraph/shared/src/platform/context'
|
||||
```
|
||||
|
||||
In the web app, if a component has `PlatformContext` available, the `telemetryRecorder` instance can be used directly - otherwise, it can be prop-drilled in from the closest parent component with `PlatformContext` available.
|
||||
|
||||
### Backend services
|
||||
|
||||
In the backend, events are recorded using `EventRecorder` instances created from the `internal/telemetry/telemetryrecorder` package. For example:
|
||||
@ -134,7 +156,6 @@ There are two core attributes in events that are considered potentially sensitiv
|
||||
- Certain events may be allowlisted to have this field exported - this is defined in [`internal/telemetry/sensitiviemetadataallowlist`](https://github.com/sourcegraph/sourcegraph/blob/main/internal/telemetry/sensitivemetadataallowlist/sensitiviemetadataallowlist.go). Adding events to this list requires review and approval from Legal.
|
||||
- `marketingTracking`: this field tracks a lot of properties around URLs visited and marketing tracking that may contain sensitive data. This is only exported from the [Sourcegraph.com](https://sourcegraph.com/search) instance.
|
||||
|
||||
|
||||
## Testing events
|
||||
|
||||
In summary, when adding your events in the new telemetry framework, you can verify events are being recorded by:
|
||||
|
||||
@ -8,6 +8,8 @@
|
||||
|
||||
This page contains generated documentation for telemetry event data that gets exported to Sourcegraph from individual Sourcegraph instances.
|
||||
|
||||
> WARNING: This page primarily pertains to the new telemetry system introduced in Sourcegraph 5.2.1 - refer to [DEPRECATED: Telemetry](deprecated.md) for the legacy system which may still be in use if a callsite has not been migrated yet.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [telemetrygateway/v1/telemetrygateway.proto](#telemetrygateway_v1_telemetrygateway-proto)
|
||||
|
||||
@ -8,6 +8,8 @@
|
||||
|
||||
This page contains generated documentation for telemetry event data that gets exported to Sourcegraph from individual Sourcegraph instances.
|
||||
|
||||
> WARNING: This page primarily pertains to the new telemetry system introduced in Sourcegraph 5.2.1 - refer to [DEPRECATED: Telemetry](deprecated.md) for the legacy system which may still be in use if a callsite has not been migrated yet.
|
||||
|
||||
## Table of Contents
|
||||
{{range .Files}}
|
||||
{{$file_name := .Name}}- [{{.Name}}](#{{.Name | anchor}})
|
||||
|
||||
Loading…
Reference in New Issue
Block a user