# Telemetry Gateway 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) - [Event](#telemetrygateway-v1-Event) - [EventBillingMetadata](#telemetrygateway-v1-EventBillingMetadata) - [EventFeatureFlags](#telemetrygateway-v1-EventFeatureFlags) - [EventFeatureFlags.FlagsEntry](#telemetrygateway-v1-EventFeatureFlags-FlagsEntry) - [EventInteraction](#telemetrygateway-v1-EventInteraction) - [EventInteraction.Geolocation](#telemetrygateway-v1-EventInteraction-Geolocation) - [EventMarketingTracking](#telemetrygateway-v1-EventMarketingTracking) - [EventParameters](#telemetrygateway-v1-EventParameters) - [EventParameters.LegacyMetadataEntry](#telemetrygateway-v1-EventParameters-LegacyMetadataEntry) - [EventParameters.MetadataEntry](#telemetrygateway-v1-EventParameters-MetadataEntry) - [EventSource](#telemetrygateway-v1-EventSource) - [EventSource.Client](#telemetrygateway-v1-EventSource-Client) - [EventSource.Server](#telemetrygateway-v1-EventSource-Server) - [EventUser](#telemetrygateway-v1-EventUser) - [Identifier](#telemetrygateway-v1-Identifier) - [Identifier.LicensedInstanceIdentifier](#telemetrygateway-v1-Identifier-LicensedInstanceIdentifier) - [Identifier.ManagedServiceIdentifier](#telemetrygateway-v1-Identifier-ManagedServiceIdentifier) - [Identifier.UnlicensedInstanceIdentifier](#telemetrygateway-v1-Identifier-UnlicensedInstanceIdentifier) - [RecordEventRequest](#telemetrygateway-v1-RecordEventRequest) - [RecordEventResponse](#telemetrygateway-v1-RecordEventResponse) - [RecordEventsRequest](#telemetrygateway-v1-RecordEventsRequest) - [RecordEventsRequest.EventsPayload](#telemetrygateway-v1-RecordEventsRequest-EventsPayload) - [RecordEventsRequestMetadata](#telemetrygateway-v1-RecordEventsRequestMetadata) - [RecordEventsResponse](#telemetrygateway-v1-RecordEventsResponse) - [TelemeteryGatewayService](#telemetrygateway-v1-TelemeteryGatewayService) - [Scalar Value Types](#scalar-value-types)

## telemetrygateway/v1/telemetrygateway.proto ### Event | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | id | [string](#string) | |

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.

| ### EventBillingMetadata | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | product | [string](#string) | |

Billing product ID associated with the event.

Billing category ID the event falls into.

| ### EventFeatureFlags | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | flags | [EventFeatureFlags.FlagsEntry](#telemetrygateway-v1-EventFeatureFlags-FlagsEntry) | repeated |

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.

| ### EventFeatureFlags.FlagsEntry | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | key | [string](#string) | |

| ### EventInteraction | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | trace_id | [string](#string) | optional |

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).

| ### EventInteraction.Geolocation | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | country_code | [string](#string) | |

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

| ### EventMarketingTracking Marketing campaign tracking metadata. 🚨 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. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | url | [string](#string) | optional |

URL the event occurred on.

Initial URL the user landed on.

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

Referrer URL that refers the user to Sourcegraph.

Last source URL visited by the user.

Device session ID to identify the user's session.

Session referrer URL for the user.

First URL the user visited in their current session.

| ### EventParameters | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | version | [int32](#int32) | |

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.

We don't use a [deprecated = true] tag because we use this field to handle

accepting exporters sending metadata in this format.

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.

| ### EventParameters.LegacyMetadataEntry | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | key | [string](#string) | |

| ### EventParameters.MetadataEntry | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | key | [string](#string) | |

| ### EventSource | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | server | [EventSource.Server](#telemetrygateway-v1-EventSource-Server) | |

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

RecordEventsRequestMetadata.Identifier.

Information about the client that generated the event.

| ### EventSource.Client | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | name | [string](#string) | |

Source client of the event.

Version of the client.

| ### EventSource.Server | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | version | [string](#string) | |

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.

| ### EventUser | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | user_id | [int64](#int64) | optional |

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

| ### Identifier | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | licensed_instance | [Identifier.LicensedInstanceIdentifier](#telemetrygateway-v1-Identifier-LicensedInstanceIdentifier) | |

A licensed Sourcegraph instance.

| | unlicensed_instance | [Identifier.UnlicensedInstanceIdentifier](#telemetrygateway-v1-Identifier-UnlicensedInstanceIdentifier) | |

An unlicensed Sourcegraph instance.

| | managed_service | [Identifier.ManagedServiceIdentifier](#telemetrygateway-v1-Identifier-ManagedServiceIdentifier) | |

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.

| ### Identifier.LicensedInstanceIdentifier | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | license_key | [string](#string) | |

License key configured in the Sourcegraph instance emitting the event.

Self-reported Sourcegraph instance identifier.

Instance external URL defined in the instance site configuration.

| ### Identifier.ManagedServiceIdentifier | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | service_id | [string](#string) | |

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

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

| ### Identifier.UnlicensedInstanceIdentifier | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | instance_id | [string](#string) | |

Self-reported Sourcegraph instance identifier.

Instance external URL defined in the instance site configuration.

| ### RecordEventRequest | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | metadata | [RecordEventsRequestMetadata](#telemetrygateway-v1-RecordEventsRequestMetadata) | |

Metadata about the events being recorded.

Event to record.

| ### RecordEventResponse ### RecordEventsRequest | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | metadata | [RecordEventsRequestMetadata](#telemetrygateway-v1-RecordEventsRequestMetadata) | |

Metadata about the events being recorded.

| | events | [RecordEventsRequest.EventsPayload](#telemetrygateway-v1-RecordEventsRequest-EventsPayload) | |

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

| ### RecordEventsRequest.EventsPayload | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | events | [Event](#telemetrygateway-v1-Event) | repeated |

| ### RecordEventsRequestMetadata | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | request_id | [string](#string) | |

Client-provided request identifier for diagnostics purposes.

Telemetry publisher self-identification - for example, a Sourcegraph

instance of some other kind of service.

| ### RecordEventsResponse | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | succeeded_events | [string](#string) | repeated |

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.

| ### TelemeteryGatewayService | Method Name | Request Type | Response Type | Description | | ----------- | ------------ | ------------- | ------------| | RecordEvents | [RecordEventsRequest](#telemetrygateway-v1-RecordEventsRequest) stream | [RecordEventsResponse](#telemetrygateway-v1-RecordEventsResponse) stream |

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 | [RecordEventRequest](#telemetrygateway-v1-RecordEventRequest) | [RecordEventResponse](#telemetrygateway-v1-RecordEventResponse) |

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.

| ## Scalar Value Types | .proto Type | Notes | | ----------- | ----- | | double | | | float | | | int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | | int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | | uint32 | Uses variable-length encoding. | | uint64 | Uses variable-length encoding. | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | | sfixed32 | Always four bytes. | | sfixed64 | Always eight bytes. | | bool | | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | | bytes | May contain any arbitrary sequence of bytes. |