This guide outlines how to report events directly to Telemetry Gateway from standalone managed services (i.e. services not operated within single-tenant Sourcegraph deployments, and instead operated on something like Managed Services Platform (MSP)).

<aside> ⚠️ This page covers the standalone Telemetry Gateway service and touches on adjacent components only - it does not cover “how to record telemetry” within single-tenant Sourcegraph, which is covered in ‣.

</aside>

Before you start, please read What this service does to get a high-level understanding of how Telemetry Gateway fits into the user event processing system at Sourcegraph (”Telemetry V2”). In particular, note the following diagram exhibiting how the Telemetry Gateway service API is not intended to be the same API developers expose within their services:

flowchart TD
   subgraph Standalone service
   Client -- "Feature, Action, Timestamp, Metadata" --> backend[Service backend]
   internal[Backend] -- "Feature, Action, Metadata" --> backend
   backend -. "Authenticated user, Service version, client-provided fields" .-> api[full Telemetry Gateway Event spec]
   end
   api --> tg[Telemetry Gateway]

Available libraries and SDKs

Telemetry Gateway SDK and API definitions are available in lib/telemetrygateway for external consumption. The library also includes some rudimentary helpers and generated Go bindings for the service API specifications that are also used in single-tenant Sourcegraph.

To authenticate with SAMS service credentials, please refer to SAMS M2M (machine-to-machine) authentication and authorization.

MSP runtime consumers can leverage helper libraries that are part of the MSP runtime:

import (
	sams "github.com/sourcegraph/sourcegraph-accounts-sdk-go"
	"github.com/sourcegraph/sourcegraph-accounts-sdk-go/scopes"

	"github.com/sourcegraph/sourcegraph/lib/managedservicesplatform/runtime/contract"
	"github.com/sourcegraph/sourcegraph/lib/managedservicesplatform/telemetry"
)

type Config struct {
	SAMS struct {
		sams.ConnConfig
		ClientID     string
		ClientSecret string
	}
}

func (Service) Initialize(ctx context.Context, logger log.Logger, ctr runtime.ServiceContract, cfg Config) (background.Routine, error) {
	// ...
	client, err := ctr.Telemetry.NewClient(ctx,	sams.ClientCredentialsTokenSource(
		cfg.SAMS.ConnConfig,
		cfg.SAMS.ClientID,
		cfg.SAMS.ClientSecret,
		[]scopes.Scope{
			// Scope required to write telemetry events to the Telemetry Gateway.
			scopes.ToScope(scopes.ServiceTelemetryGateway, "events", scopes.ActionWrite),
		},
	))
	if err != nil {
		return nil, err
	}
	// Create a recorder for recording serverside events
	recorder := telemetry.NewRecorder(client, ...)
	
	// Record an event!
	_ = recorder.Record("feature", "action", ...)
}

For assistance with building integrations, please reach out to #discuss-core-services.

Integration guidlines

• Services:
  • can expect the Telemetry Gateway V1 API specification to not change in a breaking manner.
  • must provide adhere to all requirements outlined in Telemetry Gateway service API when providing parameters in events export RPCs.
  • must self-identify and authenticate as a “managed service” using SAMS M2M (machine-to-machine) authentication and authorization when exporting events.
  • should provide as many fields as they can when exporting events, such as service versions, client versions, and so on.
  • should report Sourcegraph Accounts Management System (SAMS) external user identifiers in all user events.
• Service implementations:
  • must not expose the entire Telemetry Gateway service API internally (via internal event-recording packages or internal APIs) - instead, only a minimal surface should be exposed, and contextual metadata should only be added in backends (e.g. user IDs, service versions, and so on).
  • should name internal telemetry-recording constructs and mechanisms based on the terms telemetry recorder (noun) and record event (verb).
    • terms like log event should not be be used to avoid confusion with “V1 telemetry”, “security event logging”, standard error logging, and numerous other similarly-named mechanisms.
• Events**:**
  • must provide feature, action, timestamp, and a UUIDv7 event id.
  • must adhere to feature, action naming requirement of ^[a-z][a-zA-Z-\\\\.]+$
  • should use appropriately categorised values for feature and action to describe events
  • should provide interaction details such as a relevant trace ID

<aside> 💡

Naming and data conventions outlined in ‣ also apply in general for managed services.

</aside>