From 1c8a1479b3e9bde55da9196f7f27ece6e311ae03 Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Wed, 18 Feb 2026 21:11:05 +0100 Subject: [PATCH 1/2] docs(sdk): merge basics.mdx into overview.mdx Consolidate SDK development basics (local Relay setup, consulting existing SDKs, conventions before shipping, Discord) into the SDK overview page to create a single "getting started with SDK development" resource. Co-Authored-By: Claude --- develop-docs/sdk/foundations/overview.mdx | 56 +++++++++++++++++++++ develop-docs/sdk/processes/basics.mdx | 61 ----------------------- redirects.js | 6 ++- 3 files changed, 61 insertions(+), 62 deletions(-) delete mode 100644 develop-docs/sdk/processes/basics.mdx diff --git a/develop-docs/sdk/foundations/overview.mdx b/develop-docs/sdk/foundations/overview.mdx index e2ad968efbe5a..1d954221f06d0 100644 --- a/develop-docs/sdk/foundations/overview.mdx +++ b/develop-docs/sdk/foundations/overview.mdx @@ -4,6 +4,10 @@ description: What an SDK is, what it does, and how end-users interact with it. sidebar_order: 1 --- + + This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. + + ## Writing an SDK At its core an SDK is a set of utilities for capturing data about an exceptional state in an application. Given this data, it then builds and sends a JSON payload to the Sentry server. @@ -89,3 +93,55 @@ a basic message or exception: - `Sentry.captureMessage(message)` - `Sentry.captureException(exception)` + +## Run a Local Relay + +You do not need a local Sentry for SDK development but you will want to run a local +[relay](https://docs.sentry.io/product/relay/). The reason for this is that Sentry's +main ingestion endpoint is not intended for development but for high throughput +production use. What this means is that a lot of the event processing is happening +after the event has already been accepted by the system so you won't be able to see +errors when sending the HTTP request. + +If you haven't used relay yet, have a look at the [getting started](https://docs.sentry.io/product/relay/getting-started/) +docs for relay. Once installed you will want to turn up the log level in your +`.relay/config.yml` file: + +```yaml +logging: + level: trace +``` + +Make sure your relay is running whenever you're doing development: + +```shell +relay run +``` + +When sending events just substitute `orgXXX.ingest.sentry.io` with `localhost:3000` or +whichever port you ended up choosing. Also note that a local relay will out of the box +be available via HTTP only so don't try to send HTTPS requests there. + +## Consult Existing SDKs + +While we're trying to keep the docs up to date about all important things, it's usually +a good idea to refer to already existing Sentry SDKs for input. In particular the +transport design is not part of the documentation but generally quite similar between +SDKs. + +## Define Conventions and Types Before Shipping + +Before shipping new or changed SDK behavior, make sure the relevant definitions exist outside your SDK first: + +- **Semantic conventions:** New or changed attributes **MUST** first be defined in [sentry-conventions](https://github.com/getsentry/sentry-conventions/). If the convention you need doesn't exist yet, open a PR there to propose it. Only after the convention has been merged should you implement it in an SDK. This ensures all SDKs use consistent naming and semantics. + + The merge process for sentry-conventions PRs: + 1. Open a PR with the proposed convention. + 2. Get an approval from at least one code owner. + 3. Wait at least 3 business days after the first approval to give other code owners a chance to review. + +- **Context types:** Any newly added [context](https://develop.sentry.dev/sdk/foundations/data-model/event-payloads/contexts/) **SHOULD** also be typed out in [Relay](https://github.com/getsentry/relay/tree/master/relay-event-schema/src/protocol/contexts) so that the schema stays in sync with what SDKs emit. + +## Join us on Discord + +You can reach out to Sentry open source contributors and talk with other SDK maintainers on the [Sentry Discord server](https://discord.gg/sentry). diff --git a/develop-docs/sdk/processes/basics.mdx b/develop-docs/sdk/processes/basics.mdx deleted file mode 100644 index 4dcdc03b59eb3..0000000000000 --- a/develop-docs/sdk/processes/basics.mdx +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Basics -description: So you want to develop an SDK? Before you get started here are some basics that are worth following to have a better experience. -sidebar_order: 1 ---- - - - This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. - - -## Run a Local Relay - -You do not need a local Sentry for SDK development but you will want to run a local -[relay](https://docs.sentry.io/product/relay/). The reason for this is that Sentry's -main ingestion endpoint is not intended for development but for high throughput -production use. What this means is that a lot of the event processing is happening -after the event has already been accepted by the system so you won't be able to see -errors when sending the HTTP request. - -If you haven't used relay yet, have a look at the [getting started](https://docs.sentry.io/product/relay/getting-started/) -docs for relay. Once installed you will want to turn up the log level in your -`.relay/config.yml` file: - -```yaml -logging: - level: trace -``` - -Make sure your relay is running whenever you're doing development: - -```shell -relay run -``` - -When sending events just substitute `orgXXX.ingest.sentry.io` with `localhost:3000` or -whichever port you ended up choosing. Also note that a local relay will out of the box -be available via HTTP only so don't try to send HTTPS requests there. - -## Consult Existing SDKs - -While we're trying to keep the docs up to date about all important things, it's usually -a good idea to refer to already existing Sentry SDKs for input. In particular the -transport design is not part of the documentation but generally quite similar between -SDKs. - -## Define Conventions and Types Before Shipping - -Before shipping new or changed SDK behavior, make sure the relevant definitions exist outside your SDK first: - -- **Semantic conventions:** New or changed attributes **MUST** first be defined in [sentry-conventions](https://github.com/getsentry/sentry-conventions/). If the convention you need doesn't exist yet, open a PR there to propose it. Only after the convention has been merged should you implement it in an SDK. This ensures all SDKs use consistent naming and semantics. - - The merge process for sentry-conventions PRs: - 1. Open a PR with the proposed convention. - 2. Get an approval from at least one code owner. - 3. Wait at least 3 business days after the first approval to give other code owners a chance to review. - -- **Context types:** Any newly added [context](https://develop.sentry.dev/sdk/foundations/data-model/event-payloads/contexts/) **SHOULD** also be typed out in [Relay](https://github.com/getsentry/relay/tree/master/relay-event-schema/src/protocol/contexts) so that the schema stays in sync with what SDKs emit. - -## Join us on Discord - -You can reach out to Sentry open source contributors and talk with other SDK maintainers on the [Sentry Discord server](https://discord.gg/sentry). diff --git a/redirects.js b/redirects.js index 3cdbb29814e61..2be844b8699ef 100644 --- a/redirects.js +++ b/redirects.js @@ -44,7 +44,11 @@ const developerDocsRedirects = [ }, { source: '/sdk/basics/:path*', - destination: '/sdk/processes/basics/:path*', + destination: '/sdk/foundations/overview/', + }, + { + source: '/sdk/processes/basics/:path*', + destination: '/sdk/foundations/overview/', }, { source: '/sdk/data-handling/:path*', From f70cb9df7ebcbb922f972e371e04b13abb050c1f Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Thu, 19 Feb 2026 11:31:55 +0100 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Alex Krawiec --- develop-docs/sdk/foundations/overview.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/develop-docs/sdk/foundations/overview.mdx b/develop-docs/sdk/foundations/overview.mdx index 1d954221f06d0..b7f95634dd0c1 100644 --- a/develop-docs/sdk/foundations/overview.mdx +++ b/develop-docs/sdk/foundations/overview.mdx @@ -96,7 +96,7 @@ a basic message or exception: ## Run a Local Relay -You do not need a local Sentry for SDK development but you will want to run a local +You do not need a local Sentry instance for SDK development, but you will want to run a local [relay](https://docs.sentry.io/product/relay/). The reason for this is that Sentry's main ingestion endpoint is not intended for development but for high throughput production use. What this means is that a lot of the event processing is happening @@ -119,7 +119,7 @@ relay run ``` When sending events just substitute `orgXXX.ingest.sentry.io` with `localhost:3000` or -whichever port you ended up choosing. Also note that a local relay will out of the box +whichever port you chose. Also note that a local relay will out of the box be available via HTTP only so don't try to send HTTPS requests there. ## Consult Existing SDKs