Skip to content

Commit 4c1a3b1

Browse files
sergicalsergical
committed
Merge branch 'sergical/docs-deno-vercel-ai' of github.com:getsentry/sentry-docs into sergical/docs-deno-vercel-ai
2 parents 111f75a + b5e33c5 commit 4c1a3b1

File tree

159 files changed

+2282
-1412
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

159 files changed

+2282
-1412
lines changed

‎develop-docs/development-infrastructure/environment/ports.mdx‎

Lines changed: 26 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -8,28 +8,32 @@ The following is a non-exhaustive list of ports used by Sentry services or any d
88
* Finding out why a port is used on your work machine and which process to kill to make it free.
99
* Finding out which ports are probably safe to assign to new services.
1010

11-
| Port | Service | Description
12-
|:-----|:-------------------------------------------|:-----------
13-
| 9000 | Clickhouse | <Link to="/development/devservices/">Devservice</Link> `clickhouse`. Database for Snuba.
14-
| 8123 | Clickhouse |
15-
| 9009 | Clickhouse |
16-
| 3021 | Symbolicator | <Link to="/development/devservices/">Devservice</Link> `symbolicator`. For processing stacktraces.
17-
| 1218 | [Snuba][] | <Link to="/development/devservices/">Devservice</Link> `snuba`. For searching events.
18-
| 1219 | [Snuba][] admin | Not part of devservices setup, but running `snuba admin` will listen on this port.
19-
| 9092 | Kafka | <Link to="/development/devservices/">Devservice</Link> `kafka`. for relay-sentry communication and optionally for sentry-snuba communication
20-
| 6379 | Redis | <Link to="/development/devservices/">Devservice</Link> `redis` (or perhaps installed via Homebrew in rustier setups), responsible for caches, relay projectconfigs and Celery queues
21-
| 5432 | Postgres | <Link to="/development/devservices/">Devservice</Link> `postgres` (or perhaps installed via Homebrew in rustier setups)
22-
| 7899 | [Relay][] | <Link to="/development/devservices/">Devservice</Link> `relay`. Serves APIs for SDKs to send events to (aka event ingestion). Webpack on 8000 reverse-proxies to this server. Starts/stops with `sentry devserver`.
23-
| 8000 | <Link to="/development/environment/">Sentry Dev</Link> | Webpack devserver, routing all ingest paths to Relay, and the rest to uWSGI. Routing is defined in `webpack.config.ts` in Sentry.
24-
| 8001 | uWSGI | Starts/stops with `sentry devserver`. Serves the Django app/API. Webpack on 8000 reverse-proxies to this server. In a siloed devserver, this port is used for control silo.
25-
| 8010 | uWSGI (region silo) | Starts/stops with `sentry devserver --silo=region`. Serves the Django app/API. Webpack on 8000 reverse-proxies to this server.
26-
| 7999 | Sentry frontend prod proxy | For testing local UI changes against a prod API
27-
| 8000 | [Develop docs][] | The website around this document. **Conflicts with Sentry Dev.**
28-
| 3000 | [User docs][] | User-facing documentation. May conflict with Relay if Relay is run outside of devservices.
29-
| 9001 | Sentry Dev Styleguide server | Bound when running `sentry devserver --styleguide`
30-
| 9000 | `sentry run web` | Legacy default port for `sentry run web`, changed to 9001 to avoid conflict with Clickhouse.
31-
| 9001 | `sentry run web` | Barebones frontend without webpack or Relay. <Link to="/development/environment/">Sentry Dev</Link> is likely better. **Conflicts with Sentry Dev Styleguide server.**
32-
| 8000 | [Relay][] mkdocs documentation | At some point this is going to get merged into our existing docs repos. **Conflicts with Sentry Dev.**
11+
| Port | Service | Description
12+
|:------|:-------------------------------------------|:-----------
13+
| 9000 | Clickhouse | <Link to="/development/devservices/">Devservice</Link> `clickhouse`. Database for Snuba.
14+
| 9009 | Clickhouse | <Link to="/development/devservices/">Devservice</Link> `clickhouse`. Database for Snuba.
15+
| 8123 | Clickhouse |
16+
| 9009 | Clickhouse |
17+
| 3021 | Symbolicator | <Link to="/development/devservices/">Devservice</Link> `symbolicator`. For processing stacktraces.
18+
| 1218 | [Snuba][] | <Link to="/development/devservices/">Devservice</Link> `snuba`. For searching events.
19+
| 1219 | [Snuba][] admin | Not part of devservices setup, but running `snuba admin` will listen on this port.
20+
| 9092 | Kafka | <Link to="/development/devservices/">Devservice</Link> `kafka`.
21+
| 9093 | Kafka |
22+
| 6379 | Redis | <Link to="/development/devservices/">Devservice</Link> `redis` (or perhaps installed via Homebrew in rustier setups), responsible for caches, relay projectconfigs and Celery queues
23+
| 5432 | Postgres | <Link to="/development/devservices/">Devservice</Link> `postgres` (or perhaps installed via Homebrew in rustier setups)
24+
| 7899 | [Relay][] | <Link to="/development/devservices/">Devservice</Link> `relay`. Serves APIs for SDKs to send events to (aka event ingestion). Webpack on 8000 reverse-proxies to this server. Starts/stops with `sentry devserver`.
25+
| 8000 | <Link to="/development/environment/">Sentry Dev</Link> | Webpack devserver, routing all ingest paths to Relay, and the rest to uWSGI. Routing is defined in `webpack.config.ts` in Sentry.
26+
| 8001 | uWSGI | Starts/stops with `sentry devserver`. Serves the Django app/API. Webpack on 8000 reverse-proxies to this server. In a siloed devserver, this port is used for control silo.
27+
| 8010 | uWSGI (region silo) | Starts/stops with `sentry devserver --silo=region`. Serves the Django app/API. Webpack on 8000 reverse-proxies to this server.
28+
| 7999 | Sentry frontend prod proxy | For testing local UI changes against a prod API
29+
| 8000 | [Develop docs][] | The website around this document. **Conflicts with Sentry Dev.**
30+
| 3000 | [User docs][] | User-facing documentation. May conflict with Relay if Relay is run outside of devservices.
31+
| 9001 | Sentry Dev Styleguide server | Bound when running `sentry devserver --styleguide`
32+
| 9000 | `sentry run web` | Legacy default port for `sentry run web`, changed to 9001 to avoid conflict with Clickhouse.
33+
| 9001 | `sentry run web` | Barebones frontend without webpack or Relay. <Link to="/development/environment/">Sentry Dev</Link> is likely better. **Conflicts with Sentry Dev Styleguide server.**
34+
| 8000 | [Relay][] mkdocs documentation | At some point this is going to get merged into our existing docs repos. **Conflicts with Sentry Dev.**
35+
| 50051 | Taskbroker | <Link to="/backend/application-domains/tasks/">taskbroker</Link> gRPC interface for taskbroker.
36+
| 8969 | Sentry Spotlight |
3337

3438
## Finding out what's running on your machine
3539

‎develop-docs/frontend/using-rtl.mdx‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,8 @@ router.navigate('/new/path/');
7777
router.navigate(-1); // Simulates clicking the back button
7878
```
7979

80+
### Route Param Values
81+
8082
If you need to test route param values (as in `useParams()`), the `route` will need to be provided in the config:
8183

8284
```tsx
@@ -97,6 +99,106 @@ const {router} = render(<TestComponent />, {
9799
expect(screen.getByText('123')).toBeInTheDocument();
98100
```
99101

102+
### Outlet Context
103+
104+
If you need to test outlet param values (as in `useOutletContext()`), you can pass them inside the `initialRouterConfig` object.
105+
106+
```tsx
107+
function TestComponent() {
108+
const { id } = useOutletContext();
109+
return <div>{id}</div>;
110+
}
111+
112+
const { router } = render(<TestComponent />, {
113+
initialRouterConfig: {
114+
outletContext: { id: '123' },
115+
},
116+
});
117+
118+
expect(screen.getByText('123')).toBeInTheDocument();
119+
```
120+
121+
### Nested Routes
122+
123+
If directly setting outlet context isn't enough, instead you want to render some nested routes you can do that too!
124+
125+
Suppose routes.tsx defines some nested routes like:
126+
```tsx
127+
{
128+
path: 'settings/',
129+
component: SettingsWrapper,
130+
children: [
131+
{index: true, component: SettingsIndex},
132+
{path: ':projectId/', component: ProjectSettings},
133+
]
134+
}
135+
```
136+
137+
We can configure the in-memory router to know about just the route tree that you need. Remember to render the wrapper component itself, and the router + route child components will render themsevles.
138+
```tsx
139+
// settingsWrapper.tsx
140+
interface OutletContext {
141+
name: string;
142+
}
143+
144+
export function useCustomOutletContext() {
145+
return useOutletContext<OutletContext>();
146+
}
147+
148+
export default function SettingsWrapper() {
149+
const context: OutletContext = {name: "Default"};
150+
return <Outlet context={context} />;
151+
}
152+
153+
// settingsIndex.tsx
154+
function SettingsIndex() {
155+
const {name} = useCustomOutletContext();
156+
return <div>Settings > {name}</div>;
157+
}
158+
159+
// projectSettings.tsx
160+
function ProjectSettings() {
161+
const {name} = useCustomOutletContext();
162+
const {projectId} = useParams();
163+
return <div>Settings > {name} > Project: {projectId}</div>;
164+
}
165+
166+
// settingsIndex.spec.tsx
167+
render(<SettingsWrapper />, {
168+
initialRouterConfig: {
169+
location: {
170+
pathname: '/settings/',
171+
},
172+
route: '/settings/',
173+
children: [
174+
{
175+
index: true,
176+
element: <SettingsIndex />,
177+
},
178+
],
179+
},
180+
});
181+
expect(screen.getByText('Settings > Default')).toBeInTheDocument();
182+
183+
// projectSettings.spec.tsx
184+
render(<SettingsWrapper />, {
185+
initialRouterConfig: {
186+
location: {
187+
pathname: '/settings/123/',
188+
},
189+
route: '/settings/:projectId',
190+
children: [
191+
{
192+
path: ':projectId/',
193+
element: <ProjectSettings />,
194+
},
195+
],
196+
},
197+
});
198+
expect(screen.getByText('Settings > Default > Project: 123')).toBeInTheDocument();
199+
```
200+
201+
100202
## Querying
101203

102204
- use `getBy...` as much as possible

‎develop-docs/integrations/github.mdx‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,3 +95,35 @@ github-app.private-key: |
9595
privatekeyprivatekeyprivatekeyprivatekey
9696
-----END RSA PRIVATE KEY-----
9797
```
98+
99+
You can also use a `sentry.conf.py` file to store your configuration as follows:
100+
101+
```python
102+
from sentry.conf.server import SENTRY_OPTIONS
103+
104+
# App ID
105+
SENTRY_OPTIONS["github-app.id"] = GITHUB_APP_ID
106+
# App Name
107+
SENTRY_OPTIONS["github-app.name"] = GITHUB_APP_NAME
108+
# Client ID
109+
SENTRY_OPTIONS["github-app.client-id"] = GITHUB_CLIENT_ID
110+
# Client Secret
111+
SENTRY_OPTIONS["github-app.client-secret"] = GITHUB_CLIENT_SECRET
112+
# Webhook Secret
113+
SENTRY_OPTIONS["github-app.webhook-secret"] = GITHUB_WEBHOOK_SECRET
114+
115+
SENTRY_OPTIONS[
116+
"github-app.private-key"
117+
] = """
118+
-----BEGIN RSA PRIVATE KEY-----
119+
privatekeyprivatekeyprivatekeyprivatekey
120+
privatekeyprivatekeyprivatekeyprivatekey
121+
privatekeyprivatekeyprivatekeyprivatekey
122+
privatekeyprivatekeyprivatekeyprivatekey
123+
privatekeyprivatekeyprivatekeyprivatekey
124+
-----END RSA PRIVATE KEY-----
125+
"""
126+
127+
```
128+
129+
Take note that your private key should be a multiline string without any whitespace before the start of a new line of the key.

‎develop-docs/integrations/heroku.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
---
22
title: Heroku Plugin
3-
sidebar_title: Heroku
3+
sidebar_title: Heroku (Legacy)
44
---
5+
## Deprecation Warning
6+
Heroku plugin is deprecated and will be removed on October 25, 2025. This plugin automatically tracked releases and deployments from your Heroku apps in Sentry, linking them to error tracking and performance monitoring.
7+
You can still use Sentry with Heroku by setting up [Releases](https://docs.sentry.io/product/releases/). Releases let you track versions, commits, crash-free sessions, and more.
58

69
## Create a Heroku application
710

‎develop-docs/integrations/slack/index.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ After you update the `config.yml`, `sentry.conf.py`, or `devlocal.py` you need t
3333

3434
Now that you’ve created your app and updated your Sentry config, you can navigate to __Interactivity & Shortcuts__ under __Features__.
3535

36-
Toggle on __Interactivity__.
36+
Toggle on __Interactivity & Shortcuts__.
3737

3838
Now you’ll be able to enter your **Request URL** (this is the location of your self-hosted Sentry) and **Options Load URL**:
3939

@@ -119,7 +119,7 @@ Navigate to __Slash Commands__ under __Features__. Click __Create New Command__
119119

120120

121121
<Alert title="Note">
122-
When creating the slash command, don’t use `/sentry`. Do something like `/{your_name}-sentry`. If multiple apps are installed with the same slash command, the most recently installed one takes over.
122+
If you're a Sentry employee, when creating the slash command avoid using `/sentry`, try something like `/{your_name}-sentry`. If multiple apps are installed with the same slash command, the most recently installed one takes over.
123123
</Alert>
124124

125125
At the bottom of the page, click __Save__.

‎develop-docs/sdk/platform-specifics/python-sdk/new-major.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: New Major
3+
description: What to consider when preparing a new major.
4+
sidebar_order: 50
5+
---
6+
7+
Even if we decide to make a new major, it's important to prioritize user-friendliness, ease of migration, and backwards compatibility.
8+
9+
Upgrading requires effort. Every major increases the chances of folks staying on an older version forever.
10+
11+
Don't break existing APIs for a minor maintenance benefit on your end.
12+
13+
14+
## Making Migrating Easier
15+
16+
Create a [migration guide](https://docs.sentry.io/platforms/python/migration/). Include easily understandable and copy-pastable examples wherever possible.
17+
18+
Many folks might try to upgrade using AI. Try it out yourself on an example project. Consider adding rules specifically for migrating.
19+
20+
21+
## Dropping Version Support
22+
23+
When making a new major, consider whether we should drop support for an old Python version. There is data in Looker you can use to make an informed decision.
24+
25+
Investigate if we should drop support for old versions of frameworks and libraries. This is not feasible to do by hand as there's too many. For this purpose there is a small script in `scripts/update_integration_support.py` that automatically detects the effective lowest supported version based on our tests and package metadata. You can run the script after removing support for an old Python version, and it should automatically detect which minimum versions are no longer supported.
26+
27+
In order to fully specify the new minimum versions:
28+
- Update `_MIN_VERSIONS` in `sentry_sdk/integrations/__init__.py`
29+
- Update the lower bounds in `extras_require` in `setup.py`, if specified
30+
- Update the documentation pages for the affected integrations (usually, the lowest supported version is mentioned at the bottom)

‎develop-docs/sdk/telemetry/spans/span-protocol.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ Attributes are stored as key-value pairs where each value is an object with type
142142

143143
| Property | Type | Required | Description |
144144
|----------|------|----------|-------------|
145-
| `type` | string | Yes | The data type of the attribute value. Values: `"string"`, `"integer"`, `"float"`, `"boolean"` |
145+
| `type` | string | Yes | The data type of the attribute value. Values: `"string"`, `"integer"`, `"double"`, `"boolean"` |
146146
| `value` | any | Yes | The actual attribute value, must match the specified type |
147147
| `unit` | string | No | The unit of the attribute value. Example values: `"ms"`, `"s"`, `"bytes"`, `"count"`, `"percent"` |
148148

‎develop-docs/sdk/telemetry/traces/index.mdx‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,34 @@ Header Format:
128128

129129
The full spec is available in the [W3C Trace Context](https://www.w3.org/TR/trace-context/) specification.
130130

131+
### `traceIgnoreStatusCodes`
132+
133+
This SHOULD be a collection of integers, denoting HTTP status codes.
134+
If suitable for the platform, the collection MAY also admit pairs of integers, denoting inclusive HTTP status code ranges.
135+
136+
The option applies exclusively to incoming requests, and therefore MUST only be implemented in server SDKs.
137+
138+
The SDK MUST honor this option by inspecting the [`http.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#:~:text=1437-,http.response.status_code,-int) attribute on each transaction/root span before it's finished.
139+
If the value of this attribute matches one of the status codes in `traceIgnoreStatusCodes`, the SDK MUST set the transaction's [sampling decision](https://develop.sentry.dev/sdk/telemetry/traces/#sampling) to `not sampled`.
140+
141+
Note that a prerequisite to implement this option is that every HTTP server integration MUST record the [`http.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#:~:text=1437-,http.response.status_code,-int) attribute as defined in the OTEL spec.
142+
143+
The SDK MUST emit a debug log denoting why the transaction was dropped.
144+
If the SDK implements client reports, it MUST record the dropped transaction with the `event_processor` discard reason.
145+
146+
This option MUST default to an empty collection if it's introduced in a release with a minor SemVer bump.
147+
SDKs SHOULD set the default for this option to the following value (or equivalent if the implementation doesn't admit pairs of integers)
148+
```
149+
[[301, 303], [305, 399], [401, 404]]
150+
```
151+
at the earliest release with a major SemVer bump following its introduction.
152+
153+
The rationale for this option and default is to not consume a user's span quota to trace requests that are useless for debugging purposes (and can often be triggered by scanning bots).
154+
155+
Examples:
156+
`[403, 404]`: don't sample transactions corresponding to requests with status code 403 or 404
157+
`[[300, 399], [401, 404]]`: don't sample transactions corresponding to requests with status codes between 300 and 399 (inclusive) or between 401 and 404 (inclusive)
158+
131159
## `Event` Changes
132160

133161
As of writing, transactions are implemented as an extension of the `Event`

‎docs/cli/releases.mdx‎

Lines changed: 5 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -14,24 +14,17 @@ Because releases work on projects you will need to specify the organization and
1414

1515
## Creating Releases
1616

17-
Releases are created with the `sentry-cli releases new` command. It takes at the very least a version identifier that uniquely identifies the releases. There are a few restrictions -- the release name cannot:
18-
19-
- contain newlines, tabulator characters, forward slashes(/), or back slashes(\\)
20-
- be (in their entirety) period (.), double period (..), or space ( )
21-
- exceed 200 characters
22-
23-
The value can be arbitrary, but for certain platforms, recommendations exist:
24-
25-
- for mobile devices use `package-name@version-number` or `package-name@version-number+build-number`. **Do not** use `VERSION_NUMBER (BUILD_NUMBER)` as the parenthesis are used for display purposes ([email protected]+2 becomes 1.0 (2)), so invoking them will cause an error.
26-
- if you use a DVCS we recommend using the identifying hash (eg: the commit SHA, `da39a3ee5e6b4b0d3255bfef95601890afd80709`). You can let sentry-cli automatically determine this hash for supported version control systems with `sentry-cli releases propose-version`.
27-
- if you tag releases we recommend using the release tag prefixed with a product or package name (for example, `[email protected]`).
17+
Releases are created with the `sentry-cli releases new` command. It takes at the very least a version identifier that uniquely identifies the releases.
2818

2919
```bash
3020
#!/bin/sh
3121
sentry-cli releases new "$VERSION"
3222
```
3323

34-
Releases can also be auto created by different systems. For instance upon uploading a source map a release is automatically created. Likewise releases are created by some clients when an event for a release comes in.
24+
There are some release name restrictions and conventions to be aware of. [Learn more about naming releases](/product/releases/naming-releases/).
25+
26+
Releases can also be auto-created by different systems—for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation.
27+
3528

3629
## Finalizing Releases
3730

0 commit comments

Comments
 (0)