Telemetry protocol

Generated ID of the event, currently expected to be UUID v4.

Timestamp of when the original event was recorded.

Feature associated with the event in camelCase, e.g. 'myFeature'.

Action associated with the event in camelCase, e.g. 'pageView'.

Source of the event.

Parameters of the event.

Optional user associated with the event.

This field should be hydrated by the Sourcegraph server, and not provided

by clients.

Optional feature flags configured in the context of the event.

Optional marketing campaign tracking parameters.

🚨 SECURITY: This metadata is NEVER exported from single-tenant Sourcegraph

instances, and is only exported for events tracked in the public

Sourcegraph.com instance and managed services.

Optional metadata identifying the interaction that generated the event.

Billing product ID associated with the event.

Billing category ID the event falls into.

Evaluated feature flags. In Soucegraph we currently only support boolean

feature flags, but in the API we allow arbitrary string values for future

extensibility.

This field should be hydrated by the Sourcegraph server, and not provided

by clients.

OpenTelemetry trace ID representing the interaction associated with the event.

Custom interaction ID representing the interaction associated with the event.

Geolocation associated with the interaction, typically inferred from the

originating client's IP address (which we do not collect).

Parent interaction ID for tracking nested/sub-agent calls.

Root interaction ID identifying the first interaction in the chain.

If there is no parent, root_interaction_id equals interaction_id.

Session identifier from sourcegraphSessionId cookie, used for

session-level event correlation.

Inferred ISO 3166-1 alpha-2 or alpha-3 country code

URL the event occurred on.

Cohort ID to identify the user as part of a specific A/B test.

Referrer URL that refers the user to Sourcegraph.

URL the user last visited, in their current session.

Most recent referrer URL, in their current session

First URL the user visited, in their current session.

UTM campaign tracking parameters, in their current session.

UTM content tracking parameters, in their current session.

UTM medium tracking parameters, in their current session.

UTM source tracking parameters, in their current session.

UTM term tracking parameters, in their current session.

Version of the event parameters, used for indicating the "shape" of this

event's metadata, beginning at 0. Useful for denoting if the shape of

metadata has changed in any way.

DEPRECATED, legacy metadata format that only accepted int64 - use the new

'metadata' field instead, which accepts float values. Values sent through

this proto field will be merged into the new metadata attributes.

Strictly typed metadata, restricted to integer values to avoid accidentally

exporting sensitive or private data.

Additional potentially sensitive metadata - i.e. not restricted to integer

values.

🚨 SECURITY: This metadata is NOT exported from instances by default, as it

can contain arbitrarily-shaped data that may accidentally contain sensitive

or private contents.

This metadata is only exported on an allowlist basis based on terms of

use agreements and combinations of event feature and action, alongside

careful audit of callsites.

Optional billing-related metadata.

Information about the server that is publishing the event, based on

RecordEventsRequestMetadata.Identifier.

Information about the client that generated the event.

Source client of the event.

Version of the client.

Version of the server emitting the event, corresponding to

RecordEventsRequestMetadata.Identifier. For example, if the Identifier

indicates the publisher is a Sourcegraph instance, the version represents

the version of the Sourcegraph server.

Information about the original client that made the request that triggered

this serverside event.

The user agent of the original client that made the request that triggered

this serverside event.

The name of the original client that made the request that triggered

this serverside event.

The version of the original client that made the request that triggered

this serverside event.

The X-Requested-With header from the original client that made the request

that triggered this serverside event.

The client-reported feature from the original client that made the request

that triggered this serverside event.

Sourcegraph instance database user ID of the user. User IDs are specific to

a Sourcegraph instance, and are not universal across Sourcegraph instances.

We use an int64 as an ID because in Sourcegraph, database user IDs are

always integers.

Randomized unique identifier representing the user (typically stored in

localstorage in web clients, or similar mechanisms elsewhere). This is

often used for unauthenticated users, but can persist to authenticated

users as well.

Sourcegraph Accounts Management System (SAMS) account associated with the

user, represented by a SAMS external user ID in a UUID format. This is only

valid for services leveraging SAMS as an identity provider - in other words,

traditional Sourcegraph instances will not provide this.

Learn more about SAMS: https://handbook.sourcegraph.com/departments/engineering/teams/core-services/sams

A licensed Sourcegraph instance.

An unlicensed Sourcegraph instance.

A service operated and managed by the Sourcegraph team, for example

a service deployed by MSP: https://handbook.sourcegraph.com/departments/engineering/teams/core-services/managed-services/platform/

Valid SAMS client credentials are required to publish events under a

managed service identifier. The required scope is

'telemetry_gateway::events::publish'. See go/sams-client-credentials and

go/sams-token-scopes for more information.

A workspace within a tenant host.

Valid SAMS client credentials are required to publish events under a

workspace identifier. The required scope is

'telemetry_gateway::events::publish'. See go/sams-client-credentials and

go/sams-token-scopes for more information.

License key configured in the Sourcegraph instance emitting the event.

Self-reported Sourcegraph instance identifier.

Instance external URL defined in the instance site configuration.

Self-reported service identifier, for example 'my-service'.

Self-reported service environment, for example 'prod' or 'dev'.

Self-reported Sourcegraph instance identifier.

Instance external URL defined in the instance site configuration.

Self-reported Sourcegraph workspace identifier, for example 'ws_$UUID'.

The workspace's assigned external URL.

Internal ID of the organization from the 'orgs' table.

Name of the organization.

Display name of the organization.

The IDs of users that are members of this organization. We allow a single

repeated set here as the repeated ID-only format should be fairly compact

for realistic scenarios.

Internal ID of the user from the 'users' table.

Username of the user.

Primary email of the user.

Assigned RBAC roles for the user.

Metadata about the events being recorded.

Batch of user metadata to publish in a single message. Clients should aim

to batch large uploads into a series of smaller requests in the RecordEvents

stream, being mindful of common limits in individual message sizes:

https://protobuf.dev/programming-guides/api/#bound-req-res-sizes

🚨 SECURITY: Callers exporting for single-tenant Sourcegraph should always

respect in-instance toggles for what user metadata should be exported.

Batch of organization metadata to publish in a single message. Clients

should aim to batch large uploads into a series of smaller requests in the

RecordEvents stream, being mindful of common limits in individual message

sizes: https://protobuf.dev/programming-guides/api/#bound-req-res-sizes

🚨 SECURITY: Callers exporting for single-tenant Sourcegraph should always

respect in-instance toggles for what user metadata should be exported.

Organization metadata from the 'orgs' table in a Sourcegraph instance.

User metadata from the 'users' table in a Sourcegraph instance.

Client-provided request identifier for diagnostics purposes.

Telemetry publisher self-identification. Only LicensedInstanceIdentifier

and UnlicensedInstanceIdentifier are accepted for this RPC.

Metadata about the events being recorded.

Event to record.

Metadata about the events being recorded.

Batch of events to record in a single request. Clients should aim to

batch large event backlogs into a series of smaller requests in the

RecordEvents stream, being mindful of common limits in individual message

sizes: https://protobuf.dev/programming-guides/api/#bound-req-res-sizes

Client-provided request identifier for diagnostics purposes.

Telemetry publisher self-identification - for example, a Sourcegraph

instance of some other kind of service.

IDs of all events that were successfully recorded in the request.

Note that if succeeded_events is a subset of events that were submitted,

then some events failed to record and should be retried.

RecordEvents streams telemetry events in batches to the Telemetry Gateway

service. Events should only be considered delivered if recording is

acknowledged in RecordEventsResponse.

This is the preferred mechanism for exporting large volumes of events in

bulk.

🚨 SECURITY: Callers exporting for single-tenant Sourcegraph should check

the attributes of the Event type to ensure that only the appropriate fields

are exported, as some fields should only be exported on an allowlist basis.

RecordEvent records a single telemetry event to the Telemetry Gateway service.

If the RPC succeeds, then the event was successfully published.

This RPC currently ONLY accepts events published by ManagedServiceIdentifier,

as this mechanism is intended for low-volume managed services. Higher-volume

use cases should implement a batching mechanism and use the RecordEvents

RPC instead.

🚨 SECURITY: Callers exporting for single-tenant Sourcegraph should check

the attributes of the Event type to ensure that only the appropriate fields

are exported, as some fields should only be exported on an allowlist basis.

PublishInstanceUserMetadata uploads additional user metadata from a

Sourcegraph instance. This matadata is used to enrich recorded events with

attributes that are considered sensitive and thus not part of the RecordEvents

and RecordEvent RPCs.

🚨 SECURITY: Callers exporting for single-tenant Sourcegraph should always

respect in-instance toggles for what user metadata should be exported.